JSON or XML today: migration and coexistence

How the data models differ, what has no JSON equivalent, converting between the formats without losing meaning, and a checklist for running both behind one API.

Two data models, not two syntaxes

<!-- XML: the language is an attribute, the text is content -->
<message lang="en">Hello</message>

<!-- JSON has no place for the attribute except as a key -->
{ "lang": "en", "text": "Hello" }

The single-item list ambiguity is the most damaging difference. A converter cannot know whether one <item> should become an array of one or an object, and guessing wrong breaks every consumer.

Converting without losing meaning

<!-- a convention that survives a round trip: mark attributes and types -->
<order id="1">
  <placedAt type="date">2026-09-18</placedAt>
  <items>
    <item sku="A1" qty="2"/>
  </items>
</order>

{
  "@id": "1",
  "placedAt": "2026-09-18",
  "placedAtType": "date",
  "items": { "item": [ { "@sku": "A1", "@qty": "2" } ] }
}

1. Decide a convention for attributes and for single-item lists, and write it down before converting anything.
2. Preserve order where the consumer depends on it, or change the consumer first.
3. Convert types explicitly; everything in XML is a string until your mapping says otherwise.
4. Keep the original XML alongside the converted form during the transition, so a wrong conversion is reversible.
5. Round-trip a representative fixture and diff both directions. A conversion that is not round-trip stable is not done.
6. Publish the new format to one consumer, compare behaviour, then widen.

Running both behind one API

GET /v2/orders/1024 HTTP/1.1
Accept: application/xml;q=0.9, application/json;q=1.0

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Vary: Accept

{"id":"1024","total":{"amount":"19.99","currency":"EUR"}}

• One internal model, two serialisers. Never let either wire format become the domain model.
• Negotiate with Accept and set Vary: Accept so caches do not mix the representations.
• Generate both from the same contract — an XSD with a JSON Schema, or a single definition with two generators.
• Keep error shapes parallel so a client that switches format sees the same fields.
• Measure real usage before removing either; some consumers will still be on the old format years later.
• Set a removal date and a deprecation header so the last consumer has a deadline, not a surprise.

def serialise(order, media_type):
    if media_type == "application/json":
        return json.dumps(to_dict(order)), "application/json"
    if media_type == "application/xml":
        return to_xml_string(order), "application/xml"
    raise UnsupportedMediaType(media_type)

def to_dict(order):
    """The internal model is the source of truth for both formats."""
    return {
        "id": str(order.id),
        "total": {"amount": f"{order.total:.2f}", "currency": order.currency},
    }

FAQ

Related

SVG, XHTML and XML in the browser Attributes vs child elements: modelling decisions

Last refreshed 2026-09-18.