JSON vs YAML vs XML: syntax, use cases and how to convert between them

JSON, YAML and XML are all plain-text formats for structured data. Give them the same information and they will all describe it faithfully, yet in practice each one has settled into its own territory: JSON in APIs, YAML in configuration files, XML in documents and enterprise systems. Knowing why helps you pick the right one and avoid surprises when you convert.

The same data in three formats

Here is a small service definition written three ways. First, JSON:

{
  "service": "web",
  "port": 8080,
  "debug": false,
  "tags": ["api", "public"]
}

The same thing in YAML:

# web service
service: web
port: 8080
debug: false
tags:
  - api
  - public

And in XML:

<?xml version="1.0" encoding="UTF-8"?>
<service name="web">
  <port>8080</port>
  <debug>false</debug>
  <tags>
    <tag>api</tag>
    <tag>public</tag>
  </tags>
</service>

A few differences jump out immediately:

• JSON uses braces, brackets and quotes. It is strict: no comments, no trailing commas, keys always in double quotes.
• YAML relies on indentation instead of brackets and allows comments with #. It is the most compact and the easiest to read at a glance.
• XML wraps every value in opening and closing tags and can attach attributes to elements (name="web"). It is the most verbose, but also the most expressive.

JSON: the language of APIs

JSON maps directly onto the objects and arrays of almost every programming language, which is why it became the default format of web APIs. Parsers are fast, built into browsers and standard libraries, and the grammar is small enough that there are very few ways to misread a document.

Its strictness is a feature for machines and a small annoyance for people. You cannot leave a comment explaining a setting, and a single missing comma breaks the whole file. That is why JSON works best when software writes it and software reads it: API responses, logs, data exports, package.json.

YAML: configuration written by humans

YAML was designed to be written and reviewed by people. That is why so many DevOps tools chose it: Kubernetes manifests, GitHub Actions workflows and Docker Compose files are all YAML. Comments, multi-line strings and the lack of punctuation make long configuration files pleasant to maintain.

The price is subtlety. Indentation is meaningful, so a misplaced space changes the structure. And YAML guesses types from unquoted values, which leads to its most famous traps:

country: NO      # YAML 1.1: false
version: 1.10    # 1.1 (number)
zip: 01234       # 1234 or octal

Under YAML 1.1 rules, still used by many parsers, NO, yes, on and off become booleans. Numbers with trailing zeros lose them, and leading zeros may be read as octal. The fix is simple: quote anything that must stay a string.

country: "NO"
version: "1.10"
zip: "01234"

XML: documents, schemas and enterprise feeds

XML is older than the other two and carries features they lack: namespaces to mix vocabularies, schemas (XSD) to validate structure strictly, attributes, and mixed content where text and tags interleave. That makes it a natural fit for documents and for systems where a formal contract matters: RSS and Atom feeds, SOAP services, invoicing and banking standards, SVG images, Maven's pom.xml, and the files inside a DOCX or XLSX.

If you are building something new and just need to exchange data, XML is rarely the first choice. But you will keep receiving it from partners, legacy systems and public data feeds, so knowing how to turn it into JSON is a practical skill.

Quick comparison

• Readability: YAML > JSON > XML.
• Strictness and predictability: JSON and XML are unambiguous; YAML depends on indentation and type guessing.
• Comments: YAML and XML yes, JSON no.
• Validation: XML has the most mature schema tooling; JSON Schema is widely used; YAML is usually validated through JSON Schema too.
• Typical home: JSON for APIs and data, YAML for configuration, XML for documents and enterprise integration.

Converting between them: what to watch for

Because all three describe trees of data, converting is usually straightforward. A few details are worth knowing, though:

• YAML to JSON drops comments. JSON has nowhere to put them. Anchors and aliases (& and *) are expanded into plain copies.
• JSON to YAML is lossless. Every valid JSON document can be expressed in YAML; in YAML 1.2, JSON is almost a subset of YAML.
• XML attributes need a convention. JSON has no attributes, so converters store them as ordinary keys, often marked with a prefix such as @. Check the output before feeding it to another program.
• Single items versus lists. In XML, one <tag> and three <tag> elements look alike. Converted to JSON, one may become an object and the other an array, so code that consumes the result should handle both.
• Types become text in XML. 8080 and false are just characters inside tags; going from XML to JSON, you may need to cast them back.
• JSON to XML needs a single root and keys that are valid element names (no spaces, not starting with a digit).

Convert in your browser

Azpy's data converters run entirely in your browser: paste your text or drop a file, and the result appears instantly without anything being uploaded. That makes them safe for configuration files with internal hostnames or API responses with customer data. You will find JSON to YAML, YAML to JSON, XML to JSON and JSON to XML among the tools.

A rule of thumb

Machines talking to machines → JSON. Humans editing configuration → YAML, with quotes around anything ambiguous. Documents, strict schemas or an existing enterprise contract → XML. And when the format you have is not the one you need, convert it and check the edge cases above.