YAML vs JSON vs XML: Which to Use

The same information can be written as JSON, YAML or XML. The choice is not taste: each was designed for a different job, and using one outside its job is where the irritating bugs come from.

JSON: for machines talking to machines

JSON is deliberately tiny. Objects, arrays, strings, numbers, booleans, null — that is the whole specification. No comments, no dates, no references, no schema. Every language parses it, every parser agrees on what it means, and there is essentially nothing to argue about.

That minimalism makes it the right default for APIs, configuration written by tools, and data interchange. It makes it a poor choice for configuration written by hand, for two reasons everyone eventually hits: you cannot leave a comment, and a single trailing comma is a hard error. If you are formatting or checking a large one, the JSON formatter will point at the exact offset rather than making you count brackets.

Two real limitations worth knowing. JSON has one number type, and large integers lose precision when they pass through a parser that maps numbers to 64-bit floats — which is why IDs are so often quoted as strings. And there is no date type at all; every date in JSON is a string by convention, usually ISO 8601, and interpreting it is your problem.

YAML: for configuration written by people

YAML exists to be comfortable to type and read. Comments, no brackets, multi-line strings that keep their formatting, anchors to avoid repeating a block. This is why CI pipelines, Kubernetes manifests, Docker Compose files and countless application configs use it.

The price is that significant whitespace and a permissive type system make YAML the format most likely to mean something you did not intend:

• Indentation is syntax. Two spaces in the wrong place silently changes structure. Tabs are not allowed at all. Mixed indentation is the most common YAML bug in existence.
• The Norway problem. In YAML 1.1, unquoted no, yes, on and off are booleans — so the country code NO becomes false. Modern parsers largely follow YAML 1.2, which fixed this, but you will still meet files and tools that do not.
• Accidental types. version: 1.10 is the number 1.1. 08 may be invalid or may be octal. A time-like 12:30 can parse as something surprising. Quote anything that is really a string.
• It is a superset of JSON. Any valid JSON is valid YAML, which is occasionally very convenient.

The habit that prevents most of this: quote strings that could be read as another type, and validate the file rather than trusting your eyes. Converting to JSON with YAML to JSON is a quick way to see what a parser actually thinks your YAML says — if a version number arrives as a float, you found a bug before production did.

XML: for documents and contracts

XML is the verbose one, and the verbosity buys things the others do not have. Attributes alongside element content. Namespaces, so two vocabularies can be mixed without collision. Real schema languages that let you validate a document against an agreed contract before processing it. Mature tooling for querying and transforming.

It remains the right answer in document-centric and regulated settings: office formats, publishing, invoicing standards, SOAP services, industrial exchange formats. If a standards body defined your format, it is probably XML, and you should not fight it.

The friction is mapping it to the other two. XML distinguishes attributes from child elements, allows repeated elements and mixed content, and preserves order — none of which JSON objects represent naturally. Any conversion has to pick a convention, so XML to JSON is genuinely lossy in structure even when no information is lost. Round-tripping XML through JSON and back will not give you the file you started with.

Choosing, in one line each

• An API or data between programs? JSON.
• A file humans edit, with comments? YAML — quote your strings.
• A document, a namespace, or a schema you must validate against? XML.
• A flat table? None of them. Use CSV — CSV versus JSON covers when a table beats a tree.

Conversions run entirely in your browser, which is worth noting given how often a config file contains an API key, a connection string or a password. Pasting that into a random online converter is a credential disclosure; nothing here is transmitted.