Representating XML

In your API specification, you can describe data in both XML and JSON formats as they are easily interchangeable. For example, the following declaration

components:
  schemas:
    book:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        author: 
          type: string

is represented in the following way in JSON and XML:

JSON { "id": 0, "title": "string", "author": "string" }	XML <book> <id>0</id> <title>string</title> <author>string</author> </book>

As you can see, in XML representation, the object name serves as a parent element and properties are translated to child elements. The OpenAPI 3 format offers a special xml object to help you fine-tune representation of XML data. You can use this object to transform some properties to attributes rather than elements, to change element names, to add namespaces and to control transformations of array items.

Change Element Names

By default, XML elements get the same names that fields in the API declaration have. To change the default behavior, add the xml/name field to your spec:

Element name

Specification components: schemas: book: type: object properties: id: type: integer title: type: string author: type: string xml: name: 'xml-book'	XML <xml-book> <id>0</id> <title>string</title> <author>string</author> </xml-book>

Attribute name

Specification components: schemas: book: type: object properties: id: type: integer title: type: string xml: name: 'xml-title' author: type: string	XML <book> <id>0</id> <xml-title>string</xml-title> <author>string</author> </book>

For arrays, the xml/name property works only if another property – xml/wrapped – is set to true. See below.

Convert Property to an Attribute

As we said above, by default, properties are transformed to child elements of the parent “object” element. To make some property an attribute in the resulting XML data, use the xml/attribute:

Specification book: type: object properties: id: type: integer xml: attribute: true title: type: string author: type: string	XML <book id="0"> <title>string</title> <author>string</author> </book>

This works only for properties. Using xml/attribute for objects is meaningless.

Prefixes and Namespaces

To avoid element name conflicts, you can specify namespace and prefix for elements. The namespace value must be an absolute URI:

xml:
  prefix: 'smp'
  namespace: 'http://example.com/schema'

Namespace prefixes will be ignored for JSON:

{"author": "Mark Twain"}

The example below shows how you can add namespaces and prefixes:

Specification book: type: object properties: id: type: integer title: type: string author: type: string xml: prefix: 'smp' namespace: 'http://example.com/schema'	XML <smp:book xmlns:smp="http://example.com/schema"> <id>0</id> <title>string</title> <author>string</author> </smp:book>

If needed, you can specify only prefix (This works in case the namespace is defined in some parent element). You can also specify prefixes for attributes.

Wrapping Arrays

Arrays are translated as a sequence of elements of the same name:

Specification books: type: array items: type: string example: - 'one' - 'two' - 'three'	XML <books>one</books> <books>two</books> <books>three</books>

If needed, you can add a wrapping element by using the xml/wrapped property:

Specification books: type: array items: type: string xml: wrapped : true example: - 'one' - 'two' - 'three'	XML <books> <books>one</books> <books>two</books> <books>three</books> </books>

As you can see, by default, the wrapping element has the same name as item elements. Use xml/name to give different names to the wrapping element and array items (this will help you resolve possible naming issues):

Specification books: type: array items: type: string xml: name: 'item' xml: wrapped : true name: books-array example: - 'one' - 'two' - 'three'	XML <books-array> <item>one</item> <item>two</item> <item>three</item> </books-array>

Note that the xml.name property of the wrapping element (books in our example) has effect only if wrapped is true. If wrapped is false, xml.name of the wrapping element is ignored.

Reference

XML Object