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

By the numbers

Textual data formats trade parse speed and size for human readability. However, format syntax overhead (tags, quotation marks, curly braces) quickly scales with record count. While compression (Gzip/Brotli) mitigates this, it introduces CPU decoding costs.

Governing Formulas:

JSON_Size = 2 + N * (Record_JSON_Payload + 1) - 1  # includes outer brackets and comma separators
XML_Size = 30 + N * Record_XML_Payload             # includes root tags <transactions>
CSV_Size = Header_Size + N * Record_CSV_Payload
Compressed_Size = Uncompressed_Size * Compression_Ratio

Assuming a single record takes 110 bytes in JSON, 210 bytes in XML, and 55 bytes in CSV, here is a byte size trace as we scale the collection size N:

Decision Math (Compression and Bandwidth Cost):

For a bulk download of 10,000 transactions, let's examine the network size under Gzip compression:

• JSON (Compression Ratio 0.20): 1,100,000 bytes * 0.20 = 220,000 bytes.
• XML (Compression Ratio 0.14 - redundant tags compress better): 2,100,300 bytes * 0.14 = 294,042 bytes.
• CSV (Compression Ratio 0.25): 550,035 bytes * 0.25 = 137,508 bytes.

CSV remains the most bandwidth-efficient textual format, saving 82,492 bytes (37.5%) over compressed JSON. However, JSON remains the industry default for APIs because client-side parsing engines (like V8's native JSON.parse) are optimized in C++ and decode JSON 5x faster than custom JS-based CSV parsers.

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.

When not to use this format

• JSON over binary when humans and browsers debug the wire and payload size is not the bottleneck.
• Binary / Protobuf when you need ad-hoc queryability in logs without schema registries and your team is not proto-fluent.
• Do not dual-support forever without a sunset plan — dual formats double test and versioning surface.

Why encoding choices are API design

Encoding is a contract: schema evolution, partial reads, size on the wire, and CPU at the edge. Text formats buy debuggability and loose coupling; binary formats buy density and typed evolution. Standout engineers quantify bytes × QPS before religious wars.

Failure modes

• Schema change without additive compatibility → hard client break.
• Content-Type mismatch / wrong charset → silent corruption or 400 storms.
• Huge nested JSON without field masks / pagination → tail latency and OOM.

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

When not to use JSON (or XML)

• High-QPS internal pipelines — prefer Protobuf/Avro (see df-03) once both ends share a schema.
• Money fields as JSON numbers — never; use integer minor units or decimal strings (IEEE 754 cannot represent many cents exactly).
• Integers above 2⁵³−1 in browsers/JS — send as strings.
• XML for greenfield public HTTP APIs — only when a partner mandate or document model requires it; JSON is the modern default.

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