XML Modelling in OpenAPI 3.2: A Quiet but Important Upgrade for Enterprise Teams

JSON may dominate modern API design, but XML remains deeply embedded in many enterprise systems. Banks, insurers, logistics networks, public sector systems, and large internal platforms all continue to rely on XML for structured, strongly typed data.

OpenAPI had XML support before, but it was limited. It worked for simple examples, but it could not accurately represent real enterprise XML formats with namespaces, attributes, wrapped arrays, or mixed content.

OpenAPI 3.2 changes that. It introduces clearer, more expressive XML modelling that finally lets teams describe their XML in a faithful and predictable way.

Why XML Needed Attention

OpenAPI 3.1 could express a few basics, but it fell short when modelling XML such as:

• elements that mix attributes and child content
• namespaced payloads
• text content inside complex types
• wrapped arrays with strict naming
• schemas where element names differ from property names

These gaps forced teams to maintain parallel XSDs, rely on proprietary extensions, or manually document XML behaviour in prose.

OpenAPI 3.2 closes many of these gaps.

1. Clear Namespace Support

Before (OpenAPI 3.1)

There was no clean way to define a namespace prefix. Tools guessed from XML examples or ignored the namespace entirely.

xml:
  namespace: "http://acme.com/payments"

No way to say which prefix to use. No way to ensure generated XML matched the contract.

Now (OpenAPI 3.2)

Namespaces can define both the URI and the prefix, allowing accurate generation and parsing.

xml:
  namespace:
    uri: "http://acme.com/payments"
    prefix: "pay"

This is essential for enterprise XML that relies heavily on namespaced elements.

2. More Accurate Representation of Attributes

Before

Attributes were possible but poorly defined. Adding both attributes and text content in the same structure often confused tools.

For example, this structure could not be expressed reliably:

<amount currency="USD">120.50</amount>

Now

OpenAPI 3.2 supports well defined attribute modelling alongside text content.

type: object
xml:
  name: amount
properties:
  currency:
    type: string
    xml:
      attribute: true
  value:
    type: string
    xml:
      text: true

The result closely mirrors the real XML rather than reducing everything to elements.

3. Proper Handling of Wrapped Arrays

Before

Wrapped arrays were supported, but only at a basic level, and always assumed generic wrapping. Complex wrapped structures were impossible to describe.

For example, this common structure:

<items>
  <item>One</item>
  <item>Two</item>
</items>

was supported, but:

<inventory>
  <products>
    <product>...</product>
  </products>
</inventory>

could not be modelled with its multiple layers of specific element names.

Now

OpenAPI 3.2 allows precise control of wrapper element names.

type: array
xml:
  name: products
  wrapped: true
items:
  xml:
    name: product

More complex multi level wrappers now work predictably.

4. More Faithful Complex Types with Text Content

Before

Mixed content was not representable. Any element containing both text and child elements was impossible to model correctly.

For example:

<note priority="high">This is a message <bold>sent today</bold></note>

This simply could not be expressed.

Now

OpenAPI 3.2 introduces clearer rules for text content inside objects.

type: object
xml:
  name: note
properties:
  priority:
    type: string
    xml:
      attribute: true
  content:
    type: string
    xml:
      text: true
  bold:
    type: string

Tools can now produce mixed content more consistently.

5. Cleaner Examples with Namespaces and Structure

XML examples can now be rendered exactly as intended.

Before

Examples were often rendered incorrectly because tools lacked information about prefixes, attribute ordering, or nested wrappers.

Now

An example such as:

examples:
  simple:
    value: |
      <pay:transaction xmlns:pay="http://acme.com/payments">
        <pay:amount currency="USD">120.50</pay:amount>
      </pay:transaction>

can be generated, documented, and validated correctly.

Why This Is Important for Enterprise Teams

These improvements mean:

• fewer separate XSDs to maintain
• fewer vendor extensions
• more predictable generated XML
• documentation that finally matches real world XML
• less confusion for partners integrating with legacy systems
• better long term compatibility for platforms that cannot switch to JSON

It is a practical modernisation of XML within OpenAPI, not a theoretical tweak.

A Step Toward Real Enterprise Support

OpenAPI has been strongly focused on JSON for years, but OpenAPI 3.2 broadens the specification to reflect the reality inside many large organisations.

By strengthening XML modelling, it gives developers a clear, standardised way to describe the formats they actually use.