Appendix A. HTTP Problems and XML (HTTP-Probleme und XML)

Einige HTTP-basierte APIs verwenden XML [W3C.REC-xml-20081126] als ihre primäre Formatkonvention. Solche APIs können Problemdetails im in diesem Anhang definierten Format ausdrücken.

Das RELAX NG-Schema [ISO-19757-2] für das XML-Format lautet wie folgt. Beachten Sie, dass dieses Schema nur zur Dokumentation gedacht ist und nicht als normatives Schema, das alle Einschränkungen des XML-Formats erfasst. Es wäre auch möglich, andere XML-Schema-Sprachen zu verwenden, um einen ähnlichen Satz von Einschränkungen zu definieren (abhängig von den Funktionen der gewählten Schema-Sprache).

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

Der Medientyp für dieses Format ist application/problem+xml.

Erweiterungs-Arrays und -Objekte werden in das XML-Format serialisiert, indem ein Element mit einem oder mehreren untergeordneten Elementen als Objekt betrachtet wird, mit Ausnahme von Elementen, die nur untergeordnete Elemente mit dem Namen i enthalten, die als Arrays betrachtet werden. Zum Beispiel erscheint das obige Beispiel in XML wie folgt:

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>

Beachten Sie, dass dieses Format einen XML-Namensraum verwendet. Dies dient in erster Linie dazu, es in andere XML-basierte Formate einzubetten; es impliziert nicht, dass es mit Elementen oder Attributen in anderen Namensräumen erweitert werden kann oder sollte. Das RELAX NG-Schema erlaubt ausdrücklich nur Elemente aus dem einen im XML-Format verwendeten Namensraum. Alle Erweiterungs-Arrays und -Objekte MÜSSEN (MUST) nur mit diesem Namensraum in XML-Markup serialisiert werden.

Bei Verwendung des XML-Formats ist es möglich, eine XML-Verarbeitungsanweisung in das XML einzubetten, die Clients anweist, das XML unter Verwendung des referenzierten XSLT-Codes [W3C.REC-xml-stylesheet-20101028] zu transformieren. Wenn dieser Code das XML in (X)HTML transformiert, ist es möglich, das XML-Format bereitzustellen, und dennoch können Clients, die in der Lage sind, die Transformation durchzuführen, benutzerfreundliches (X)HTML anzeigen, das auf dem Client gerendert und angezeigt wird. Beachten Sie, dass es bei Verwendung dieser Methode ratsam ist, XSLT 1.0 zu verwenden, um die Anzahl der Clients zu maximieren, die in der Lage sind, den XSLT-Code auszuführen.