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

<p>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.</p><p>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.</p><p>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.</p><h2 id="why-xml-needed-attention">Why XML Needed Attention</h2><p>OpenAPI 3.1 could express a few basics, but it fell short when modelling XML such as:</p><ul><li>elements that mix attributes and child content</li><li>namespaced payloads</li><li>text content inside complex types</li><li>wrapped arrays with strict naming</li><li>schemas where element names differ from property names</li></ul><p>These gaps forced teams to maintain parallel XSDs, rely on proprietary extensions, or manually document XML behaviour in prose.</p><p>OpenAPI 3.2 closes many of these gaps.</p><h2 id="1-clear-namespace-support">1. Clear Namespace Support</h2><h3 id="before-openapi-3-1-">Before (OpenAPI 3.1)</h3><p>There was no clean way to define a namespace prefix. Tools guessed from XML examples or ignored the namespace entirely.</p><pre>xml: namespace: "http://acme.com/payments"</pre><p>No way to say which prefix to use. No way to ensure generated XML matched the contract.</p><h3 id="now-openapi-3-2-">Now (OpenAPI 3.2)</h3><p>Namespaces can define both the URI and the prefix, allowing accurate generation and parsing.</p><pre>xml: namespace: uri: "http://acme.com/payments" prefix: "pay"</pre><p>This is essential for enterprise XML that relies heavily on namespaced elements.</p><h2 id="2-more-accurate-representation-of-attributes">2. More Accurate Representation of Attributes</h2><h3 id="before">Before</h3><p>Attributes were possible but poorly defined. Adding both attributes and text content in the same structure often confused tools.</p><p>For example, this structure could not be expressed reliably:</p><pre><amount currency="USD">120.50</amount></pre><h3 id="now">Now</h3><p>OpenAPI 3.2 supports well defined attribute modelling alongside text content.</p><pre>type: object xml: name: amount properties: currency: type: string xml: attribute: true value: type: string xml: text: true</pre><p>The result closely mirrors the real XML rather than reducing everything to elements.</p><h2 id="3-proper-handling-of-wrapped-arrays">3. Proper Handling of Wrapped Arrays</h2><h3 id="before-1">Before</h3><p>Wrapped arrays were supported, but only at a basic level, and always assumed generic wrapping. Complex wrapped structures were impossible to describe.</p><p>For example, this common structure:</p><pre><items> <item>One</item> <item>Two</item> </items></pre><p>was supported, but:</p><pre><inventory> <products> <product>...</product> </products> </inventory></pre><p>could not be modelled with its multiple layers of specific element names.</p><h3 id="now-1">Now</h3><p>OpenAPI 3.2 allows precise control of wrapper element names.</p><pre>type: array xml: name: products wrapped: true items: xml: name: product</pre><p>More complex multi level wrappers now work predictably.</p><h2 id="4-more-faithful-complex-types-with-text-content">4. More Faithful Complex Types with Text Content</h2><h3 id="before-2">Before</h3><p>Mixed content was not representable. Any element containing both text and child elements was impossible to model correctly.</p><p>For example:</p><pre><note priority="high">This is a message <bold>sent today</bold></note></pre><p>This simply could not be expressed.</p><h3 id="now-2">Now</h3><p>OpenAPI 3.2 introduces clearer rules for text content inside objects.</p><pre>type: object xml: name: note properties: priority: type: string xml: attribute: true content: type: string xml: text: true bold: type: string</pre><p>Tools can now produce mixed content more consistently.</p><h2 id="5-cleaner-examples-with-namespaces-and-structure">5. Cleaner Examples with Namespaces and Structure</h2><p>XML examples can now be rendered exactly as intended.</p><h3 id="before-3">Before</h3><p>Examples were often rendered incorrectly because tools lacked information about prefixes, attribute ordering, or nested wrappers.</p><h3 id="now-3">Now</h3><p>An example such as:</p><pre>examples: simple: value: | <pay:transaction xmlns:pay="http://acme.com/payments"> <pay:amount currency="USD">120.50</pay:amount> </pay:transaction></pre><p>can be generated, documented, and validated correctly.</p><h2 id="why-this-is-important-for-enterprise-teams">Why This Is Important for Enterprise Teams</h2><p>These improvements mean:</p><ul><li>fewer separate XSDs to maintain</li><li>fewer vendor extensions</li><li>more predictable generated XML</li><li>documentation that finally matches real world XML</li><li>less confusion for partners integrating with legacy systems</li><li>better long term compatibility for platforms that cannot switch to JSON</li></ul><p>It is a practical modernisation of XML within OpenAPI, not a theoretical tweak.</p><h2 id="a-step-toward-real-enterprise-support">A Step Toward Real Enterprise Support</h2><p>OpenAPI has been strongly focused on JSON for years, but OpenAPI 3.2 broadens the specification to reflect the reality inside many large organisations.</p><p>By strengthening XML modelling, it gives developers a clear, standardised way to describe the formats they actually use.</p>