APIs & Authentication
What is YAML?
A human-readable data serialization format that uses indentation rather than braces, popular for configuration files (CI pipelines, Kubernetes manifests, OpenAPI specs).
YAML was originally an acronym for "Yet Another Markup Language" and later a backronym for "YAML Ain't Markup Language", which says something about how the format thinks of itself. It is a superset of JSON: every valid JSON document is also valid YAML, but YAML adds anchors, aliases, multi-line strings, and a forgiving syntax that drops braces in favor of indentation.
YAML wins where humans edit the file directly: docker-compose, Kubernetes manifests, GitHub Actions workflows, OpenAPI specs, Ansible playbooks. Writing nested config in YAML is roughly half the keystrokes of writing it in JSON, which matters when an engineer is editing it daily.
The catch is that YAML is also notoriously easy to subtly break. Tabs vs spaces, the "Norway problem" (the country code NO parsed as boolean false), and surprise type coercion of unquoted strings all bite. Modern parsers (YAML 1.2, libyaml, ruamel.yaml) tighten most of this, but defensive YAML still means quoting strings and being explicit about types.
In the wild
- →A GitHub Actions workflow file driving CI from
.github/workflows/test.yml - →A Kubernetes Deployment manifest declaring replicas and container image
- →An OpenAPI spec written in YAML for legibility and converted to JSON at build time
How Brand.dev uses yaml
Endpoints in the Brand.dev API where this concept comes up directly.
FAQ
YAML or JSON for config?
YAML when humans edit it (Kubernetes, CI, OpenAPI). JSON when machines write or read it (API responses, log lines, settings shipped from code).
What is the Norway problem?
In YAML 1.1, unquoted no parses as boolean false, which means a list of country codes that includes Norway becomes [false, "GB", ...]. Quote your strings; YAML 1.2 also fixed this.
Is YAML a superset of JSON?
YAML 1.2 is, in theory. In practice, parser quirks mean you should not rely on it; convert explicitly with a YAML library if you need to round-trip.
Related terms
JavaScript Object Notation, a lightweight text format for representing structured data, supported natively by every modern language.
Extensible Markup Language, a self-describing text format for structured data, predating JSON and still ubiquitous in enterprise systems, sitemaps, and RSS feeds.
A specification format for describing REST APIs in a machine-readable schema, used to generate documentation, client SDKs, and server stubs.