Before we touch syntax: what problem do JSON and YAML solve? They are ways to write down structured information — a person, a product, a server's settings — as plain text that both humans and programs can read. This is called serialization.
Imagine describing a student to a computer. In your head it's obvious: a name, an age, some courses, whether they've graduated. A data format is just an agreed way to write that down:
Student • name = Aisha • age = 27 • courses = JSON, YAML • graduated? = no
{
"name": "Aisha",
"age": 27,
"courses": ["JSON", "YAML"],
"graduated": false
}That text can now be saved to a file, sent across the internet, or read by another program written in any language. That's the whole point.
.txt note is unstructured — a program can't reliably find "the age". JSON and YAML are
structured: every value has a labelled place, so code can pull out exactly
age or courses[0] without guessing.
| You're doing… | The format | Example file / place |
|---|---|---|
| Calling a web API | JSON | the response from GET /users/42 |
| Node.js / npm project | JSON | package.json |
| Browser app state / config | JSON | tsconfig.json, settings.json |
| Running containers | YAML | docker-compose.yml |
| Kubernetes | YAML | deployment.yaml |
| CI/CD pipelines | YAML | .github/workflows/ci.yml |
| Ansible automation | YAML | playbook.yml |
Rough rule of thumb: machines exchange JSON (compact, unambiguous), and humans write YAML (less punctuation, easier to hand-edit). Both describe the same kinds of data.
| JSON | YAML | |
|---|---|---|
| Full name | JavaScript Object Notation | YAML Ain't Markup Language |
| Born | ~2001, from JavaScript | 2001, as a config-friendly format |
| Structure shown by | { }, [ ], commas | indentation (spaces) |
| Comments | ❌ not allowed | ✅ # like this |
| Best at | APIs, data exchange | configuration humans edit |
| Superset fact | Any JSON file is also valid YAML — YAML is a superset of JSON. | |
deployment.yaml is written in…# comments.