JSON vs XML vs YAML: Differences and When to Use Each

Here is one small record, written in each format.

{
  "user": {
    "id": 42,
    "name": "Asha",
    "active": true,
    "roles": ["admin", "beta"]
  }
}

<user id="42">
  <name>Asha</name>
  <active>true</active>
  <roles>
    <role>admin</role>
    <role>beta</role>
  </roles>
</user>

# a user record
user:
  id: 42
  name: Asha
  active: true
  roles:
    - admin
    - beta

Notice what each format spends characters on. JSON needs quotes and braces. XML repeats every name in a closing tag. YAML relies on indentation and has almost no punctuation, which makes it the most compact to read but also the easiest to break with a misplaced space.

JSON has exactly six kinds of values: objects, arrays, strings, numbers, booleans and null. That small, strict grammar is its strength. Parsers exist in every language, behave almost identically, and are fast. It maps directly onto the dictionaries, lists and primitives that programming languages already have.

• Strengths: simple, universal, compact, native in browsers and JavaScript, excellent tool support.
• Weaknesses: no comments, no date type, no way to reference or reuse a value, and no built-in schema (JSON Schema is a separate standard).
• Best for: web and mobile APIs, data exchange between services, browser storage, and configuration that is generated or read by programs more than by people.

XML is a markup language, not just a data format. It can mix text and elements (as in a paragraph with bold words inside it), carry metadata in attributes, mix vocabularies from different sources with namespaces, and be validated against schemas such as XSD. Query and transformation languages such as XPath and XSLT are built around it.

• Strengths: supports comments, attributes and mixed content, mature schema validation, namespaces, and a large ecosystem in enterprise and publishing.
• Weaknesses: verbose, no native arrays, numbers or booleans (everything is text until a schema says otherwise), and more complex to parse safely.
• Best for: document formats (office files, SVG, RSS and Atom feeds), SOAP and other enterprise integrations, and systems that already rely on XSD contracts.

YAML was designed to be pleasant to read and write. It supports comments, multi-line text, several documents in one file, and anchors and aliases to reuse a block. Since YAML 1.2 it is, for practical purposes, a superset of JSON, so most JSON documents are also valid YAML.

• Strengths: very readable, comments, less noise, reuse through anchors.
• Weaknesses: indentation is significant and tabs are not allowed for it; values are typed by guessing, which can surprise you; and parsers differ between YAML versions.
• Best for: hand-edited configuration such as Kubernetes manifests, CI pipelines and application settings.

Two YAML traps to know

country: NO        # parsed as boolean false by YAML 1.1 parsers (the "Norway problem")
version: 1.10      # parsed as the number 1.1, not the string "1.10"
zip: 02134         # may be read as an octal number by some parsers

Also be careful with untrusted YAML. Some libraries can construct arbitrary objects from tags in the file. In Python, use yaml.safe_load rather than yaml.load for input you do not control.

1. Is it an API or data exchanged between programs? Use JSON unless a partner requires otherwise.
2. Do people edit it by hand and need comments? Use YAML (or a format like TOML). Keep files small and quote ambiguous values.
3. Is it a document with mixed text and markup, or do you need namespaces and strict schemas? Use XML.
4. Do you have to match an existing system? Follow what it already speaks, and convert at the boundary.

Converting is easy for plain data, but some information has no home in the target format:

• Converting YAML or XML to JSON loses comments.
• XML attributes and elements both become keys in JSON, so a tool has to pick a convention, such as prefixing attribute names.
• A single XML element can mean either an object or a one-item array, which is ambiguous in JSON.
• Numbers and booleans in XML are text, so a converter either guesses types or leaves them as strings.
• YAML anchors are expanded when converting to JSON, so the shared structure is duplicated.

After any conversion, spot-check a few records and compare the result with the source, rather than trusting it blindly.