YAML

Technical Definition

YAML is a data serialisation format defined by the YAML specification maintained at yaml.org. It expresses data as nested mappings (key-value pairs), sequences (ordered lists) and scalars (strings, numbers, booleans, null), using significant whitespace indentation to denote structure instead of explicit delimiters such as braces or brackets. YAML documents are supersets that can also represent JSON-equivalent structures, and most YAML parsers can consume valid JSON as a subset of YAML syntax. A single YAML file may contain multiple documents separated by the --- marker.

Operational Relevance

YAML is widely used for configuration in continuous integration pipelines, container orchestration manifests, infrastructure-as-code definitions and application settings files. Its readability makes it a common choice where humans routinely read and edit configuration by hand. Because structure is conveyed through indentation rather than explicit closing markers, YAML documents are sensitive to whitespace errors: mixing tabs and spaces, inconsistent indentation levels, or accidental trailing whitespace can silently change the parsed structure without raising an obvious syntax error, sometimes reordering keys under the wrong parent or dropping intended nesting.

Architecture Relationship

YAML sits at the configuration and data interchange layer of a system rather than in the runtime execution path. It is typically parsed at application startup, build time, or deployment time by a YAML library or tool-specific parser (for example, in a CI/CD platform or orchestration system), which converts the YAML document into an in-memory data structure the consuming application or tool then uses. YAML itself carries no execution semantics; any behaviour attributed to a YAML file arises entirely from how the consuming tool interprets the resulting data structure.

Example

A minimal YAML mapping with a nested list might appear as:

service:
  name: example-service
  ports:
    - 8080
    - 8443
  enabled: true

Here, service is a mapping containing a scalar name, a sequence ports, and a boolean enabled. Indentation alone establishes that ports and enabled are children of service.

Misunderstanding

A common misunderstanding is treating YAML as inherently safe to parse without further consideration. Some YAML parsers support tag-based type coercion or, in unsafe load modes, arbitrary object construction; this is a property of the specific parser and its configuration, not a universal feature of the YAML format itself, and safe-load functions exist precisely because unsafe parsing of untrusted YAML can lead to unintended code or object instantiation in certain language bindings. Confirm which loader mode a given tool or library uses before treating untrusted YAML input as safe.

Related Terms

• JSON — a data interchange format YAML supersets structurally in most parsers
• Infrastructure as code — a practice area where YAML is a common configuration syntax
• Serialisation — the general category of encoding structured data as text

Further Reading

• YAML specification and documentation at yaml.org, maintained as the canonical reference for the format’s syntax and semantics
• Documentation for the specific YAML parser or library in use, to confirm supported tags, load modes and version-specific behaviour before production use

Verified Checks and Next Steps

Before relying on a YAML document in an operational workflow, validate it against the consuming tool’s schema or a general YAML linter in a non-production environment, and confirm the parser’s load mode (safe versus unsafe) against the tool’s own documentation for the version in use. If a YAML file behaves unexpectedly, the first diagnostic step is to have the parser re-emit the document as normalised YAML or JSON and compare the emitted structure against the intended structure, rather than assuming the source text is correct as written.