⇠ chan.dev / posts

A Non-Comprehensive Guide to YAML for Folks Who Like JSON Just Fine

YAML is a human friendly data serialization standard for all programming languages. — https://yaml.org

I don’t know precisely which humans YAML is friendly to but I’m not one of them.

And it looks like the people who run in my circles are also excluded.

{% tweet ’https://twitter.com/chantastic/status/1359601176434544640?s=20’ %}

Mapping to JSON

Between Eleventy, GitHub Actions, and a recent foray into serverless, I’m using a more YAML. And I don’t understand it.

This is mapping for my JSON-acquainted brain.

Outline

Comments

YAML

# you can put these p much anywhere

JSON

JSON doesn’t support comments.

Array of strings

Sequence of Scalars

YAML

- Evermore
- Folklore
- Lover

JSON

["Evermore", "Folklore", "Love"]

Array of objects — single value

Mapping Scalars to Scalars

YAML

- Evermore: 2020
- Folklore: 2020
- Lover: 2019

JSON

[
  {
    "Evermore": 2020
  },
  {
    "Folklore": 2020
  },
  {
    "Lover": 2019
  }
]

Array of objects — many values

Sequence of Mappings

YAML

- name: Taylor Swift
  album_count: 9
  label: Republic
- name: The National
  album_count: 8
  label: 4AD

JSON

[
  {
    "name": "Taylor Swift",
    "album_count": 9,
    "label": "Republic"
  },
  {
    "name": "The National",
    "album_count": 8,
    "label": "4AD"
  }
]

This syntax confused the shit out of me.
This code is auto-formatted by prettier putting the dash and the first property on the same line.

YAML docs show the dash and first property on different lines which is much more legible.

- name: Taylor Swift
  album_count: 9
  label: Republic
- name: The National
  album_count: 8
  label: 4AD

Object of keyed arrays of strings

Mapping Scalars to Sequences

YAML

Taylor Swift:
  - Evermore
  - Folklore
  - Lover
The National:
  - I Am Easy to Find
  - Sleep Well Beast
  - Trouble Will Find Me

JSON

{
  "Taylor Swift": ["Evermore", "Folklore", "Lover"],
  "The National": [
    "I Am Easy to Find",
    "Sleep Well Beast",
    "Trouble Will Find Me"
  ]
}

Object of keyed objects with mixed values

Mapping of Mappings

YAML

Taylor Swift:
  album_count: 9
  label: Republic
The National:
  album_count: 8
  label: 4AD

JSON

{
  "Taylor Swift": {
    "album_count": 9,
    "label": "Republic"
  },
  "The National": {
    "album_count": 8,
    "label": "4AD"
  }
}

Array of arrays with mixed values

Sequence of Sequences

YAML

- [name, album_count, label]
- [Taylor Swift, 9, Republic]
- [The National, 8, 4AD]

JSON

[
  ["name", "album_count", "label"],
  ["Taylor Swift", 9, "Republic"],
  ["The National", 8, "4AD"]
]

Nodes

YAML

Folklore:
  # Following node labeled TS and AD
  - &TS Taylor Swift
  - &AD Aaron Dressner
  - Jack Antonoff
Lover:
  - *TS # Subsequent occurrence
I Am Easy to Find:
  - *AD

JSON

No JSON equivalent.
But this is the output from the above YAML.

{
  "Folklore": [
    "Taylor Swift",
    "Aaron Dressner",
    "Jack Antonoff"
  ],
  "Lover": ["Taylor Swift"],
  "I Am Easy to Find": ["Aaron Dressner"]
}

Sample GitHub Action

YAML

name: Netlify Rebuild
on:
  schedule:
    - cron: "0 21 * * MON-FRI"
jobs:
  build:
    name: Netlify Rebuild
    runs-on: ubuntu-latest
    steps:
      - name: Curl request
        run: curl -X POST -d {} https://api.netlify.com/build_hooks/601321b7879709a8b8874175

JSON

{
  "name": "Netlify Rebuild",
  "on": {
    "schedule": [
      {
        "cron": "0 21 * * MON-FRI"
      }
    ]
  },
  "jobs": {
    "build": {
      "name": "Netlify Rebuild",
      "runs-on": "ubuntu-latest",
      "steps": [
        {
          "name": "Curl request",
          "run": "curl -X POST -d {} https://api.netlify.com/build_hooks/601321b7879709a8b8874175"
        }
      ]
    }
  }
}

Takeaways

Complex types are inferred

The structures of complex types are hidden in YAML.
They get inferred by the structure of included data.

Keep a look out for - and : which indicate the containing structure.

Dash -

If you see a dash -, it means you’re describing a single array item.
This means you’re in an array.

Colon :

If you see a color : separating two values, it means your describing a key-value pair. This means you’re in an object.

In the wild

Since YAML is used often for configuration, it’s likely that your root type is object.
At least that’s the case for Markdown Frontmatter, GitHub Actions, and CloudFormation templates.

TODO

Sections I’d like to add:

Resources and further reading

Keep in touch