> [!tldr] **Like JSON, but more human-readable & with more [[Footgun]]s** YAML is a space-dependent [[Data Serialization]] method, that extends JSON. It is highly flexible and has many features JSON lacks, but in some ways is more confusing to learn and also subject to type-inferencing errors if you're not paying attention. A [[JSON]] string is also valid YAML, but a YAML string is almost certainly not valid JSON. YAML is a way to provide metadata to a [[Markdown]] file & is used for coding configuration files. This is called [[Frontmatter]]. It can be used for general data storage. See also: [[YAML Uses]] There's a good [[NodeJS]] package that allows you to read/write to YAML using [[JavaScript]]. Can convert 1:1 to [[JSON]]. By trying to be more flexible, the designers of YAML included a lot of [[Footgun]]s. I have run into a simple one of these several times by accidentally making making [[Frontmatter]] contain _comments_ rather than strings by writing things like: ```yaml name: my #1 most often screw up! ``` # Fast Facts - Uses whitespace indentation (but not tabs) - Can store multiple documents within a single file - Comments start with # - Lists can be done in two ways: 1. [item 1, item 2] (like JSON) 2. Or one per line, with the line starting with a hyphen - Associative arrays (like Objects in JavaScript) can be done two ways: - {key: value} (like JSON) - with simple key, colon, space, value - Strings typically aren't quoted, but can also be quoted or double-quoted - If your string is meant to literally be surrounded by quotes in the way it is represented. You need to use apostrophes to encapsulate the whole thing ```yaml quoteless: this string will passes without quotes footgun: "this string will parse without quotes, too" includesquotes: '"this will parse with the quotes"' ``` - Can have references and tags, using an Ampersand [[Sigil]] to denote the tag location and an asterisk sigil to reference it - The use of references allows for Graphs to be represented in YAML (not just trees, like JSON) ### [[YAML Uses]] Became its own note. ### Anchors A power feature of YAML that definitely separates it from JSON is the ability to include by reference. From [here](https://www.yaml.info/learn/index.html): > Let's add a billing address to the invoice. > > In our case it is the same as the shipping address. We rename address to shipping address and add billing address: > ```yaml > invoice number: 314159 > name: Santa Claus > shipping address: > street: Santa Claus Lane > zip: 12345 > city: North Pole > billing address: > street: Santa Claus Lane > zip: 12345 > city: North Pole > order items: > - Sled > - Wrapping Paper > ``` > > Now that's a bit wasted space. If it's the same address, you don't need to repeat it. Use an [Alias](https://www.yaml.info/learn/index.html). > > In the native data structure of a programming language, this would be a reference, pointer, or alias. > > Before an [Alias](https://www.yaml.info/learn/index.html) can be used, it has to be created with an [Anchor](https://www.yaml.info/learn/index.html): > ```yaml > invoice number: 314159 > name: Santa Claus > shipping address: &address # Anchor > street: Santa Claus Lane # ┐ > zip: 12345 # │ Anchor content > city: North Pole # ┘ > billing address: *address # Alias > > order items: > - Sled > - Wrapping Paper > ``` > > When loaded into a native data structure, the shipping address and billing address point to the same data structure. ## Samples ```yaml --- # The Smiths - {name: John Smith, age: 33} #interoperability with JSON? - name: Mary Smith age: 27 - [name, age]: [Rae Smith, 4] # sequences as keys are supported --- # People, by gender men: [John Smith, Bill Jones] women: - Mary Smith - Susan Williams ``` **** ## Source - [The Official YAML Web Site](https://yaml.org/) - [What exactly is Frontmatter?](https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/) - [YAML - Wikipedia](https://en.wikipedia.org/wiki/YAML) - https://ruudvanasseldonk.com/2023/01/11/the-yaml-document-from-hell - https://www.yaml.info/learn/index.html ## Related - [[Data Serialization Methods]] - [[Data Serialization]] - [[YAML Uses]]