Comparison
XML vs JSON: Why Documents Speak One and APIs the Other
The Split
Records Went One Way, Prose the Other
JSON won data interchange fair and square. API payloads are records — named fields, lists, numbers — and JSON is that shape: it maps directly onto the structures every language already has, with almost no syntax in the way. When people declare XML legacy, they're really describing this victory, and it's real.
But documents aren't records. They're mixed content: sentences with emphasis woven through them, warnings embedded mid-procedure, a part number mid-paragraph that links to its entry. Markup represents that natively — elements inside running text, in order. JSON has no honest way to say it; try, and you end up encoding text fragments and offset spans, reinventing markup badly. Which is why every serious document format — S1000D, DITA, DocBook, HTML itself — is markup. Add the layered validation stack regulated content depends on, and the document world's choice stops looking sentimental and starts looking structural.
The Synthesis
Two Layers, Not Two Camps
The false choice dissolves the moment you look at how a modern content services platform actually works. The documents live as structured markup — where mixed content, deep validation, and rendering pipelines belong. The APIs serving them speak JSON — because their consumers are applications asking for a page, a table of contents, a search result, and applications want records. Same content, two shapes, each chosen by its consumer. Our own Content Portal API is built precisely this way.
The takeaway for a buyer evaluating platforms: be suspicious of purity in either direction. A “modern” system that stores documents as JSON blobs has quietly discarded mixed content and the validation stack — ask it where the warning goes inside step four. A document system with no JSON delivery layer has kept the structure and forfeited the consumers. The mature answer speaks both, in their lanes — and knowing why lets you ask the question that separates the two in a single demo.
FAQ
Questions We Hear
Why did JSON win APIs so completely?
Because API payloads are data — records with named fields — and JSON is that shape natively: objects, arrays, numbers, strings, mapping directly onto the structures every programming language already has. No parsing ceremony, no attributes-versus-elements decisions, dramatically less syntax. For moving structured records between systems, JSON's simplicity is a genuine engineering advantage, which is why essentially every modern API speaks it.
What is mixed content, and why does it decide the document question?
Mixed content is text with markup woven through it: a sentence where three words are emphasized, a warning embedded mid-procedure, a paragraph containing a part number that links somewhere. XML represents this naturally — elements sit inside running text, in order. JSON has no native way to express it: you end up encoding spans with offsets, or nesting arrays of text fragments, reinventing markup badly. Documents are made of mixed content, which is why every serious document format — S1000D, DITA, DocBook, even HTML — is markup, not JSON.
Doesn't JSON have schemas too?
Yes — JSON Schema validates structure and types, and it's fine at what it does. But the document world's validation stack runs deeper: grammars that constrain element order and nesting, typed schemas, and rule languages like Schematron asserting cross-element logic — 'a warning must precede its step.' That layered enforcement is what regulated content depends on, and it grew up in the XML world because that's where the documents were. The gap is practical, not theological.
So which should our content platform use?
Both, in their lanes — and this is exactly how modern content services platforms work. The documents live as structured markup, where mixed content and deep validation belong. The APIs that serve them speak JSON, because the consumers are applications: a request for a page, a table of contents, a search result returns JSON envelopes that carry or reference the content. The formats aren't rivals in a well-designed system; they're the document layer and the delivery layer, each in the shape its job demands.
Get In Touch
Structure In, Services Out
Documents as markup, delivery as JSON — it's how we build. If your platform forces you to choose, bring us the demo question and watch what happens.