Data & Formats · Lesson 02

Textual formats: JSON & XML

JSON conquered the web API world in under a decade — but XML never went away. Understanding both formats and their genuine trade-offs lets you make an informed choice instead of a reflex one.

JSON: the format that was already there

JSON — JavaScript Object Notation — won the web API wars not because it was invented in a standards body or optimized for computers, but because it was already inside every browser. When a JavaScript page needed to talk to a server in the early 2000s, parsing JSON was a one-liner: JSON.parse(text). That accidental head start became a permanent advantage once REST APIs and AJAX made browser-to-server calls routine.

The format itself is deliberately narrow. There are exactly six value types: string, number, boolean, null, array, and object. No dates, no binary blobs, no comments, no references. What looks like a limitation is actually the feature: any developer in any language can learn the entire format in an afternoon.

Why JSON won

Four concrete reasons explain JSON's dominance over earlier XML-heavy REST and SOAP approaches:

1. Zero parsing friction in the browser. JSON.parse() and JSON.stringify() are built into every JavaScript engine. No library, no schema, no namespace declarations.
2. Maps directly to native types. A JSON object becomes a Python dict, a Go struct, a Ruby Hash — the binding is mechanical. XML nodes have no such natural mapping; you need an ORM-like layer.
3. Readable without tooling. A developer can paste a JSON blob into a browser console or VS Code and immediately see the structure. This reduces debugging time dramatically.
4. Minimal syntax surface. The entire grammar fits on a postcard. Fewer rules mean fewer parser bugs and interop surprises.

JSON Schema: adding structure without abandoning flexibility

JSON's lack of a built-in schema is its main weakness for server validation. JSON Schema fills the gap: it's a JSON document that describes what another JSON document should look like — required fields, value types, string patterns, numeric ranges. Swagger/OpenAPI uses JSON Schema under the hood to describe every request and response body in an API.

// JSON Schema fragment — validates a User object
{
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "email": { "type": "string",  "format": "email" },
    "role":  { "type": "string",  "enum": ["admin", "viewer"] }
  },
  "additionalProperties": false
}

XML: the format that refused to die

XML (eXtensible Markup Language) predates JSON by a decade and was the default for web services throughout the 2000s via SOAP and WS-* protocols. It never really lost ground in the domains where it has genuine advantages.

XML excels at mixed content — text that contains markup interspersed with data, like a legal document with embedded annotations. JSON cannot represent "a paragraph of text with a bold section in the middle" without awkward workarounds; XML's element nesting handles it naturally. This is why the publishing industry, legal tech, and government document standards (DITA, DocBook, HL7 for healthcare) still use XML.

XML also has a mature ecosystem: XSD (XML Schema Definition) for strict structural validation, XSLT for declarative transformation, XPath/XQuery for querying. SOAP APIs built on these standards are still alive in banking, insurance, and enterprise middleware — not because XML is better, but because the toolchain is deeply embedded and migration risk is high.

Same document, two formats

Here is a simple invoice represented in both formats. Notice how XML's attributes and mixed-content nesting can describe a line item differently than JSON's flat key-value pairs, and how XML is nearly three times more verbose for this purely data-oriented example.

// JSON — 185 bytes
{
  "invoice": {
    "id":   "INV-2024-0042",
    "total": 149.99,
    "currency": "USD",
    "lines": [
      { "sku": "WDG-7", "qty": 2, "unit_price": 49.99 },
      { "sku": "SVC-1", "qty": 1, "unit_price": 50.01 }
    ]
  }
}

<!-- XML — 330 bytes -->
<invoice xmlns="urn:example:billing">
  <id>INV-2024-0042</id>
  <total currency="USD">149.99</total>
  <lines>
    <line sku="WDG-7" qty="2" unit_price="49.99"/>
    <line sku="SVC-1" qty="1" unit_price="50.01"/>
  </lines>
</invoice>

Trade-offs at a glance

Under the hood: how it actually works

When a runtime calls JSON.parse(), it runs two distinct phases. First, lexing/tokenizing: the parser scans bytes left-to-right, emitting a flat stream of tokens — STRING, NUMBER, TRUE, FALSE, NULL, {, }, [, ], :, and ,. There is no meaning yet, just classification. Second, value construction: the token stream is consumed recursively and assembled into the language's native type tree — a Python dict, a JavaScript object, a Go struct. The type a NUMBER token maps to is decided here, in the language runtime, not by the JSON spec itself. That is exactly where the IEEE-754 precision trap is introduced.

// IEEE-754 double precision: 53 bits of mantissa
// 2^53     = 9007199254740992  ← exactly representable
// 2^53 + 1 = 9007199254740993  ← requires 54 bits; rounds DOWN to 2^53

// JavaScript — silent precision loss
JSON.parse('{"id": 9007199254740993}').id
// → 9007199254740992  ✗ wrong! the last bit was silently dropped

// Safe fix: send the ID as a string
JSON.parse('{"id": "9007199254740993"}').id
// → "9007199254740993"  ✓ correct string; parse with BigInt() or int64
BigInt(JSON.parse('{"id": "9007199254740993"}').id)
// → 9007199254740993n  ✓

// Monetary amounts — IEEE-754 cannot represent 0.1 exactly
0.1 + 0.2
// → 0.30000000000000004  ✗  not 0.3
// So {"price": 0.1} decoded as float and summed gives wrong totals.
// Fix: use integer minor units  →  {"price_cents": 1099}  for $10.99

A JSON Schema validator works by walking the schema tree and the document tree in parallel, applying three categories of checks at each node: type checks (is this value actually a string?), constraint checks (does this number meet minimum? does this string match pattern? does this string length respect maxLength?), and required-field checks (are all keys listed in "required" present?). When a check fails, the validator records the JSON Pointer path to the offending node — for example #/items/0/price — so errors are precise and actionable rather than vague "invalid document" messages.

# Validate with Python's jsonschema library
python3 -c "
import jsonschema, json
schema = json.load(open('schema.json'))
data   = json.load(open('response.json'))
jsonschema.validate(data, schema)
print('valid')
"
# A violation prints: jsonschema.exceptions.ValidationError: 'foo' is not of type 'integer'
# with a .json_path pointing to the exact failing field.

# ajv-cli (Node.js) works similarly:
npx ajv validate -s schema.json -d response.json

How to debug & inspect it

1. Pipe the response through jq '.' or python3 -m json.tool to confirm it is valid JSON and see structure.
2. Check for numbers larger than 9007199254740992 (2⁵³) that should be IDs — flag them for string encoding.
3. Verify all date fields use ISO 8601 UTC format.
4. Run a JSON Schema validator against the response if a schema exists — it will pinpoint type mismatches precisely.
5. For encoding issues, hexdump -C the first 4 bytes: a BOM starts with ef bb bf 7b.

{
  "user_id":    9007199254741234,
  "balance":   49.99,
  "joined":    "March 15 2024",
  "last_login": "15-03-2024 09:32",
  "active":    "yes"
}

Sources & further reading

• MDN — JSON global object
• Understanding JSON Schema — json-schema.org
• RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format
• W3C — Extensible Markup Language (XML) 1.0 specification
• MDN — Number.MAX_SAFE_INTEGER (2^53 − 1)
• jq manual — command-line JSON processor