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
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 restrictionItems in the array are restricted to the following types:stringNo 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:No length restrictionBlock 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.
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:No length restrictionInline 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.
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:No length restrictionexamples: - - Complex number: 1 real, -1 imaginary - "!complex 1-1j" type: array items:
Items in the array are restricted to the following types:arrayNo length restrictionThe first 2 items in the list must be the following types:- stringNo length restriction
- object
stringNo length restrictionThis node must validate against any of the following:
- additionalItems
object This node must validate against any of the following:
- boolean
itemsobject This node must validate against any of the following:
additionalPropertiesobject This node must validate against any of the following:
- boolean
definitionsobject objectpropertiesobject objectpatternPropertiesobject objectdependenciesobject objectallOfschemaArray anyOfschemaArray oneOfschemaArray not# Internal Definitions ¶
schemaArrayarray Minimum length: 1Items in the array are restricted to the following types: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 # Redefine JSON schema validators in terms of this document so that # we can check nested objects: additionalItems: anyOf: - type: boolean - $ref: "#" items: anyOf: - $ref: "#" - $ref: "#/definitions/schemaArray" additionalProperties: anyOf: - type: boolean - $ref: "#" definitions: type: object additionalProperties: $ref: "#" properties: type: object additionalProperties: $ref: "#" patternProperties: type: object additionalProperties: $ref: "#" dependencies: type: object additionalProperties: anyOf: - $ref: "#" - $ref: "http://json-schema.org/draft-04/schema#definitions/stringArray" allOf: $ref: "#/definitions/schemaArray" anyOf: $ref: "#/definitions/schemaArray" oneOf: $ref: "#/definitions/schemaArray" not: $ref: "#" definitions: schemaArray: type: array minItems: 1 items: $ref: "#" ...
Schema documentation automatically generated by sphinx-asdf 0.1.4.