Formats

One record, four spellings: the data is the same

JSONAPIs, state files{ "name": "web-01", "port": 8080, "active": true, "tags": ["web", "eu"]}YAMLpipelines, Kubernetesname: web-01port: 8080active: truetags: - web - euTOMLtool settingsname = "web-01"port = 8080active = truetags = ["web", "eu"]CSVtables, exportsname,port,active,tagsweb-01,8080,true,web;euNo types and no nesting:every cell is text.One record, four spellings. The data is the same; the format is a choice.Each is plain text built from three things: single values, ordered lists, and keys mapped to values.JSON is strict and every language reads it. YAML is the one people edit by hand. TOML suits settingsfiles. CSV suits rows that all share the same columns.

JSON, YAML, TOML and CSV all write down the same kinds of data.

JSON

JSON has six kinds of value and no options

{ "name": "web-01", "port": 8080, "active": true, "owner": null, "tags": ["web", "eu"], "disk": {"size_gb": 100}}objectkeys mapped to values, in bracesstringalways in double quotesnumberno quotes; integer or decimalbooleantrue or false, in lower casenulldeliberately emptyarrayan ordered list, in bracketsobjectobjects nest inside objectsJSON refuses✗// comments✗a comma after the last item✗'single quotes'✗keys without quotesJSON has six kinds of value and no options.That strictness is its strength: any language parses it the same way, which is why APIs speak it. Thecost is that it is unforgiving to write by hand. One stray comma and the whole file is rejected, solet a tool write it and a formatter such as jq check it.

Objects, arrays, strings, numbers, booleans and null. Nothing else.

JSON limits · Going deeper

JSON has no integer size, no dates and no NaN: parsers fill the gaps

In the JSON textWhat parsers do with it (checked: Python 3.13, Node 22, jq 1.7)Do instead{"id": 9007199254740993}JavaScript reads ...992; Python and jq keep ...993send big ids as stringsa date or a timethere is no date type: it must travel as textISO 8601: "2026-03-09T14:05:00Z"NaN or Infinitynot valid JSON: Python writes it anyway, JavaScript writes nullsend null, or fail early{"a": 1, "a": 2}accepted in silence; Python and JavaScript keep the last, 2never repeat a key1.0 or 1one number type: Python tells 1.0 from 1, JavaScript does notdo not rely on the differenceLargest whole number a JavaScript number holds exactly: 2^53 - 1 = 9,007,199,254,740,991A 64-bit database id can be as large as: 2^63 - 1 = 9,223,372,036,854,775,807JSON says how a value is written, not how large or precise it may be. Each parser decides.RFC 8259 only advises staying within what a 64-bit float holds exactly. That is why some APIs return a large id a secondtime as a string, and why money travels as a string or as whole pence. Python's json.dumps writes NaN unless you passallow_nan=False, and refuses a datetime outright: TypeError, Object of type datetime is not JSON serializable.

Above 2^53, JavaScript changes your number. Send big ids as strings.

YAML

YAML is the same data, with indentation as structure

YAML# settings for shop-apiservice: shop-apireplicas: 3ports: - 80 - 443env: LOG_LEVEL: infocomments are allowedno quotes neededthe value is the block belowa dash starts a list itemtwo spaces in: one level downThe same data as JSON{ "service": "shop-api", "replicas": 3, "ports": [80, 443], "env": {"LOG_LEVEL": "info"}}YAML holds the same data as JSON, with indentation instead of brackets.That makes it pleasant to read and easy to break: the structure is the whitespace. Indent with spaces,never tabs, and keep sibling keys exactly aligned. Any JSON file is also valid YAML.

Indentation replaces brackets. A dash starts a list item.

Multi-line strings · Going deeper

| keeps the line breaks, > folds them into spaces

YAMLrun: | pip install -r requirements.txt pytestsummary: > Deploys the shop API to staging.strip: |- no newline at the endWhat the parser hands over (PyYAML 6.0.3, shown as JSON)"run": "pip install -r requirements.txt\npytest\n""summary": "Deploys the shop API to staging.\n""strip": "no newline at the end"|literal: every line break is kept>folded: line breaks become spaces, giving one long line|- >-the same, without the final newline| keeps each line break; > folds the lines into one. Both end in one newline unless you add a minus.This is why a GitHub Actions step written "run: |" can hold several shell commands, one per line; with > they wouldbe joined into a single command. Inside a block nothing is special: colons, hashes and quotes are plain text. Theindentation of the first line sets the margin, and that margin is removed from every line.

A block scalar holds several lines of text: | keeps the breaks, > joins the lines.

YAML mistakes

YAML guesses types, and sometimes guesses wrong

You wroteYAML readsWrite insteadcountry: NO✗the boolean false, not the text NOcountry: "NO"version: 1.10✗the number 1.1, not the text 1.10version: "1.10"msg: error: disk full✗an error: a second colon and spacemsg: "error: disk full"a tab to indent✗an error: tabs are not allowedspaces, two per levela key one space off✗a different structure, or an erroralign sibling keys exactlyYAML guesses the type of anything unquoted, and it sometimes guesses wrong.The first row is known as the Norway problem. Parsers that follow YAML 1.2 no longer read NO as aboolean, but many tools still follow 1.1. One habit avoids all of it: quote any string that could passfor a number or a boolean, and let an editor or a linter such as yamllint check the indentation.

Unquoted NO becomes false. Unquoted 1.10 becomes 1.1. Quote your strings.

Validation

A schema lets a machine check configuration first

The filename: shop-apiport: "8080"env: productionreplicas: 3The schema says✓name: text, required✗port: an integer, 1 to 65535✗env: one of dev, test, prod✓replicas: an integer, 1 or moreRejected: 2 errorsin the pipeline, in secondsWithout the check, the same filefails in production instead.A schema states what valid configuration looks like, so that a machine can check it.This file is perfectly good YAML and is still wrong twice: the port is text, and the environment isnot one of the allowed names. JSON Schema describes the allowed keys, types and ranges for JSON andYAML alike. Editors use it to underline mistakes as you type; pipelines use it to stop a bad file.

Valid syntax is not valid configuration. A schema checks the meaning.

Validation · Going deeper · 1 of 2

Where a setting comes from

Highest priority firstA flag on the command line--log-levelnot setAn environment variableLOG_LEVELdebugthe first one that is set winsThe configuration filelog_level:infoThe default in the codewarnPORT=8080arrives in the program as the text '8080'. Environment variables are always strings.The service logs at debug, because the most specific source that is set wins.Environment variables are how one artefact is configured differently in each environment. Convertthem on reading: int(os.environ["PORT"]). Compare text, not truth: DEBUG=false is a non-empty string.

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

shop-api.schema.json (JSON Schema, draft 2020-12){ "type": "object", "required": ["name", "port"], "additionalProperties": false, "properties": { "name": {"type": "string"}, "port": {"type": "integer", "minimum": 1, "maximum": 65535}, "env": {"enum": ["dev", "test", "prod"]}, "replicas": {"type": "integer", "minimum": 1} }}What the validator reports (jsonschema 4.26 for Python)1typeport: "8080" gives '8080' is not of type 'integer'2enum'production' is not one of ['dev', 'test', 'prod']3additionalProperties: falsea misspelt key is an error: ('replcas' was unexpected)4requireda missing key is an error: 'name' is a required propertyA schema is itself a JSON document: types, ranges, allowed values and required keys.Without "additionalProperties": false a typing slip such as replcas passes, and the real setting quietly keeps itsdefault. One schema checks YAML and JSON alike, because both parse to the same data. Editors find a schema from a"$schema" line or the file name, which is how workflow files and Kubernetes manifests are underlined as you type.

Set additionalProperties to false, or a misspelt key passes unnoticed.

Lesson complete

You finished “Data formats”

Nicely done.

Open in a new tab