YAML (YAML Ain't Markup Language) is a human-readable, data serialization format commonly used for configuration files and data exchange between programming languages. It emphasizes simplicity and readability, making it ideal for developers and system administrators. * **Human-Readable Syntax** - YAML's indentation-based structure is easy to read and write, resembling natural language formatting, which reduces errors. * **Lightweight and Flexible** - Unlike XML or JSON, YAML avoids complex syntax, making it simpler and more concise for configuration files. * **Data Serialization** - YAML is excellent for serializing structured data, making it ideal for storing nested and hierarchical information. * **Supports Complex Data Types** - YAML supports scalars (strings, numbers, booleans), lists, and dictionaries, enabling representation of complex configurations. * **Comments Support** - Unlike JSON, YAML supports comments using the hash symbol, making it easier to document configuration files. * **Integrations** - YAML is often used in APIs and tools like OpenAPI, Swagger, and CI/CD pipelines for defining configurations and workflows. YAML is a versatile, human-friendly, and widely-used format for configuration files, data serialization, and API specifications. Its readability, flexibility, and compatibility with modern tools make it an essential choice for DevOps, microservices, and automation workflows. It is useful to apply YAML during design, development, and configuration, but then in runtime you switch over to JSON representations. YAML has its shortcomings, but it provides an important bridge between the engineering and product stakeholders who are making APIs happen.
YAML
YAML (YAML Ain’t Markup Language) is a human-readable data serialization format used for configuration files and for exchanging structured data between languages and tools. It represents scalars, lists, and maps through indentation rather than brackets or tags, which makes it easy to read and write by hand. It has become the default authoring format for API definitions, infrastructure config, and CI/CD pipelines.
- Indentation-based structure - Nesting is expressed with whitespace instead of braces or closing tags, keeping documents clean and legible.
- Comments and readability - Unlike JSON, YAML supports inline comments, which makes it well-suited to hand-edited configuration.
- A superset of JSON - Any valid JSON is valid YAML, so the two convert cleanly back and forth across the toolchain.
- The design-time format for API specs - OpenAPI, AsyncAPI, and Arazzo definitions are almost always authored in YAML before anything else touches them.
In my own work the pattern is consistent: you apply YAML during design, development, and configuration, then switch to JSON representations at build and run time. That split lets humans reason about an OpenAPI or JSON Schema contract in a readable form while machines consume the serialized JSON. For governance and the agentic turn, YAML is where the human-owned source of truth lives, so keeping it clean and diff-friendly is some of the most stabilizing API work a team can do.
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
Editing JSON Schema in YAML
2025-03-31
The Basic Building Blocks API Governance
2025-03-14
Schema Work is the Most Stabilizing API Work
2025-02-25
