JSON, YAML, and XML are the three dominant data serialization formats in software development. Each was designed with different goals in mind, and choosing the wrong format for a given task creates unnecessary complexity. This guide gives you the precise technical knowledge to make the right choice.

JSON: The API Standard

JSON (JavaScript Object Notation) was introduced by Douglas Crockford in the early 2000s and formalized in RFC 8259 (2017). It directly maps to JavaScript primitives: objects, arrays, strings, numbers, booleans, and null.

{
  "server": {
    "host": "api.example.com",
    "port": 443,
    "tls": true
  },
  "features": ["auth", "ratelimit", "logging"]
}

• Strict syntax: All string keys must be double-quoted. No comments. No trailing commas.
• Data types: string, number, boolean, null, object, array.
• Native browser support: `JSON.parse()` and `JSON.stringify()` are built into every JavaScript engine.
• Specification: RFC 8259, minimal and unambiguous.

YAML: Human-Readable Configuration

YAML (YAML Ain't Markup Language) was created in 2001 with the explicit goal of being maximally human-readable. YAML 1.2 (2009) is technically a superset of JSON, meaning valid JSON is also valid YAML 1.2. However, YAML's parsing spec is considerably more complex, making it slower to parse and more prone to subtle bugs.

server:
  host: api.example.com
  port: 443
  tls: true

features:
  - auth
  - ratelimit
  - logging

# YAML supports comments (JSON does not)
# Anchors allow value reuse:
defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: prod.example.com

• Comments: YAML supports `#` single-line comments.
• Anchors and aliases: `&anchor` and `*alias` allow reusing values, reducing repetition.
• Indentation-sensitive: Indentation defines structure (not braces), which can cause subtle bugs.
• Multiple documents: A single YAML file can contain multiple documents separated by `---`.
• Type coercion: YAML 1.1 (used by PyYAML) treats `yes`, `no`, `on`, `off` as booleans, which catches many developers off guard. YAML 1.2 fixes this.

XML: The Enterprise Standard

XML (Extensible Markup Language) was standardized by the W3C in 1998. It is verbose but extraordinarily powerful: it has a rich ecosystem of standards including XPath (querying), XSLT (transformation), XML Schema (validation), DTD, and SOAP.

<?xml version="1.0" encoding="UTF-8"?>
<server>
  <host>api.example.com</host>
  <port>443</port>
  <tls>true</tls>
  <features>
    <feature>auth</feature>
    <feature>ratelimit</feature>
    <feature>logging</feature>
  </features>
</server>

• Attributes vs elements: XML supports both element text content and element attributes, enabling richer modeling.
• Namespaces: XML namespaces (`xmlns`) prevent element name collisions across vocabularies.
• Schema validation: XML Schema (XSD) provides rigorous type-safe validation.
• XSLT: XML can be transformed to HTML, PDF, or other XML formats via XSLT stylesheets.
• Comment support: `<!-- comment -->` supported natively.

Head-to-Head: Readability, Performance, and File Size

Using the same server configuration data shown above, here are real-world metrics:

• File size (same data): JSON ~120 bytes · YAML ~130 bytes · XML ~280 bytes
• Parse speed in browser: JSON is fastest (native V8/SpiderMonkey implementation). YAML is 5–15x slower (complex grammar). XML is 2–5x slower than JSON.
• Human readability ranking: YAML > JSON > XML (YAML wins when comments and anchors are used; JSON wins for simplicity).
• Tooling breadth: XML > JSON > YAML (XML has decades of enterprise tooling; JSON has universal REST API support).

When to Use JSON

• REST and GraphQL APIs: JSON is the universal API payload format. Every HTTP client library has built-in JSON support.
• Browser storage: localStorage, IndexedDB, and fetch responses all work natively with JSON.
• Inter-service communication: Microservices communicating over HTTP almost always use JSON.
• npm/package.json: Metadata for Node.js packages.
• Any scenario where file size and parse speed matter most.

When to Use YAML

• Infrastructure configuration: Kubernetes manifests, Docker Compose, GitHub Actions workflows, and Ansible playbooks all use YAML natively.
• Human-maintained config files: When humans write and review configs frequently, YAML's comment support and reduced boilerplate help.
• CI/CD pipelines: GitLab CI, CircleCI, Bitbucket Pipelines all use YAML.
• OpenAPI/Swagger specifications: Both JSON and YAML are valid; YAML is preferred for hand-authored specs due to comments.

When to Use XML

• SOAP web services: Enterprise systems (SAP, Oracle, banking mainframes) often expose only SOAP/XML interfaces.
• Document formats: DOCX, XLSX, SVG, and RSS/Atom feeds are all XML-based.
• Schema-validated data exchange: When recipient systems require strict type validation via XSD.
• Android resources: Android layout files, strings.xml, and manifests are all XML.
• Financial messaging: ISO 20022 financial messages use XML.

Converting Between Formats

Conversion between these formats always involves trade-offs because the type systems do not map perfectly:

• JSON → YAML: Lossless. Every JSON value maps to a valid YAML value. Comments are not preserved (JSON has none).
• YAML → JSON: Mostly lossless, but YAML anchors, multi-document files, and comments are lost. YAML-specific types (e.g., timestamps) may need special handling.
• JSON → XML: Requires choosing a root element name (JSON has no root element concept). Arrays become repeated elements or a wrapper element.
• XML → JSON: Attributes and elements need a mapping convention. Namespaces have no JSON equivalent.