{"canonical_url":"https://engineer.company/glossary/yaml/","content_markdown":"# YAML\n\n## What it is\n\nYAML is a text format for nested data that marks structure with indentation,\ncolons and dashes instead of brackets and quotes, which is why it is the usual\nchoice for configuration that people write and review by hand. The name is a\nrecursive acronym, \"YAML Ain't Markup Language\". Files end in `.yaml` or `.yml`,\nand RFC 9512, published in February 2024, registered the media type\n`application/yaml` and named `.yaml` the preferred extension.\n\nUnderneath the light punctuation sits a small data model. There are mappings,\nwhich pair keys with values, sequences, which are ordered lists, and scalars:\nstrings, numbers, booleans and null. Around that model the language adds what a\nperson editing a file wants: comments that start with `#`, block scalars that\nkeep line breaks with `|` or fold them with `\u003e`, several documents in one file\nseparated by `---`, anchors and aliases (`\u0026name` and `*name`) that let one value\nbe reused elsewhere, and tags that name a type outright.\n\nThe earliest YAML framework was a Perl one, written in 2001. Version 1.1 of the\nspecification followed in 2005, and version 1.2 in 2009, with a primary focus on\nmaking YAML a strict superset of JSON and with many of the older implicit typing\nrules removed. Revision 1.2.2, published in October 2021, corrected errors and\nclarified wording without changing the language. Plenty of software still reads\nthe older rules, though: Ansible's documentation notes that PyYAML and libyaml\nimplement YAML 1.1.\n\nSo YAML sits between two neighbours. JSON is its strict subset, terse and\nunambiguous, made for programs to exchange. TOML is a flatter configuration\nformat in which every string is quoted, so a value's type is never guessed. YAML\noffers more than either, and the extra freedom is exactly where its trouble\ncomes from.\n\n## Why it matters\n\nThe real choice is what format to give a file that people will maintain for\nyears: deployment descriptions, CI workflows, server configuration. Ansible\nplaybooks are YAML, and so are the configuration files of many other\ninfrastructure tools, so for much of that work the decision has already been\nmade upstream, and what is left to decide is how strictly to write it.\n\nThe case for YAML is readability. A reviewer can read a diff of it without\ncounting braces, a comment can explain why a value is what it is, and a\nmulti-line script or certificate fits in a block scalar without escaping.\nAgainst that, whitespace carries meaning, so a key indented two spaces too far\ncan land in a different mapping while the file still parses. Tabs are forbidden\nfor indentation altogether. Unquoted values are typed by their spelling, and the\nspelling rules differ between 1.1 and 1.2. Templating adds a second syntax on\ntop: in Ansible, a value that begins with `{{` must be quoted, or the parser\ntakes it for a mapping.\n\nWhat tips the decision is how the file will be checked. YAML with a linter and a\nhabit of quoting strings is a comfortable format for configuration a team edits\ntogether. YAML without either is a format in which a valid file can say\nsomething other than what its author meant. For data passed between programs,\nJSON is the safer default, and for a short settings file with few levels of\nnesting TOML is simpler.\n\n## What it looks like in practice\n\nThe company's infrastructure repository covers deployed public services and\nconfiguration for other components, including database, backup, mail transport\nand DNS roles. Its recorded implementation comprised\n[19 Ansible playbooks and 34 roles, 12,065 lines in all](/portfolio/servers-you-can-rebuild-from-scratch/),\na historical count rather than the current repository size. Backup and mail\nautomation have an operational activation step separate from their configuration.\nComposition is data rather than flags. Each host belongs to a tier group, and\nthe YAML variables of that group list the roles the host gets, so a provisioning\nrun needs no arguments to bring every host to the state its group declares.\nThat is YAML used as the language of declared state, and its success is checked\nrather than assumed, because a converged host has to report zero changes. The\nYAML costs speed: every change is slower than editing a file on the server\nwould be, and because a converge that half-applies is worse than one that\nrefuses, a preflight play now runs in front of it.\n\nTwelve thousand lines of YAML need a machine reading them before a person\ndoes. At the documented August 2026 implementation stage, [YAML was one of the\nlanguages a 22-linter commit gate\nchecked](/portfolio/built-a-22-linter-commit-gate/), alongside HTML, CSS,\nJavaScript, Python, Markdown and shell. The gate has no warning tier, so every\ndiagnostic stops the commit, and inline suppressions are prohibited outright:\nan ignore comment or a disable directive in the file is not an escape route.\nFor YAML that matters, because most of the traps below are perfectly valid\nsyntax, and only a rule that refuses them catches them before they reach a\nhost.\n\n## Where it goes wrong\n\nThe traps below share one trait: the file parses cleanly and means something\nelse.\n\n**A country code turns into false.** Under YAML 1.1 rules, unquoted `yes`, `no`,\n`on`, `off`, `y` and `n`, in several capitalisations, are booleans. The YAML 1.2\ncore schema keeps only `true` and `false`, in three capitalisations, and RFC\n9512 warns that a parser following the older syntax can read `{insecure: n}` as\nfalse rather than as the letter n. A list of Nordic countries shows the problem:\n\n```yaml\ncountries:\n    - DK\n    - SE\n    - NO # YAML 1.1 reads this as false\n```\n\nQuote any string that could be read as something else, write booleans only as\n`true` and `false`, and let a linter enforce both.\n\n**A version number loses a digit.** Unquoted numbers are converted, so\n`version: 1.10` arrives as the float 1.1, and under 1.1 rules a leading zero\nmarks an octal number, so a code written as `010` becomes 8. Ansible's\ndocumentation tells its users to quote a version such as `\"1.0\"` for exactly\nthis reason. Quote identifiers, codes and versions, which are strings that\nhappen to contain digits.\n\n**A key ends up under the wrong parent.** Indentation decides which mapping a\nkey belongs to, so one line shifted by two spaces moves a setting somewhere else\nwithout any error. The specification also requires every key in a mapping to be\nunique, and a repeated key far down a long block is easy to miss in review, so\nyamllint carries a rule for each of the two mistakes. Run it before the file is\nused.\n\n**Loading a file runs code.** Tags can name language-specific types, and a\nloader that honours them will construct whatever object the file asks for.\nPyYAML's documentation compares `yaml.load` with an unsafe\nloader to `pickle.load`: it can construct objects and invoke\nPython functions. The loader choice matters; current versions require it\nexplicitly. `yaml.safe_load` recognises only basic YAML tags. RFC\n9512 asks for code execution in deserializers to be off by default. Use the\nsafe loader for ordinary configuration files.\n\n**A short file fills the memory.** Anchors and aliases make a YAML document a\ngraph rather than a tree. When each anchor repeats the one before it twice,\nevery added line doubles the size, so thirty short lines describe more than a\nbillion strings once a program walks the result as a plain tree. RFC 9512 names\nthis exponential data expansion, the billion laughs attack, and answers it with\nprocessors that limit anchor recursion depth. Accept YAML from outside only\nthrough such a processor, and test the limit against the parser actually in use.\n\n## Further reading\n\n- [YAML 1.2.2 specification](https://yaml.org/spec/1.2.2/) — the\n  language itself, including the core schema that decides how unquoted values\n  are typed.\n- [RFC 9512: YAML Media Type](https://www.rfc-editor.org/rfc/rfc9512) — the\n  `application/yaml` registration, with security notes on booleans, code\n  execution and alias expansion.\n- [YAML specification changes](https://yaml.org/spec/1.2.2/ext/changes/) —\n  what each revision changed, from 1.2.1 to 1.2.2.\n- [Ansible: YAML Syntax](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html)\n  — the subset Ansible uses, with its quoting gotchas.\n- [yamllint rules](https://yamllint.readthedocs.io/en/stable/rules.html) — the\n  checks for truthy values, duplicate keys, octal numbers and indentation.\n- [PyYAML documentation](https://pyyaml.org/wiki/PyYAMLDocumentation) — the\n  difference between `load` and `safe_load`, in the library's own words.\n\n\u003chttps://engineer.company/glossary/yaml/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"What YAML is, when a hand-edited file should use it rather than JSON or TOML, and the boolean, indentation and unsafe-loader traps behind its bugs.","formats":{"gemtext":"https://engineer.company/glossary/yaml/index.gmi","gopher":"https://engineer.company/glossary/yaml/gophermap","html":"https://engineer.company/glossary/yaml/","json":"https://engineer.company/glossary/yaml/index.json","markdown":"https://engineer.company/glossary/yaml/index.md","pdf":"https://engineer.company/glossary/yaml/index.pdf"},"kind":"page","language":"en","title":"What is YAML?","url":"https://engineer.company/glossary/yaml/","version":1}