JSON vs XML vs YAML: How the Formats Differ

JSON, XML and YAML are three text formats for representing structured data. All three can describe the same information, so the choice is about trade-offs: how strict the rules are, how readable the text is to humans, whether comments are allowed, and what the tools around you expect. In short, JSON is the common choice for data exchanged between programs, XML suits documents and systems that need rich structure and validation, and YAML is popular for configuration files that people edit by hand.

One record, three ways

The clearest comparison is the same small record written in each format. Here is a person with a name, an age and two skills.

JSON:

{
  "name": "Asha",
  "age": 29,
  "skills": ["sql", "design"]
}

XML:

<person age="29">
  <name>Asha</name>
  <skills>
    <skill>sql</skill>
    <skill>design</skill>
  </skills>
</person>

YAML:

name: Asha
age: 29
skills:
  - sql
  - design

Even at this size you can see the character of each. JSON uses braces, brackets and quotes. XML wraps everything in named tags and has a second place for data, the attribute. YAML relies on indentation and has the least punctuation.

JSON: small and strict

JSON is defined by RFC 8259. It has a short list of building blocks: objects, arrays, strings, numbers, the two booleans and null. Keys are always strings in double quotes, and the grammar is tight, so a parser can be small and fast to write. That is one reason nearly every programming language has JSON support built in or available as a standard library.

The strictness has a cost. JSON has no comments, no trailing commas and no way to reuse a value. Numbers have a single form and no distinct date type, so dates travel as strings by convention. For hand-edited files this can feel limiting. If your JSON fails to parse, the guide on common JSON errors lists the usual causes.

XML: documents, attributes and validation

XML 1.0 is a W3C Recommendation. It describes a tree of elements with attributes and text, and it grew out of the world of document markup. Features that matter in practice include:

• Attributes and mixed content. Text can contain inline elements, which suits documents with marked-up paragraphs more naturally than the other two formats.
• Namespaces. They let you combine vocabularies from different sources without name clashes.
• Schemas. Languages built on top of XML can describe and validate the exact structure a document must have.
• Comments and processing instructions are part of the syntax.

The trade-off is length: element names are written out twice around each piece of content, and the language itself has no notion of a number or a list; everything is text unless a schema says otherwise. A list is simply a repeated element, as the skill tags above show, and whether a single item counts as a list or not depends on how the consuming code reads it.

YAML: readable and flexible

YAML describes itself as a human-friendly data serialization language. It represents three kinds of thing: mappings (key and value pairs), sequences (ordered lists) and scalars (single values). Structure comes from indentation, and comments start with a hash character. Beyond that, YAML supports multi-line text blocks, multiple documents in one file, and anchors and aliases that let you define a value once and reuse it.

The flexibility has traps:

• Indentation matters. A misaligned line changes the meaning or breaks the file. Tabs are not permitted for indentation.
• Implicit typing. An unquoted value can be read as a number, boolean or null depending on its look. Some parsers that follow older YAML 1.1 rules treat words like yes or no as booleans, which has surprised many people with country codes and similar data. Quoting the value avoids guessing.
• Version differences. Parsers differ in which YAML version and features they support, so a file that works in one tool may behave differently in another.

Because YAML 1.2 was designed to line up closely with JSON, a lot of JSON text is also valid YAML, but you should not rely on that for anything critical without testing it in your parser.

How they compare

| Aspect | JSON | XML | YAML | | --- | --- | --- | --- | | Comments | No | Yes | Yes | | Structure marked by | Braces and brackets | Tags | Indentation | | Built-in types | String, number, boolean, null, array, object | Text only (types via schema) | Scalars, sequences, mappings | | Typical use | Data exchange between programs | Documents, strict validation | Hand-edited configuration |

Use that table as a summary of the points above rather than a verdict; each format is the best fit somewhere.

Choosing between them

A few practical questions settle most cases:

1. Who or what reads it? If mostly programs, such as a web API, JSON is the usual default. If people edit it often, YAML or another comment-friendly format is easier.
2. Do you need validation against a formal structure? XML has mature schema tooling for that purpose, though schema systems also exist for JSON.
3. Is it a document with text and markup mixed together? XML handles that case directly.
4. What does the ecosystem already use? Following the format your tools, framework or partner systems expect usually beats picking on theoretical merit.

Converting between formats is possible but not always lossless. Comments, attributes, anchors and ordering do not map neatly from one format to another, and plain JSON cannot hold them.

Common mistakes

• Choosing YAML for data that machines write and read, then fighting indentation and typing quirks.
• Hand-writing JSON for a config file and forgetting that comments and trailing commas are not allowed.
• Using XML attributes in one place and child elements in another for the same kind of data, which makes consuming code messy.
• Leaving YAML values unquoted when they must stay strings, such as version numbers or codes.
• Assuming a conversion between formats keeps comments or structure details.

Quick checklist

• Decide the audience first: programs, people or both.
• Check whether you need comments, validation or mixed text.
• Quote ambiguous YAML values.
• Validate the file with a real parser before shipping it.

Related tools

When your data is JSON, the JSON formatter validates it and makes nested structures easy to read. Tokens often carry JSON in an encoded form, which the JWT decoder and the article on what a JWT is explain, and the Base64 encoder and decoder helps when a field holds encoded text.