跳到主要内容

Appendix B. HTTP 问题和 XML (HTTP Problems and XML)

使用 XML [XML] 的基于 HTTP 的 API 可以使用本附录定义的格式表示问题详情.

XML 格式的 RELAX NG schema [ISO-19757-2] 如下:

   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 })*

注意, 此 schema 仅用于文档说明, 并不是捕获 XML 格式所有约束的规范性 schema. 可以使用其他 XML schema 语言定义类似的一组约束, 具体取决于所选 schema 语言的特性.

此格式的媒体类型为 "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 schema 明确只允许来自 XML 格式所用单一命名空间的元素. 任何扩展数组和对象都必须 (MUST) 只使用该命名空间序列化为 XML 标记.

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

最后于 更新