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
- Array of strings
- Array of objects — single value
- Array of objects — many values
- Object of keyed arrays of strings
- Object of keyed objects with mixed values
- Array of arrays with mixed values
- Nodes
- Sample GitHub Action
- Takeaways
- Resources and further reading
- Keep in touch
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 - LoverThe 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: RepublicThe 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 AntonoffLover: - *TS # Subsequent occurrenceI 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 Rebuildon: 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:
- Multi-line strings
- Block scalar
- Block scalar, block chomping indicators
-
strip+
keep
Resources and further reading
- Official YAML 1.2 Documentation at yaml.org
- YAML to JSON web converters