XML の表現

API仕様では、XMLとJSON形式の両方でデータを記述できます。これらは簡単に交換可能です。たとえば、以下の宣言は、

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

— JSONと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>

ご覧のとおり、XML表現では、オブジェクト名が親要素として機能し、プロパティは子要素に変換されます。OpenAPI 3形式では、XMLデータの表現を微調整するのに役立つ特別な xml オブジェクトを提供しています。このオブジェクトを使用して、一部のプロパティを要素ではなく属性に変換したり、要素名を変更したり、名前空間を追加したり、配列項目の変換を制御したりできます。

要素名の変更

デフォルトでは、XML要素はAPI宣言のフィールドと同じ名前を持ちます。デフォルトの動作を変更するには、スペックに xml/name フィールドを追加します。

要素名

仕様

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>

属性名

仕様

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>

配列の場合、xml/name プロパティは、別のプロパティである xml/wrapped が true に設定されている場合にのみ機能します。詳細については、以下を参照してください。

プロパティを属性に変換

前述のとおり、デフォルトでは、プロパティは親の「オブジェクト」要素の子要素に変換されます。結果のXMLデータでプロパティを属性にするには、xml/attribute を使用します。

仕様

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>

これはプロパティにのみ適用されます。xml/attribute をオブジェクトに使用しても意味がありません。

プレフィックスと名前空間

要素名の競合を避けるために、要素の名前空間とプレフィックスを指定できます。名前空間の値は絶対URIである必要があります。

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

名前空間プレフィックスはJSONでは無視されます

1
{ "author": "Mark Twain" }

以下の例は、名前空間とプレフィックスを追加する方法を示しています。

仕様

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>

必要に応じて、prefix のみを指定できます（名前空間が親要素で定義されている場合に機能します）。属性のプレフィックスも指定できます。

配列のラッピング

配列は同じ名前の要素のシーケンスとして変換されます。

仕様

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>

必要に応じて、xml/wrapped プロパティを使用してラッピング要素を追加できます。

仕様

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>

ご覧のとおり、デフォルトでは、ラッピング要素は項目要素と同じ名前を持ちます。xml/name を使用して、ラッピング要素と配列項目に異なる名前を付けます（これにより、発生する可能性のある名前付けの問題を解決できます）。

仕様

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>

ラッピング要素（この例では books）の xml.name プロパティは、wrapped が *true* の場合にのみ効果があることに注意してください。wrapped が *false* の場合、ラッピング要素の xml.name は無視されます。

参照

XMLオブジェクト

お探しのものが見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください