YAML – JSON Schema

YAML and JSON: Interoperability and Schemas

YAML is designed to be a superset of JSON (JavaScript Object Notation). This means that, with very few exceptions, any valid JSON document is also a valid YAML document. This interoperability is a key feature, allowing YAML to be used in environments where JSON is prevalent.

YAML’s Core Schema defines data types that directly correspond to JSON’s types: null, boolean, integer, floating-point number, string, array (sequence in YAML), and object (mapping in YAML).

Mapping YAML Core Schema Types to JSON

When a YAML document adhering to the Core Schema (or JSON Schema, which is a subset) is parsed, its data types can be straightforwardly converted to JSON types.

1. Null Values

YAML represents null values using null or ~ (tilde). An empty value for a key can also be interpreted as null.

# YAML
optional_field: null
another_null: ~
empty_implies_null:

Corresponding JSON:

{
  "optional_field": null,
  "another_null": null,
  "empty_implies_null": null
}

2. Boolean Values

YAML uses true and false (lowercase) for boolean values in its Core Schema.

# YAML
is_active: true
has_errors: false

Corresponding JSON:

{
  "is_active": true,
  "has_errors": false
}

3. Integer Values

YAML supports decimal, hexadecimal (0x...), and octal (0o...) integers.

# YAML
count: 123
negative_value: -45
hex_value: 0xFF  # 255 in decimal
octal_value: 0o77 # 63 in decimal

Corresponding JSON:

{
  "count": 123,
  "negative_value": -45,
  "hex_value": 255,
  "octal_value": 63
}

4. Floating-Point Numbers

YAML supports standard decimal notation and scientific (exponential) notation for floats. Special values like .inf (infinity) and .nan (Not a Number) are also supported.

# YAML
pi_approx: 3.14159
scientific_notation: 1.23e-4 # 0.000123
positive_infinity: .inf
negative_infinity: -.inf
not_a_number: .nan

Corresponding JSON (note: JSON standard itself doesn’t explicitly define Infinity or NaN literals, but many parsers handle them or they might be represented as null or strings depending on the converter’s strictness. YAML specification for .inf and .nan is robust):

{
  "pi_approx": 3.14159,
  "scientific_notation": 0.000123,
  "positive_infinity": "Infinity", // Or null, or error depending on JSON serializer
  "negative_infinity": "-Infinity",// Or null, or error
  "not_a_number": "NaN"         // Or null, or error
}

For maximum JSON compatibility, it’s often best if YAML .inf and .nan are converted to null or a specific string agreed upon by the consuming application if strict JSON adherence is required, as official JSON grammar lacks these.

5. Strings, Sequences, and Mappings

YAML strings (plain, single-quoted, double-quoted, block) map to JSON strings. YAML sequences map to JSON arrays, and YAML mappings map to JSON objects.

# YAML
message: "Hello, YAML!"
items: ["apple", "banana", "cherry"]
configuration:
  host: localhost
  port: 8080

Corresponding JSON:

{
  "message": "Hello, YAML!",
  "items": ["apple", "banana", "cherry"],
  "configuration": {
    "host": "localhost",
    "port": 8080
  }
}

YAML Features Beyond JSON

While YAML is a superset of JSON, it includes features not present in JSON, such as:

• Comments (#)
• Anchors (&) and Aliases (*) for data reuse
• Explicit Tags (!!str, !mycustomtype)
• Block scalars (literal | and folded >)
• Multiple documents in a single stream (separated by ---)

When converting YAML with these features to JSON, they are typically resolved or omitted: comments are removed, anchors/aliases are expanded, custom tags might be stripped or cause errors if the JSON converter doesn’t know how to handle them, and block scalars are converted to standard JSON strings. Multiple documents would need to be processed individually.

Practical Implications

The strong JSON compatibility means:

• You can often use YAML where JSON is expected, especially for configuration.
• Many tools and libraries can seamlessly convert between YAML and JSON.
• YAML can provide a more human-readable way to write and maintain data that will eventually be consumed as JSON.

Understanding this relationship helps in leveraging YAML’s readability and advanced features while ensuring compatibility with JSON-based systems when needed.