DEV Community

chantastic
chantastic

Posted on • Originally published at chan.dev on

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
Enter fullscreen mode Exit fullscreen mode

JSON

JSON doesn't support comments.

Array of strings

Sequence of Scalars

YAML

- Evermore
- Folklore
- Lover
Enter fullscreen mode Exit fullscreen mode

JSON

["Evermore", "Folklore", "Love"]
Enter fullscreen mode Exit fullscreen mode

Array of objects — single value

Mapping Scalars to Scalars

YAML

- Evermore: 2020
- Folklore: 2020
- Lover: 2019
Enter fullscreen mode Exit fullscreen mode

JSON

[
  {
    "Evermore": 2020
  },
  {
    "Folklore": 2020
  },
  {
    "Lover": 2019
  }
]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

JSON

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

JSON

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

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
Enter fullscreen mode Exit fullscreen mode

JSON

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

Array of arrays with mixed values

Sequence of Sequences

YAML

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

JSON

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

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
Enter fullscreen mode Exit fullscreen mode

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"]
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
        }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)

Read next

alexmercedcoder profile image

Leveraging Python's Pattern Matching and Comprehensions for Data Analytics

Alex Merced -

tekiegirl profile image

The Knowledge Vault: ADRs

Jacqui Read -

fazly_fathhy profile image

Why AWS CodeCommit

Fazly Fathhy -

rsaz profile image

"How the Open Source Project Uses EarlyAI to Enhance Framework Code Quality"!

Richard Zampieri -