Skip to main content

Appendix A. HTTP Problems and XML (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>
  <detail>Your current balance is 30, but that costs 50.</detail>
  <instance>https://example.net/account/12345/msgs/abc</instance>
  <balance>30</balance>
  <accounts>
    <i>https://example.net/account/12345</i>
    <i>https://example.net/account/67890</i>
  </accounts>
</problem>

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

使用 XML 格式时,可以在 XML 中嵌入 XML 处理指令,指示客户端使用引用的 XSLT 代码转换 XML [W3C.REC-xml-stylesheet-20101028]。如果此代码将 XML 转换为 (X)HTML,则可以提供 XML 格式,但能够执行转换的客户端会显示在客户端呈现和显示的人性化 (X)HTML。请注意,使用此方法时,建议使用 XSLT 1.0 以最大化能够执行 XSLT 代码的客户端数量。

Last updated on