Skip to content

Guide

Default encoding of scalars

Section titled “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

Section titled “Examples”

1. Array of primitive types

Section titled “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

Section titled “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

Section titled “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

Section titled “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)

Section titled “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)

Section titled “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

Section titled “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