Formats
One record, four spellings: the data is the same
JSON, YAML, TOML and CSV all write down the same kinds of data.
Configuration and API data travel as plain text, in a handful of formats. Here is one server record in four of them. JSON: braces, quotes and commas. It is what APIs speak. YAML: the same data, with indentation in place of the punctuation. Pipelines and Kubernetes use it. TOML: keys, equals signs and values, for settings files. And CSV: one row per record, with no types and no nesting.
JSON
JSON has six kinds of value and no options
Objects, arrays, strings, numbers, booleans and null. Nothing else.
JSON is small enough to learn in a minute. An object is a set of keys and values in braces. Keys are always strings in double quotes. A value is a string, a number, true or false, null, an array in square brackets, or another object. That is the entire format. What it leaves out matters as much: no comments, no comma after the last item, no single quotes.
JSON limits · Going deeper
JSON has no integer size, no dates and no NaN: parsers fill the gaps
Above 2^53, JavaScript changes your number. Send big ids as strings.
YAML
YAML is the same data, with indentation as structure
Indentation replaces brackets. A dash starts a list item.
YAML is the format you will edit most often by hand. A key, a colon, a value. Strings need no quotes, and a hash sign starts a comment. A key with nothing after it takes the indented block below as its value: a list, where every item starts with a dash, or more keys, two spaces in. It describes exactly the same data as this JSON. The whitespace is doing the work of the brackets.
Multi-line strings · Going deeper
| keeps the line breaks, > folds them into spaces
A block scalar holds several lines of text: | keeps the breaks, > joins the lines.
YAML mistakes
YAML guesses types, and sometimes guesses wrong
Unquoted NO becomes false. Unquoted 1.10 becomes 1.1. Quote your strings.
The convenience has a price. YAML decides the type of anything you do not quote. Write the country code for Norway, and many parsers read the boolean false. Write version one point ten, and it becomes the number one point one. A second colon inside a value breaks the line. A tab used for indentation is an error. And a key one space out of line silently belongs to a different parent.
Validation
A schema lets a machine check configuration first
Valid syntax is not valid configuration. A schema checks the meaning.
A file can be perfectly formed and still wrong. This configuration parses without complaint. A schema says what each key must be. The name is fine. The port should be an integer, and here it is text. The environment must be one of three names, and production is not among them. The replica count is fine. So the file is rejected in the pipeline, seconds after it was written, instead of failing in production.
Validation · Going deeper · 1 of 2
Where a setting comes from
Flag, then environment variable, then file, then default. All env vars are strings.
JSON Schema · Going deeper · 2 of 2
A JSON Schema, as written, and the errors it reports
Set additionalProperties to false, or a misspelt key passes unnoticed.
Lesson complete
You finished “Data formats”
Nicely done.