Stop writing JSON by hand, this is a much easier way to handle config files

JSON is a massively widespread format, used for configuration, API responses, sport save knowledge, and rather more. However it has its critics, and JSON isn’t the one possibility.

YAML is definitely older than JSON, however despite the fact that it hasn’t caught on to fairly the identical extent, it has loads to supply.

What’s YAML, and what’s it used for?

A markup language that’s actually extra of a knowledge format

YAML could be difficult to come up with at first; in spite of everything, its identify has modified that means over time, from But One other Markup Language to YAML Ain’t Markup Language. (This kind of recursive acronym is widespread within the tech world, particularly amongst Unix geeks.)

To grasp YAML, it’s helpful to discover what a markup language is. In brief, a markup language combines a doc written in plain textual content with annotations that describe varied elements of that textual content. HTML is the best-known instance, a language that helps on-line publication, including hyperlinks, embedded photos, and construction to net pages.

Different widespread markup languages embrace XML and SGML; these are strongly related to HTML, though they’ve completely different scopes and makes use of. There’s also Markdown, a extremely popular format that, regardless of its identify, can be a markup language.

YAML isn’t actually a markup language, although, as its acronym change displays. YAML describes itself as a knowledge serialization language, which actually simply means it’s a syntax for storing knowledge. Consider YAML as much less like HTML with knowledge and extra like JSON improved.

YAML dates again so far as 2001, however its first full launch was in 2004. It’s been revised a handful of instances since, with the newest model touchdown in 2021. Its recordsdata sometimes use certainly one of two extensions: .yml or .yaml.

How is YAML completely different from JSON?

A bit like JSON with the tough edges sanded down

JSON is YAML’s closest well-known various. In truth, YAML is a superset of JSON, so any JSON file can be a legitimate YAML file. A easy YAML doc appears to be like very similar to JSON:

identify:
    first: Jane
    final: Doe
age: 28
function: Engineer

The JSON equal of the above is:

{
    "identify":
    {
        "first": "Jane",
        "final": "Doe"
    },
    "age": 28,
    "function": "Engineer"
}

At this degree, YAML actually isn’t that a lot completely different, though it’s undoubtedly a bit nicer to learn and write—for people, not less than. The language removes all these quotes, brackets, and commas in favor of a construction implied by line breaks and indentation.

YAML makes use of some constructs which can be acquainted from Markdown, like a set of rows, every starting with a hyphen to characterize a listing:

fruits:
    - Apple
    - Banana
    - Cherry

You’ll be able to simply mix the syntax for dictionaries (maps) and lists, in no matter hierarchy you want:

YAML additionally helps multi-line strings, which many JSON customers will welcome. The primary kind, the literal block, preserves line breaks. It’s helpful once they convey that means:

handle: |
  1600 Pennsylvania Avenue NW
  Washington, D.C.
  20500

The opposite kind is known as a folded block, and it treats line breaks as areas:

data: >
  Folding permits lengthy traces to be damaged
  wherever a single area character
  separates two non-space characters.

The folded kind helps you to lay out paragraphs nonetheless you need, a lot the identical means that Markdown and HTML do.

The place is YAML utilized in the true world?

Config recordsdata and DevOps have been vital adopters

Amusingly, the official YAML web site presents itself in YAML syntax:

Though it’s intelligent, it demonstrates that YAML is best at representing knowledge than it’s at structuring the contents of net pages!

YAML is commonly used for configuration recordsdata, particularly by extra trendy applications. For instance, looking out my consumer config listing for YAML recordsdata provides me the next:

Aside from gh, the GitHub command-line consumer, these are all TUI apps with a contemporary strategy to configuration that differs from extra conventional approaches like INI recordsdata, scripts, or bespoke codecs.

The gh config file demonstrates a superb use of YAML:

This config file has smart defaults, clean values performing as templates, and feedback to clarify every setting. It is a marked enchancment on JSON, which doesn’t straight help feedback—until you’re using JSONC.

DevOps instruments like Docker and Kubernetes have adopted YAML, not less than partly for its ease of readability. The previous’s Compose file and the latter’s object spec files each use YAML.

In the meantime, the yq tool does for YAML what jq does for JSON: it helps you to course of a YAML file, extracting knowledge from it or updating it.

You need to use yq to transform JSON to YAML:

yq -P -oy file.json

You’ll be able to edit knowledge with it, like this instance, which finds an merchandise in an array, then adjustments it:

yq '(.[] | choose(.identify == "foo") | .handle) = "12 cat st"'

When YAML works, it’s excellent

YAML isn’t at all times a more sensible choice than JSON, which has higher interoperability because the extra established format. However YAML’s benefits are fairly vital, so it’s no shock that, for configuration and associated duties, it’s typically most popular.