YAML – Failsafe Schema

YAML - Failsafe Schema

A YAML schema defines how YAML tags are resolved into native data types. The Failsafe Schema is the most basic and universally compatible schema. It guarantees that any YAML document can be parsed, but it only recognizes three fundamental data structures: generic mappings, generic sequences, and generic strings. It does not perform any implicit type conversion (e.g., ‘true’ remains a string, not a boolean; ‘123’ remains a string, not an integer).

The Failsafe Schema is implicitly used when no other schema is specified or when a YAML processor needs a fallback for unknown tags. It ensures interoperability by making minimal assumptions about the data’s meaning.

Supported Types in Failsafe Schema

Generic Mapping (!!map)

Represents an associative container where keys are unique and map to values. In the Failsafe Schema, both keys and values are typically treated as generic strings unless explicitly tagged otherwise by a more specific schema.

Example of a generic mapping:

# YAML content
authors:
  "Clark Evans": "YAML Specification Co-author"
  "Ingy döt Net": "YAML Specification Co-author"
  "Oren Ben-Kiki": "YAML Specification Co-author"

# Explicitly using the !!map tag (often inferred)
flow_style_map:
  !!map {name: "Alice", role: "Developer"}

When parsed with the Failsafe Schema, the structure is preserved as key-value pairs, with keys and values being generic strings:

# Conceptual JSON representation (all values as strings)
{
  "authors": {
    "Clark Evans": "YAML Specification Co-author",
    "Ingy döt Net": "YAML Specification Co-author",
    "Oren Ben-Kiki": "YAML Specification Co-author"
  },
  "flow_style_map": {
    "name": "Alice",
    "role": "Developer"
  }
}

Generic Sequence (!!seq)

Represents an ordered collection of items, indexed by sequential integers starting from zero. In the Failsafe Schema, items in the sequence are treated as generic strings.

# YAML content for a sequence
contributors:
  - "Clark Evans"
  - "Ingy döt Net"
  - "Oren Ben-Kiki"

# Explicitly using the !!seq tag for a flow-style sequence
flow_style_seq: !!seq ["item1", "item2", "item3"]

The conceptual JSON representation for this generic sequence would be:

# Conceptual JSON representation (all items as strings)
{
  "contributors": [
    "Clark Evans",
    "Ingy döt Net",
    "Oren Ben-Kiki"
  ],
  "flow_style_seq": [
    "item1",
    "item2",
    "item3"
  ]
}

Generic String (!!str)

Represents a scalar value as a sequence of Unicode characters. All unquoted scalars, single-quoted scalars, double-quoted scalars, literal block scalars, and folded block scalars that are not resolved by other schemas (like JSON or Core schema) default to generic strings in the Failsafe Schema.

# YAML content
message: Hello, world!
quoted_message: "123"
boolean_like_string: 'true'

In the Failsafe Schema, these would all be interpreted as strings:

# Conceptual JSON representation
{
  "message": "Hello, world!",
  "quoted_message": "123",
  "boolean_like_string": "true"
}

The Failsafe Schema is fundamental because it provides a baseline for YAML processing, ensuring that any document can be loaded at least as a structure of maps, sequences, and strings. More advanced schemas, like the JSON Schema or Core Schema, build upon this by adding rules for resolving tags into more specific types like integers, booleans, nulls, etc.