Skip to content

YAML with Schema

A developer can choose to additionally validate the input that a user gives in a YAML file through a schema. For more information on the version of schema that is implemented here, see the documentation.

Here is an example of a schema file for the above example.

$schema: "http://json-schema.org/draft-04/schema#"

type: object

properties:
        meta:
                type: string
        fun:
                type: bool

A schema must contain a link to the original definition, here given as a link, and a description of each variable. In this case, the schema is simple. It is describing an object with two properties (variables), meta, and fun. It succinctly gives the expected type declaration for these variables, which can be validated at run time.

To include this in the above report with yamldoc, set the -s flag.

yamldoc test/yaml/basic.yaml -s test/schema/basic.schema

Which outputs:

Configuration Parameters Reference

Any information about this page goes here.

Key Value Type Information
meta "Data" string Here is some meta data.
fun True bool And here is some more split over a couple of
lines.

Generated by yamldoc v0.1.2 on 2020-10-06

The difference between these two reports is the inclusion of the Type column.

Modifying the Title and Description

Though the title and description of this page can easily be edited after it is generated, we also include a special declaration in the schema file to modify these easily.

Edit the schema file from before and add the following lines:

$schema: "http://json-schema.org/draft-04/schema#"

_yamldoc_title: My Awesome Title
_yamldoc_description: This can be a long string or paragraph talking about your parameters and describing how to use them. You can use line breaks too, you just have to write them manually.<br><br> Isn't that cool?

type: object

properties:
        meta:
                type: string
        fun:
                type: bool

Which gives

My Awesome Title

This can be a long string or paragraph talking about your parameters and describing how to use them. You can use line breaks too, you just have to write them manually.

Isn't that cool?

Key Value Type Information
meta "Data" string Here is some meta data.
fun True bool And here is some more split over a couple of
lines.

Generated by yamldoc v0.1.2 on 2020-10-06