XML 对象

一个为 XML 模型定义微调过的元数据对象。

当使用数组时，不会推测 XML 元素的名称（单数或复数形式），所以应该添加 name 属性来提供此信息。 查看展示此期望的示例。

固定字段

字段名	类型	描述
name	string	替换用于描述元素/属性的结构特性的名称。当在 items 内定义时将会影响处于此列表中的每个元素的名称。当定义于 items 之上时将会影响它说包裹的元素且仅当 wrapped 是 true 时，如果 wrapped 是 false 时它将会被忽略。
namespace	string	命名空间定义的 URI。其值必须是绝对 URI。
prefix	string	用于 name 的前缀。
attribute	boolean	声明此特性定义会被转换为一个属性而不是一个元素。默认值是 false。
wrapped	boolean	只可被用于数组定义。表示数组是否被包裹（比如, <books><book/><book/></books>）或未被包裹（<book/><book/>）。默认值是 false。此定义只在 type 为 array（位于 items 之上） 时生效。

这个对象可能会被规范扩展扩展。

XML 对象示例

XML 对象定义的示例被包括在一个 Schema 对象 的特性定义并带有一个样例 XML 来呈现它。

无 XML 元素

基础字符串属性：

{
  "animals": {
    "type": "string"
  }
}

animals:
  type: string

<animals>...</animals>

基础字符串数组属性 (wrapped 默认是 false)：

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

animals:
  type: array
  items:
    type: string

<animals>
  <animal>...</animal>
  <animal>...</animal>
  <animal>...</animal>
</animals>

XML 名称替换

{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}

animals:
  type: string
  xml:
    name: animal

<animal>...</animal>

XML 属性，前缀和命名空间

在此示例中展示了一个完整的模型定义。

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "http://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: http://example.com/schema/sample
        prefix: sample

<Person id="123">
  <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name>
</Person>

XML 数组

改变元素的名称：

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal

<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

外部的 name 属性在 XML 上不产生效果：

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens"
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens

<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

尽管数组是被包裹的，如果没有明确定义一个名称，那么同样地名称会被用于内部和外部：

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    wrapped: true

<animals>
  <animals>value</animals>
  <animals>value</animals>
</animals>

为了解决上面示例的命名问题，可以使用下面的定义：

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    wrapped: true

<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

Affecting both internal and external names:

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
    wrapped: true

<aliens>
  <animal>value</animal>
  <animal>value</animal>
</aliens>

如果我们改变外部的元素而保持内部的不变：

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    name: aliens
    wrapped: true

<aliens>
  <aliens>value</aliens>
  <aliens>value</aliens>
</aliens>