Representing 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 —

1
components:
2
  schemas:
3
    book:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        title:
9
          type: string
10
        author:
11
          type: string

— is represented in the following way in JSON and XML:

JSON

1
{ "id": 0, "title": "string", "author": "string" }

XML

1
<book>
2
  <id>0</id>
3
  <title>string</title>
4
  <author>string</author>
5
</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

1
components:
2
  schemas:
3
    book:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        title:
9
          type: string
10
        author:
11
          type: string
12
      xml:
13
        name: "xml-book"

XML

1
<xml-book>
2
  <id>0</id>
3
  <title>string</title>
4
  <author>string</author>
5
</xml-book>

Attribute name

Specification

1
components:
2
  schemas:
3
    book:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        title:
9
          type: string
10
          xml:
11
            name: "xml-title"
12
        author:
13
          type: string

XML

1
<book>
2
  <id>0</id>
3
  <xml-title>string</xml-title>
4
  <author>string</author>
5
</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

1
book:
2
  type: object
3
  properties:
4
    id:
5
      type: integer
6
      xml:
7
        attribute: true
8
    title:
9
      type: string
10
    author:
11
      type: string

XML

1
<book id="0">
2
  <title>string</title>
3
  <author>string</author>
4
</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:

1
xml:
2
  prefix: "smp"
3
  namespace: "http://example.com/schema"

Namespace prefixes will be ignored for JSON:

1
{ "author": "Mark Twain" }

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

Specification

1
book:
2
  type: object
3
  properties:
4
    id:
5
      type: integer
6
    title:
7
      type: string
8
    author:
9
      type: string
10
  xml:
11
    prefix: "smp"
12
    namespace: "http://example.com/schema"

XML

1
<smp:book xmlns:smp="http://example.com/schema">
2
  <id>0</id>
3
  <title>string</title>
4
  <author>string</author>
5
</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

1
books:
2
  type: array
3
  items:
4
    type: string
5
  example:
6
    - "one"
7
    - "two"
8
    - "three"

XML

1
<books>one</books>
2
<books>two</books>
3
<books>three</books>

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

Specification

1
books:
2
  type: array
3
  items:
4
    type: string
5
  xml:
6
    wrapped: true
7
  example:
8
    - "one"
9
    - "two"
10
    - "three"

XML

1
<books>
2
  <books>one</books>
3
  <books>two</books>
4
  <books>three</books>
5
</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

1
books:
2
  type: array
3
  items:
4
    type: string
5
    xml:
6
      name: "item"
7
  xml:
8
    wrapped: true
9
    name: books-array
10
  example:
11
    - "one"
12
    - "two"
13
    - "three"

XML

1
<books-array>
2
  <item>one</item>
3
  <item>two</item>
4
  <item>three</item>
5
</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

Did not find what you were looking for? Ask the community
Found a mistake? Let us know