YAML for the People: A Human Readable Primer

What is YAML?

Everybody touts the human-readability of YAML (YAML Ain't Markup Language), and to be fair there are fewer marks on the file. But, it still has a syntax that needs to be observed if you want the file to actually run anywhere, cause (psst… it really is markup). In a sec, we’ll get into some key features of that syntax.  

First, if you haven’t yet heard much about YAML, it – very much like JSON or XML – is just a way of representing structured data. And so, you could theoretically use it for lots of the same purposes. As it happens, YAML is largely used in configuration files, both for cloud services and for software that your team could potentially be running locally.

So, if it does the same thing as JSON or, ahem XML, why learn a new markup language, you may well be asking. Code blindness is real. XML is hard to read, and while JSON is easier on the eyes, it still doesn’t permit comments  natively – using them requires JSONC.

In addition to simply being more “human-readable,” YAML will save you time in the long run. Take XML as a counterpoint – this XML snippit will be read just fine:

But this won’t:

Moreover, when run, XML won’t natively tell you why it won’t work (psst… the above is missing a forward slash in the outermost closing tag). This can and does lead to massive efforts to find simple errors, often spread over hundreds of fields.

YAML feedback, by contrast, refers to specific lines in the file, so you can quickly find and fix syntax errors. And this ease of use has led to its adoption as a config tool by lots and lots of cool software out there that would likely benefit your team. Below is a not at all inclusive list of a few such products that are frequently used by MacStadium customers:

• ‍Ansible
  -- One of the methods for provisioning masOS VMs
  -- Can also be used to apply updates or config management to your macOS
• ‍Kubernetes (K8s) Deployments
  -- MacStadium’s Orka uses K8s for the orchestration of macOS VMs
  -- YAMLs are used by customers to create additional storage or lightweight Linux VMs running beside the macOS resources
• ‍Git
  -- A source code history management tool
  -- The revision control language of GitHub

The Difference Between YAML and JSON

The major criticism of YAML is a single space has the potential to destroy a build, rendering the spaces highly important. This is contrasted with JSON, which is flexible to that, but then sensitive to commas, brackets, and quotes.

Valid JSON will result in meaningful feedback, but when the interpreter runs into invalid JSON it generally just stops and tells you it was expecting a “,” or “]”, but instead it got a “}”, or some other character for that matter.  

Example JSON snippet: