Zum Hauptinhalt springen

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

Einige HTTP-APIs verwenden XML [XML] als primäres Inhaltsformat. Für diese Dienste kann es nützlich sein, Problem Details unter Verwendung eines XML-Formats zu serialisieren, das mit den Einschränkungen anderer ausgetauschter Nachrichten kompatibel ist.

Das kanonische XML-Format für Problem Details ist ein XML-Dokument, das den Medientyp "application/problem+xml" identifiziert.

Sein Dokument-Root ist "problem", das den Namespace "urn:ietf:rfc:9457" verwendet.

Beispielsweise würde ein HTTP-Problem, das in JSON serialisiert ist als:

{
 "type": "https://example.com/probs/out-of-credit",
 "title": "You do not have enough credit.",
 "detail": "Your current balance is 30, but that costs 50.",
 "instance": "/account/12345/msgs/abc",
 "balance": 30,
 "accounts": ["/account/12345",
              "/account/67890"]
}

in XML so aussehen:

<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:9457">
  <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>/account/12345/msgs/abc</instance>
  <balance>30</balance>
  <accounts>
    <i>/account/12345</i>
    <i>/account/67890</i>
  </accounts>
</problem>

Beachten Sie, dass dieses Format ein generisches "<i>"-Element anstelle von benannten Array-Elementen in JSON verwendet. Dies liegt an den inhärenten Einschränkungen von XML, bei denen Elementnamen gültige XML-Namen sein müssen -- was Zeichen wie Leerzeichen, die meisten Satzzeichen und Ziffern am Anfang des Namens ausschließt.

Dieses XML-Format für Problem Details folgt den Konventionen des nicht-normativen XML-Schemas [ISO-19757-2], das hier präsentiert wird. Dieser Abschnitt präsentiert auch Zuordnungen zwischen JSON-Mitgliedsnamen und XML-Elementnamen sowie einige zusätzliche Überlegungen.

Hier ist das nicht-normative RELAX NG [ISO-19757-2]-Schema:

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

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

Beachten Sie, dass die Reihenfolge der Elemente in Problem Details ausdrücklich nicht spezifiziert ist. Obwohl XML in einigen Situationen verwendet wird, um eine Verarbeitungsreihenfolge zu übermitteln (z.B. XSLT [XSLT]), ist dies im Allgemeinen nicht der Fall für ein Problem Details-Objekt, da alle Mitglieder des Objekts optional sind und in beliebiger Reihenfolge verarbeitet werden können.

Problem Details können Erweiterungsmitglieder enthalten, die nicht auf XML abgebildet werden können. Beim Serialisieren erscheinen solche Mitglieder möglicherweise nicht im XML-Dokument oder werden beim Deserialisieren ignoriert. Wie in Abschnitt 3.2 angegeben, MÜSSEN Clients alle Erweiterungen ignorieren, die sie nicht erkennen.

Wenn ein Problem Details-Objekt Mitglieder enthält, deren JSON-Werte nicht direkt in XML dargestellt werden können (z.B. ein JSON-Objekt), wird es notwendig sein, spezifische Zuordnungen für diese Werte zu einem XML-Format zu definieren.

Letztes Update am