chan.dev

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.

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.

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.

Resources and further reading #

Keep in touch #