JSON vs XML vs YAML: Choosing the Right Data Format

JSON, XML, and YAML all solve the same basic problem — representing structured data as readable text — and any one of them can express the exact same information as the other two. The real differences are practical: how much you have to type, whether you can leave a comment explaining a value, how forgiving the syntax is of small mistakes, and which ecosystem each format has become the default in. This guide puts all three side by side on identical data, works through the syntax tradeoffs that actually matter day to day, and covers the specific gotchas that catch people off guard in each format.

The same data, three ways

Here's one small user record — a name, age, active flag, a list of roles, and a nested address — written out in full in all three formats.

JSON:

{
  "name": "Ana Silva",
  "age": 29,
  "active": true,
  "roles": ["admin", "editor"],
  "address": {
    "city": "Lisbon",
    "country": "Portugal"
  }
}

XML:

<user>
  <name>Ana Silva</name>
  <age>29</age>
  <active>true</active>
  <roles>
    <role>admin</role>
    <role>editor</role>
  </roles>
  <address>
    <city>Lisbon</city>
    <country>Portugal</country>
  </address>
</user>

YAML:

name: Ana Silva
age: 29
active: true
roles:
  - admin
  - editor
address:
  city: Lisbon
  country: Portugal

All three describe exactly the same record. Notice immediately how much more compact YAML is compared to XML for the same data — no closing tags, no brackets, just indentation — while JSON sits in between, using brackets and braces but no repeated tag names.

Syntax tradeoffs

Property	JSON	XML	YAML
Verbosity	Moderate	High (repeats tag names)	Low (whitespace-based)
Human readability	Good	Fair (nesting gets busy)	Very good
Comments supported	No	Yes (<!-- -->)	Yes (#)
Native data types	Strings, numbers, booleans, null	Everything is text by default	Strings, numbers, booleans, null
Whitespace-sensitive	No	No	Yes (indentation is structural)
Schema validation	JSON Schema	XSD, DTD	No native standard (often borrows JSON Schema)
Attributes vs. elements	Not applicable	Both exist, adding ambiguity	Not applicable

Comments: a genuinely practical difference

This is one of the most concrete, everyday-relevant differences between the three formats. JSON has no comment syntax whatsoever — not //, not /* */ — by deliberate design choice, to keep every JSON parser simple and unambiguous. XML and YAML both support real comments:

<!-- XML comment: this endpoint is deprecated, use /v2 instead -->
<endpoint>/v1/users</endpoint>

# YAML comment: this endpoint is deprecated, use /v2 instead
endpoint: /v1/users

This single difference is a major practical reason YAML dominates hand-edited configuration files (where explaining why a setting exists matters) while JSON dominates machine-to-machine API payloads (where a comment would serve no purpose, since nothing reads the file by eye). If you need documented JSON specifically, some tools support supersets like JSONC or JSON5 that add comment support — but that's an extension, not standard JSON, and a strict JSON parser will reject it.

Where each format is used today

JSON: REST APIs and the JavaScript ecosystem

JSON is the default payload format for essentially every modern REST API, because it parses natively into JavaScript objects with zero library code (hence the name) and every other mainstream language now ships a JSON parser in its standard library. It's also the format behind package.json, most modern app configuration, and NoSQL databases like MongoDB that store documents natively as JSON-like structures.

XML: legacy enterprise systems, SOAP, and schema-validated documents

XML predates JSON as the general-purpose data interchange format, and it persists heavily in systems built during that earlier era: SOAP web services, enterprise integration middleware, and document formats that need strict, externally-defined validation via an XML Schema Definition (XSD) — common in finance, healthcare (HL7), and government data exchange where a document's structure needs to be formally guaranteed before it's accepted. XML also remains the underlying format inside Microsoft Office files (a .docx file is literally a zip archive of XML documents) and RSS/Atom feeds.

YAML: configuration files and CI/CD pipelines

YAML has become the dominant format for anything meant to be hand-written and hand-edited by a developer: Docker Compose files, Kubernetes manifests, GitHub Actions and GitLab CI pipeline definitions, and Ansible playbooks all use YAML specifically because of its low visual noise and native comment support — both genuinely valuable when a human is going to be reading and modifying the file directly, rather than a program generating and consuming it automatically.

Common gotchas

YAML's whitespace sensitivity

YAML uses indentation to represent nesting, the same way Python uses indentation for code blocks — which means a misplaced space can silently change what a document means, or break it outright. Two specific rules catch people constantly: YAML indentation must use spaces, never tabs (most parsers reject tabs outright), and the exact number of spaces used for one level of nesting must stay consistent throughout a sibling block.

The "Norway problem"

This is YAML's most infamous gotcha. Under the YAML 1.1 specification (still the version many parsers implement), a handful of unquoted bare words are automatically interpreted as booleans — including yes, no, on, off, true, and false, in various letter cases. This becomes a genuine problem the moment your data happens to contain the two-letter ISO country code for Norway — NO — unquoted:

# This looks like it stores the string "NO" for Norway...
country: NO

...but many YAML 1.1 parsers instead silently interpret NO as the boolean false, turning a country code into an unrelated boolean value with no warning at all. The fix is simple once you know the trap exists: always quote any value that could be misread as a boolean, number, or null:

# Explicitly quoted — this is unambiguously the string "NO"
country: "NO"

This exact issue has caused real, documented outages and data-corruption bugs in production systems, which is why it's worth specifically checking for country codes, ISO currency codes, and similar short bare-word values whenever writing YAML by hand.

JSON's zero tolerance for trailing commas

Unlike YAML and several other lenient formats, JSON never allows a trailing comma after the last item in an object or array:

{ "a": 1, "b": 2, }

That trailing comma after 2 makes this entire document invalid — a single character that will fail an entire API response or config load. This is an extremely common mistake when editing JSON by hand, especially after deleting what used to be the last field and forgetting to also remove the comma before it.

XML's verbosity for deeply nested data

Because every XML element needs both an opening and a matching closing tag, deeply nested data structures grow noticeably larger and harder to visually scan than the equivalent JSON or YAML — a document nested five levels deep repeats five different closing tags at the bottom, each of which has to be manually matched back up to its corresponding opening tag by eye when debugging. XML also introduces a design decision JSON and YAML don't have to make at all: whether a piece of data should be an attribute (<user id="42">) or a child element (<user><id>42</id></user>) — both are valid, and different codebases make this call differently, adding a layer of inconsistency that simply doesn't exist in JSON or YAML.

Converting between formats

It's common to need the same data in a different format than the system you're integrating with expects — pulling a JSON API response into a legacy XML-based system, or turning a YAML Kubernetes manifest fragment into JSON for a script to parse programmatically. DocNectar's JSON to XML Converter and YAML ⇄ JSON Converter handle exactly this kind of conversion directly in the browser, without needing to hand-translate the structure yourself.

Which should you choose?

In practice, the choice is rarely a free preference — it's dictated by what the system you're talking to already expects. If you're building a new web API, JSON is the overwhelming default. If you're writing configuration a human will read and edit directly, YAML's compactness and comment support make it the better fit. If you're integrating with an existing enterprise system that already communicates in XML, or you need formal schema validation via XSD for a document that must be structurally guaranteed correct, XML remains the right tool rather than something to migrate away from.

Frequently asked questions

Is YAML a superset of JSON?

Effectively yes under the YAML 1.2 specification — valid JSON is (with very minor edge cases) also valid YAML, since YAML 1.2 was deliberately designed to be a superset of JSON. This is why a .yaml file containing plain JSON syntax will generally parse correctly with a YAML parser.

Can XML represent lists and arrays?

Yes, conventionally by repeating an element name for each item, exactly as shown in the <roles> example above — XML has no dedicated "array" syntax the way JSON and YAML do, so the convention is inferred from context rather than being a first-class language feature.

Which format parses fastest?

JSON generally parses fastest in practice, owing to its simple, fully-specified grammar. XML parsing tends to carry more overhead from building a full DOM tree and validating against namespaces/schemas. YAML's more permissive, feature-rich specification (anchors, multi-document files, multiple ways to write the same value) generally makes it noticeably slower to parse than JSON for equivalent data, which is one reason it's rarely used for high-throughput API payloads.

Does JSON support dates as a native type?

No — none of the three formats have a native date type. JSON, XML, and YAML all represent dates as plain strings (commonly ISO 8601 format, like "2026-07-18"), and it's up to the application reading the data to parse that string into an actual date value.

Work with your data

DocNectar's JSON Formatter validates and pretty-prints any JSON document, the JSON to XML Converter translates JSON into well-formed XML, and the YAML ⇄ JSON Converter converts cleanly in either direction — all free, directly in your browser.