Skip to content

Guide

Default encoding of scalars

As in Json we have some default handling of the common scalars like utcDateTime

Scalar TypeDefault EncodingEncoding name
utcDateTimexs:dateTimeTypeSpec.Xml.Encoding.xmlDateTime
offsetDateTimexs:dateTimeTypeSpec.Xml.Encoding.xmlDateTime
plainDatexs:dateTypeSpec.Xml.Encoding.xmlDate
plainTimexs:timeTypeSpec.Xml.Encoding.xmlTime
durationxs:durationTypeSpec.Xml.Encoding.xmlDuration
bytesxs:base64BinaryTypeSpec.Xml.Encoding.xmlBase64Binary

Examples

1. Array of primitive types

TypeSpec Xml OpenAPI3
@encodedName("application/xml", "XmlPet")
model Pet {
@xml.unwrapped
tags: string[];
}
<XmlPet>
<tags>abc</tags>
<tags>def</tags>
</XmlPet>
Pet:
type: "object"
properties:
tags:
type: "array"
items:
type: string
xml:
name: "XmlPet"
@encodedName("application/xml", "XmlPet")
model Pet {
@encodedName("application/xml", "ItemsTags")
tags: string[];
}
<XmlPet>
<ItemsTags>
<string>abc</string>
<string>def</string>
</ItemsTags>
</XmlPet>
Pet:
type: "object"
properties:
tags:
type: "array"
xml:
name: "ItemsTags"
wrapped: true
items:
type: string
xml:
name: "XmlPet"
@encodedName("application/xml", "ItemsName")
scalar tag extends string;
@encodedName("application/xml", "XmlPet")
model Pet {
@xml.unwrapped
tags: tag[];
}
<XmlPet>
<ItemsName>abc</ItemsName>
<ItemsName>def</ItemsName>
</XmlPet>
Pet:
type: "object"
properties:
tags:
type: "array"
xml:
name: "ItemsTags"
items:
type: string
xml:
name: ItemsName
xml:
name: "XmlPet"
@encodedName("application/xml", "ItemsName")
scalar tag extends string;
@encodedName("application/xml", "XmlPet")
model Pet {
@encodedName("application/xml", "ItemsTags")
tags: tag[];
}
<XmlPet>
<ItemsTags>
<ItemsName>abc</ItemsName>
<ItemsName>def</ItemsName>
</ItemsTags>
</XmlPet>
Pet:
type: "object"
properties:
tags:
type: "array"
xml:
name: "ItemsTags"
wrapped: true
items:
type: string
xml:
name: ItemsName
xml:
name: "XmlPet"

2. Complex array types

TypeSpec Xml OpenAPI3
@encodedName("application/xml", "XmlPet")
model Pet {
@xml.unwrapped
tags: Tag[];
}
@encodedName("application/xml", "XmlTag")
model Tag {
name: string;
}
<XmlPet>
<XmlTag>
<name>string</name>
</XmlTag>
</XmlPet>
Tag:
type: "object"
properties:
name:
type: "string"
xml:
name: "XmlTag"
Pet:
type: "object"
properties:
tags:
type: "array"
items:
$ref: "#/definitions/Tag"
xml:
name: "XmlPet"
@encodedName("application/xml", "XmlPet")
model Pet {
tags: Tag[];
}
@encodedName("application/xml", "XmlTag")
model Tag {
name: string;
}
<XmlPet>
<ItemsTags>
<XmlTag>
<name>string</name>
</XmlTag>
</ItemsTags>
</XmlPet>
Tag:
type: "object"
properties:
name:
type: "string"
xml:
name: "XmlTag"
Pet:
type: "object"
properties:
tags:
type: "array"
xml:
name: "ItemsTags"
wrapped: true
items:
$ref: "#/definitions/Tag"
xml:
name: "XmlPet"
@encodedName("application/xml", "XmlPet")
model Pet {
@encodedName("application/xml", "ItemsTags")
@xml.unwrapped
tags: Tag[];
}
@encodedName("application/xml", "XmlTag")
model Tag {
name: string;
}
<XmlPet>
<ItemsTag>
<name>string</name>
</ItemsTag>
</XmlPet>
Tag:
type: "object"
properties:
name:
type: "string"
xml:
name: "XmlTag"
Pet:
type: "object"
properties:
tags:
type: "array"
xml:
name: "ItemsTags"
items:
$ref: "#/definitions/Tag"
xml:
name: ItemsXMLName
xml:
name: "XmlPet"
@encodedName("application/xml", "XmlPet")
model Pet {
@encodedName("application/xml", "ItemsTags")
tags: Tag[];
}
@encodedName("application/xml", "XmlTag")
model Tag {
name: string;
}
<XmlPet>
<ItemsTags>
<XmlTag>
<name>string</name>
</XmlTag>
</ItemsTags>
</XmlPet>
Tag:
type: "object"
properties:
name:
type: "string"
Pet:
type: "object"
properties:
tags:
type: "array"
xml:
name: "ItemsTags"
wrapped: true
items:
$ref: "#/definitions/Tag"
xml:
name: "XmlPet"

3. Nested models

TypeSpec Xml OpenAPI3
model Book {
author: Author;
}
model Author {
name: string;
}
<Book>
<author>
<name>string</name>
</author>
</Book>
Book:
type: object
properties:
author:
$ref: "#/components/schemas/Author"
Author:
type: object
properties:
name:
type: string
model Book {
author: Author;
}
@encodedName("application/xml", "XmlAuthor")
model Author {
name: string;
}
<Book>
<author>
<name>string</name>
</author>
</Book>
Book:
type: object
properties:
author:
allOf:
- $ref: "#/components/schemas/Author"
xml:
name: "author" # Here we have to redefine this name otherwise in OpenAPI semantic the `XmlAuthor` name would be used
Author:
type: object
properties:
name:
type: string
xml:
name: "XmlAuthor"
model Book {
@encodedName("application/xml", "xml-author")
author: Author;
}
model Author {
name: string;
}
<Book>
<xml-author>
<name>string</name>
</xml-author>
</Book>
Book:
type: object
properties:
author:
allOf:
- $ref: "#/components/schemas/Author"
xml:
name: "xml-author"
Author:
type: object
properties:
name:
type: string

4. Attributes

TypeSpec Xml OpenAPI3
model Book {
@Xml.attribute
id: string;
title: string;
author: string;
}
<Book id="0">
<xml-title>string</xml-title>
<author>string</author>
</Book>
Book:
type: object
properties:
id:
type: integer
title:
type: string
xml:
name: "xml-title"
author:
type: string

5. Namespace and prefix (inline form)

TypeSpec Xml OpenAPI3
@Xml.ns("smp", "http://example.com/schema")
model Book {
id: string;
title: string;
author: string;
}
<smp:Book xmlns:smp="http://example.com/schema">
<id>0</id>
<title>string</title>
<author>string</author>
</smp:Book>
Book:
type: object
properties:
id:
type: integer
title:
type: string
author:
type: string
xml:
prefix: "smp"
namespace: "http://example.com/schema"
@Xml.ns("smp", "http://example.com/schema")
model Book {
id: string;
@Xml.ns("smp", "http://example.com/schema")
title: string;
@Xml.ns("ns2", "http://example.com/ns2")
author: string;
}
<smp:Book xmlns:smp="http://example.com/schema" xmlns:sn2="http://example.com/ns2">
<id>0</id>
<smp:title>string</smp:title>
<ns2:author>string</ns2:author>
</smp:Book>
Book:
type: object
properties:
id:
type: integer
title:
type: string
xml:
prefix: "smp"
namespace: "http://example.com/schema"
author:
type: string
xml:
prefix: "ns2"
namespace: "http://example.com/ns2"
xml:
prefix: "smp"
namespace: "http://example.com/schema"

6. Namespace and prefix (normalized form)

TypeSpec Xml OpenAPI3
@Xml.nsDeclarations
enum Namespaces {
smp: "http://example.com/schema",
}
@Xml.ns(Namespaces.smp)
model Book {
id: string;
title: string;
author: string;
}
<smp:Book xmlns:smp="http://example.com/schema">
<id>0</id>
<title>string</title>
<author>string</author>
</smp:Book>
Book:
type: object
properties:
id:
type: integer
title:
type: string
author:
type: string
xml:
prefix: "smp"
namespace: "http://example.com/schema"
@Xml.nsDeclarations
enum Namespaces {
smp: "http://example.com/schema",
ns2: "http://example.com/ns2",
}
@Xml.ns(Namespaces.smp)
model Book {
id: string;
@Xml.ns(Namespaces.smp)
title: string;
@Xml.ns(Namespaces.ns2)
author: string;
}
<smp:Book xmlns:smp="http://example.com/schema" xmlns:sn2="http://example.com/ns2">
<id>0</id>
<smp:title>string</smp:title>
<ns2:author>string</ns2:author>
</smp:Book>
Book:
type: object
properties:
id:
type: integer
title:
type: string
xml:
prefix: "smp"
namespace: "http://example.com/schema"
author:
type: string
xml:
prefix: "ns2"
namespace: "http://example.com/ns2"
xml:
prefix: "smp"
namespace: "http://example.com/schema"

6. Property setting the text of the node

TypeSpec Xml OpenAPI3
model BlobName {
@Xml.attribute language: string;
@Xml.unwrapped content: string;
}
<BlobName language="abc">
...content...
</smp:Book>
Book:
type: object
properties:
language:
type: string
content:
type: string
xml:
x-ms-text: true # on autorest emitter