Notes on JSON and YAML

JSON and YAML are both data serialisation formats which are both machine- and human readable. JSON is the simplest of these two, and it forms the basis of YAML, which is a superset of JSON.

JSON

JSON (JavaScript Object Notation) is not much more than a comma-separated collection of key-value pairs, structured by curly braces { } to form objects, and square brackets [ ] to form arrays.

An example is shown below:

{
  "boom":
  {
    "roos": 1,
    "vis": 2,
    "vuur": "huis",
    "pim": null,
    "number" : 1.23E5,
    "value" : false
  },

  "vuur":
  {
    "array_of_numbers": [1, 2, 3, 4],
    "array_mixed": ["tekst", 123, false, null, {"test1": 1, "test2": 2}]
  }
}

Note that it's not allowed to put a trailing comma after the last item in a data structure. Forgetting to leave out that last comma is a frequent and easy-to-overlook mistake.

YAML

YAML is a superset of JSON, so every valid JSON file is also valid YAML, and if you have a YAML parser, there is no need for a separate JSON parser.

The advantage of YAML over plain JSON is that it's more expressive and readable for humans. For example, JSON does not even allow for comments, but YAML does.

Like JSON, YAML is in essence not much more than key-value pairs, but with a bit more notational freedom:

site: My Website  # This is a comment
url: https://example.nl
author: Jan Jansen

• You can put in comments
• In most places, you can leave out the quotes
• You can replace curly braces and commas by indentation

The JSON example from the previous section could thus be written as YAML as follows:

boom:
  roos: 1
  vis: 2
  vuur: huis
  pim: null
  number : 1.23E5
  value : false


vuur:
  array of numbers: [1, 2, 3, 4]
  array_mixed: [tekst, 123, false, null, {test1: 1, test2: 2}]

Note that indentation has to be done with spaces (no tabs) and since whitespace has syntactic meaning (like in Python), indentation mistakes make the file invalid, or worse change the meaning of the data (without being noticed).

You can replace the JSON-style list with YAML-style lists, which are made by putting a dash (and space) in front of the items:

boom:
  roos: 1
  vis: 2
  vuur: huis
  pim: null
  number : 1.23E5
  value : false


vuur:
  array of numbers:
    - 1
    - 2
    - 3
    - 4

  array_mixed:
    - tekst
    - 123
    - false
    - null
    - test1: 1
      test2: 2