Overview

Swagger-OpenAPI 2.0 and 3.0 have limited support for XML.


While OpenAPI specifications can use any media type, request and response message schemas are specified using Schema Objects, based on JSON Schema. Schema Objects, in combination with the optional XML Object, are sufficient to describe some XML structures and constraints, but not others. 


OpenAPI does not currently support XML Schema. The OAI Technical Steering Committee is currently exploring alternate schema languages as a possible feature for a later release of the OpenAPI Specification.


Option 1: Adopt JSON Format for new REST Services

Clearly, one possibility is to drop XML support in your new REST-style APIs, and use JSON format. This allows you to use the full capabilities of OpenAPI schema objects (which are based on JSON Schema, but not exactly the same). It also makes your new services more idiomatic to modern REST API design. Compared to XML and XSD, JSON and JSON schema are somewhat simpler and less verbose. 


If an automated transformation from XML schema to JSON schema is available, it could useful in this scenario, but only as a starting point for your new JSON-based format.  Taking full advantage of JSON Schema will likely require further adjustments. 


Option 2: Model the XML Format with OpenAPI Schema Objects 

You may be able to describe your XML format, partially or completely, using OpenAPI Schema Objects with the optional XML Objects


Schema Objects specify essential structure and primitive property constraints. XML Objects annotate object properties with additional, XML-specific metadata.  They can specify:

  • an alternative name for the XML element or attribute, overriding the property name specified in the Schema Object. 
  • a namespace URI in which the element or attribute must be declared. 
  • a namespace prefix mapped to the specified namespace URI. 
  • the form of the property value, which may be an element or attribute.
  • for array values, an optional list container element to wrap multi-valued properties.


Taken together, the Schema Object and the additional metadata contributed by the XML object may be adequate to describe your XML format. 


But there are some constructs that cannot be modeled this way.  For example:

  • There is no way to represent mixed content
  • You cannot describe an XML element that has both a text value and one or more attributes. 
  • There are many advanced constructs in XML Schema, like type derivation, substitution groups, global elements, and others, that will not translate into Schema Objects. 

Consider limiting your use of XML to a form that can be described using OpenAPI Schema Objects with XML Objects. It might not be identical to, or even 100% compatible with your current XML Schemas.  But this might be a good compromise for you.


Option 3: Embed Documentation to Fully Describe the XML Format

You can rely on OpenAPI's "description" properties, which allow you to provide formatted, human-readable documentation, to explain how your XML format may deviate from what is defined in your OpenAPI specification.  


So if your OpenAPI spec includes Schema Objects that are only an approximation of your actual XML format, you can supplement with human-readable documentation, examples, and/or an external XML schema, to fully define your XML message format.