API Data Formats: JSON, YAML, and XML

APIs need an agreed way to represent data when sending a request or returning a response. JSON, YAML, and XML are text-based serialization formats commonly used for that purpose.

The format defines how data is written and parsed. The API contract or schema defines what the fields mean, which fields are required, and which values are valid.

Format, Schema, and Media Type

These terms describe different parts of the exchange:

Term	What it describes	Example
Data model	Structures supported by the format	JSON objects, arrays, and scalar values
Syntax	Characters and rules used to write those structures	{}, [], quotes, colons, and commas in JSON
Schema or API contract	Required fields, data types, constraints, and meaning	quantity must be an integer greater than zero
Media type	How an HTTP message labels its representation	Content-Type: application/json

Key Insight: Valid JSON is not automatically a valid API request. It can follow JSON syntax while missing a field required by the API.

The Same Data in Three Formats

The examples below represent the same logical data:

user
├── name: john
├── location
│   ├── city: Austin
│   └── state: TX
└── roles
    ├── admin
    └── user

YAML

user:
  name: john
  location:
    city: Austin
    state: TX
  roles:
    - admin
    - user

JSON

{
  "user": {
    "name": "john",
    "location": {
      "city": "Austin",
      "state": "TX"
    },
    "roles": [
      "admin",
      "user"
    ]
  }
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <name>john</name>
  <location>
    <city>Austin</city>
    <state>TX</state>
  </location>
  <roles>
    <role>admin</role>
    <role>user</role>
  </roles>
</user>

The three documents look similar, but their formal data models are different. JSON has objects and arrays, YAML has mappings and sequences, and XML has elements, attributes, and character data. An application decides how those structures map to its own objects.

Comparison

Aspect	JSON	YAML	XML
Core structure	Objects, arrays, and scalar values	Mappings, sequences, and scalars	Elements, attributes, and text
Typical API role	Request and response bodies	Configuration; supported by some APIs	APIs and standards built around XML
Human editing	Readable but punctuation-heavy	Usually the easiest of the three	Verbose but explicit
Comments	Not supported	# comment	<!-- comment -->
Whitespace	Mostly insignificant outside strings	Indentation defines structure	Passed to the application and may be significant
Namespaces	No built-in namespace system	No built-in namespace system	Standard namespace mechanism
Common file extension	.json	.yaml or .yml	.xml
HTTP media type	application/json	application/yaml	application/xml

JSON

JSON is a language-independent data-interchange format derived from JavaScript object syntax. It supports:

• objects containing name-value pairs
• arrays containing ordered values
• strings
• numbers
• true and false
• null

{
  "enabled": true,
  "retries": 3,
  "labels": ["api", "production"],
  "owner": null
}

Important syntax rules:

• Object member names must be strings in double quotes.
• Members and array elements are separated by commas.
• A trailing comma is not valid JSON.
• true, false, and null are lowercase.
• Whitespace outside strings is only formatting.
• A complete JSON document can contain any JSON value, although APIs commonly use an object or array at the top level.
• JSON exchanged between independent systems uses UTF-8.

The names inside a JSON object should be unique. Parsers handle duplicate names inconsistently: some keep the last value, some fail, and others preserve every occurrence.

YAML

YAML is designed to be comfortable for people to read and write. It represents data using:

• mappings for key-value associations
• sequences for ordered lists
• scalars for individual values

service:
  name: catalog
  enabled: true
  ports:
    - 8080
    - 8443

Important syntax rules:

• Indentation defines block structure.
• Use spaces for indentation. Tabs are not allowed as indentation characters.
• The amount of indentation is not fixed at two spaces, but it must remain consistent for sibling nodes.
• A dash introduces an item in a block sequence.
• Quotes are optional for many strings but useful when a value could be interpreted as another type.
• Comments begin with #.

YAML 1.2 was designed as a strict superset of JSON, meaning valid JSON can be treated as YAML 1.2. In practice, YAML libraries differ by supported version and schema, so an application should not assume that every YAML parser will interpret every value identically.

YAML is common in human-maintained configuration such as Kubernetes manifests and compose.yaml. It is not automatically the best API payload just because it is easy to read. The API decides which representations it accepts.

XML

XML represents a document as a tree of elements. Elements can contain text, attributes, or nested elements.

<service enabled="true">
  <name>catalog</name>
  <port>8080</port>
  <port>8443</port>
</service>

Important syntax rules:

• A well-formed document has one root element.
• Every non-empty start tag needs a matching end tag.
• Names are case-sensitive: <role> must close with </role>, not </Role>.
• Elements must be nested correctly.
• Attribute values must be quoted.
• Empty elements can use <element/>.

XML processors pass non-markup characters, including whitespace, to the application. A schema, parser configuration, or application may then decide whether formatting whitespace is meaningful. Do not assume that whitespace between elements is always discarded.

XML remains useful when an existing protocol or document standard requires it, when mixed text and markup matter, or when an ecosystem relies on XML Schema, XPath, or XSLT.

How an HTTP API Selects a Format

File extensions are useful for files stored on disk. HTTP messages normally identify their representation with headers:

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
 
{"name":"john","roles":["admin","user"]}

• Content-Type describes the body being sent.
• Accept tells the server which response media types the client prefers.

If the API accepts only JSON, changing the body to YAML while leaving Content-Type: application/json does not convert it. The server will try to parse the YAML as JSON and should reject the request.

Some protocols use more specific media types. RESTCONF, for example, uses application/yang-data+json and application/yang-data+xml for data modelled with YANG.

XML Namespaces

XML namespaces prevent collisions when the same local element name has different meanings.

<catalog
  xmlns:net="urn:example:network"
  xmlns:furn="urn:example:furniture">
  <net:port>GigabitEthernet0/1</net:port>
  <furn:table>Standing desk</furn:table>
</catalog>

net and furn are prefixes. Each prefix is bound to a namespace URI by an xmlns declaration. The URI identifies the namespace; it does not have to point to a downloadable webpage.

JSON and YAML have no equivalent built-in namespace mechanism. A particular specification can define its own naming convention. For example, the JSON encoding of YANG data uses names such as ietf-interfaces:interfaces, but that behaviour comes from the YANG JSON specification, not from JSON itself.

Note: RESTCONF and NETCONF are network-management topics. Their protocol operations, YANG models, and device configuration workflows belong in the Networking blog; only their data-format behaviour is relevant here.

Conversion Is Not Always Lossless

Simple mappings, lists, and scalar values can often be converted between formats. More complex documents may lose information:

• XML attributes, namespaces, mixed content, and element ordering need explicit mapping rules.
• YAML supports tags, anchors, aliases, and multiple documents in one stream.
• JSON has a smaller type system and no comments.
• Numbers and implicit scalar types can be interpreted differently by different libraries.

Use a schema or protocol-specific conversion rule when accuracy matters. Changing the file extension is never a conversion.

Choosing a Format

Situation	Practical choice
Consuming an existing API	Use the exact media type and schema documented by the API
Designing a typical HTTP API	JSON is usually the simplest interoperable default
Human-maintained configuration	YAML is often easier to edit
Existing XML protocol or document ecosystem	Use XML and its defined schema
Need to support several response formats	Implement explicit content negotiation and test every representation

Comfort matters only after compatibility. If an API accepts one format, the client must use that format.

Common Mistakes

• Treating .json, .yaml, or .xml as sufficient format identification in HTTP
• Sending a body that does not match its Content-Type
• Using tabs for YAML indentation
• Adding trailing commas or comments to JSON
• Assuming duplicate keys are handled consistently
• Assuming all XML whitespace is insignificant
• Treating JSON or XML well-formedness as business-level validation
• Assuming conversion between formats preserves every detail

TL;DR

• JSON, YAML, and XML serialize structured data using different formal models.
• The format defines representation syntax; the API contract defines meaning and constraints.
• JSON is common for HTTP request and response bodies.
• YAML is strongest as human-maintained configuration and is supported by some APIs.
• XML is explicit, schema-friendly, and still required by many established protocols.
• HTTP uses Content-Type and Accept to identify and negotiate representations.
• XML has a standard namespace mechanism; JSON and YAML do not.
• RESTCONF’s qualified JSON names come from YANG-specific rules.
• Use the format required by the API, even if another format looks easier.

Resources

• JSON Data Interchange Format — RFC 8259
• YAML 1.2.2 Specification
• YAML Media Type — RFC 9512
• XML 1.0 Specification — W3C
• Namespaces in XML 1.0 — W3C
• HTTP Semantics — RFC 9110
• RESTCONF Protocol — RFC 8040
• JSON Encoding of YANG Data — RFC 7951

Note: Format rules and media types were checked against the current specifications in July 2026.