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: tags
  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: 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"
      items:
        type: string
        xml:
          name: tags
  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:
        allOf:
          - $ref: "#/definitions/Tag"
        xml:
          name: tags
  xml:
    name: "XmlPet"
 
@encodedName("application/xml", "XmlPet")
model Pet {
  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:
        allOf:
          - $ref: "#/components/schemas/Tag"
        xml:
          name: XmlTag
      xml:
        wrapped: true
  xml:
    name: XmlPet
 
@encodedName("application/xml", "XmlPet")
model Pet {
  @encodedName("application/xml", "ItemsTag")
  @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"
      items:
        allOf:
          - $ref: "#/definitions/Tag"
        xml:
          name: ItemsTag
  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"
  xml:
    name: "XmlTag"
Pet:
  type: "object"
  properties:
    tags:
      type: "array"
      xml:
        name: "ItemsTags"
        wrapped: true
      items:
        allOf:
          - $ref: "#/definitions/Tag"
        xml:
          name: XmlTag
  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: integer;


  @Xml.name("xml-title")
  title: string;


  author: string;
}
 
<Book id="0">
  <xml-title>string</xml-title>
  <author>string</author>
</Book>
 
Book:
  type: object
  properties:
    id:
      type: integer
      xml:
        attribute: true
    title:
      type: string
      xml:
        name: "xml-title"
    author:
      type: string

5. Namespace and prefix (inline form)

TypeSpec Xml OpenAPI3 
@Xml.ns("http://example.com/schema", "smp")
model Book {
  id: integer;
  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("http://example.com/schema", "smp")
model Book {
  id: integer;


  @Xml.ns("http://example.com/schema", "smp")
  title: string;


  @Xml.ns("http://example.com/ns2", "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: integer;
  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"
Namespaces:
  type: string
  enum:
    - 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: integer;


  @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"
Namespaces:
  type: string
  enum:
    - http://example.com/schema
    - http://example.com/ns2

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
      xml:
        attribute: true
    content:
      type: string