YAML Schema

YAML Schema is a small extension to JSON Schema Draft 4 that adds some features specific to YAML. Understanding JSON Schema provides a good resource for understanding how to use JSON Schema, and further resources are available at json-schema.org. A working understanding of JSON Schema is assumed for this section, which only describes what makes YAML Schema different from JSON Schema.

Writing a new schema is described in Designing a new tag and schema.

Note

The YAML Schema currently does not require either the id or tag keywords. The id keyword is not included in the YAML Schema since it is actually inherited from the base JSON Schema standard. However, it may become mandatory in a future version of the YAML Standard. The tag keyword may also eventually become mandatory, although the motivation for this is somewhat weaker.

YAML Schema

Description

A metaschema extending JSON Schema’s metaschema to add support for some YAML-specific constructions.

Outline

Schema Definitions

This node must validate against all of the following:

  • This type is an object with the following properties:
    • tag
      string
      A fully-qualified YAML tag name that should be associated with the object type returned by the YAML parser; for example, the object must be an instance of the class registered with the parser to create instances of objects with this tag. Implementation of this validator is optional and depends on details of the YAML parser.

      Minimum length: 6
    • propertyOrder
      array
      Specifies the default order of the properties when writing out. Any keys not listed in propertyOrder will be in arbitrary order at the end. This field applies only to nodes with object type.

      No length restriction
      Items in the array are restricted to the following types:
      string
      No length restriction
    • flowStyle
      string
      Specifies the default serialization style to use for an array or object. YAML supports multiple styles for arrays/sequences and objects/maps, called “block style” and “flow style”. For example:

      Block style: !!map
        Clark : Evans
        Ingy  : döt Net
        Oren  : Ben-Kiki
      
      Flow style: !!map { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }
      

      This property gives a hint to the tool outputting the YAML which style to use. If not provided, the library is free to use whatever heuristics it wishes to determine the output style. This property does not enforce any particular style on YAML being parsed.

      No length restriction
      Only the following values are valid for this node:
      • block
      • flow
    • style
      string
      Specifies the default serialization style to use for a string. YAML supports multiple styles for strings:

      Inline style: "First line\nSecond line"
      
      Literal style: |
        First line
        Second line
      
      Folded style: >
        First
        line
      
        Second
        line
      

      This property gives a hint to the tool outputting the YAML which style to use. If not provided, the library is free to use whatever heuristics it wishes to determine the output style. This property does not enforce any particular style on YAML being parsed.

      No length restriction
      Only the following values are valid for this node:
      • inline
      • literal
      • folded
    • examples
      array
      A list of examples to help document the schema. Each pair is a prose description followed by a string containing YAML content. For example:

      examples:
        -
          - Complex number: 1 real, -1 imaginary
          - "!complex 1-1j"
            type: array
            items:
      
      No length restriction
      Items in the array are restricted to the following types:
      array
      No length restriction
      The first 2 items in the list must be the following types:
        string
        No length restriction

        This node must validate against any of the following:

        • string
          No length restriction
        • object

Original Schema

%YAML 1.1
---
$schema: "http://json-schema.org/draft-04/schema"
id: "http://stsci.edu/schemas/yaml-schema/draft-01"
title:
  YAML Schema
description: |
  A metaschema extending JSON Schema's metaschema to add support for
  some YAML-specific constructions.
allOf:
  - $ref: "http://json-schema.org/draft-04/schema"
  - type: object
    properties:
      tag:
        description: |
          A fully-qualified YAML tag name that should be associated
          with the object type returned by the YAML parser; for
          example, the object must be an instance of the class
          registered with the parser to create instances of objects
          with this tag. Implementation of this validator is optional
          and depends on details of the YAML parser.
        type: string
        minLength: 6

      propertyOrder:
        description: |
          Specifies the default order of the properties when writing
          out. Any keys not listed in **propertyOrder** will be in
          arbitrary order at the end. This field applies only to nodes with
          **object** type.
        type: array
        items:
          type: string

      flowStyle:
        description: |
          Specifies the default serialization style to use for an
          array or object.  YAML supports multiple styles for
          arrays/sequences and objects/maps, called "block style" and
          "flow style".  For example::

            Block style: !!map
              Clark : Evans
              Ingy  : döt Net
              Oren  : Ben-Kiki

            Flow style: !!map { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }

          This property gives a hint to the tool outputting the YAML
          which style to use.  If not provided, the library is free to
          use whatever heuristics it wishes to determine the output
          style.  This property does not enforce any particular style
          on YAML being parsed.
        type: string
        enum: [block, flow]

      style:
        description: |
          Specifies the default serialization style to use for a string.
          YAML supports multiple styles for strings:

          ```yaml
            Inline style: "First line\nSecond line"

            Literal style: |
              First line
              Second line

            Folded style: >
              First
              line

              Second
              line
          ```

          This property gives a hint to the tool outputting the YAML
          which style to use.  If not provided, the library is free to
          use whatever heuristics it wishes to determine the output
          style.  This property does not enforce any particular style
          on YAML being parsed.
        type: string
        enum: [inline, literal, folded]

      examples:
        description: |
          A list of examples to help document the schema.  Each pair
          is a prose description followed by a string containing YAML
          content. For example:

          ```yaml
            examples:
              -
                - Complex number: 1 real, -1 imaginary
                - "!complex 1-1j"
                  type: array
                  items:
          ```

        type: array
        items:
          type: array
          items:
            - type: string
            - anyOf:
              - type: string
              - type: object
...