OAS 3 This guide is for OpenAPI 3.0.
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 —
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
Did not find what you were looking for? Ask the community
Found a mistake? Let us know