跳到主要内容

Appendix A. HTTP 问题与 XML

一些基于 HTTP 的 API 使用 XML [W3C.REC-xml-20081126] 作为其主要格式约定. 此类 API 可以使用本附录定义的格式表达问题详情.

XML 格式的 RELAX NG 模式 [ISO-19757-2] 如下. 请记住, 该模式仅作为文档说明, 而不是捕获 XML 格式所有约束的规范性模式. 此外, 也可以使用其他 XML 模式语言来定义类似约束集合 (取决于所选模式语言的特性).

default namespace ns = "urn:ietf:rfc:7807"

start = problem

problem =
  element problem {
    (  element  type            { xsd:anyURI }?
     & element  title           { xsd:string }?
     & element  detail          { xsd:string }?
     & element  status          { xsd:positiveInteger }?
     & element  instance        { xsd:anyURI }? ),
    anyNsElement
  }

anyNsElement =
  (  element    ns:*  { anyNsElement | text }
   | attribute  *     { text })*

该格式的媒体类型为 "application/problem+xml".

扩展数组和对象序列化到 XML 格式时, 包含子元素的元素被视为表示对象; 但如果某个元素只包含名为 'i' 的子元素, 则将其视为数组. 例如, 上面的示例在 XML 中表示如下:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+xml
Content-Language: en

<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:7807">
  <type>https://example.com/probs/out-of-credit</type>
  <title>You do not have enough credit.</title>
  &lt;detail>Your current balance is 30, but that costs 50.&lt;/detail>
  &lt;instance>https://example.net/account/12345/msgs/abc&lt;/instance>
  &lt;balance>30&lt;/balance>
  &lt;accounts>
    <i>https://example.net/account/12345</i>
    <i>https://example.net/account/67890</i>
  &lt;/accounts>
&lt;/problem>

注意, 该格式使用 XML 命名空间. 这主要是为了允许将其嵌入其他基于 XML 的格式; 这并不意味着可以或应当使用其他命名空间中的元素或属性来扩展它. RELAX NG 模式明确只允许 XML 格式所用单一命名空间中的元素. 任何扩展数组和对象都必须仅使用该命名空间序列化为 XML 标记.

使用 XML 格式时, 可以在 XML 中嵌入 XML 处理指令, 指示客户端使用引用的 XSLT 代码 [W3C.REC-xml-stylesheet-20101028] 转换 XML. 如果该代码将 XML 转换为 (X)HTML, 则可以提供 XML 格式, 同时让具备执行转换能力的客户端显示人类友好的 (X)HTML, 并在客户端渲染和展示. 注意, 使用此方法时, 建议使用 XSLT 1.0, 以最大化能够执行该 XSLT 代码的客户端数量.

最后于 更新