Appendix B. HTTP Problems and XML (Problèmes HTTP et XML)

Certaines API HTTP utilisent XML [XML] comme format de contenu principal. Pour ces services, il peut être utile de sérialiser les détails de problème en utilisant un format XML compatible avec les contraintes d'autres messages échangés.

Le format XML canonique pour les détails de problème est un document XML qui identifie le type de média "application/problem+xml".

Sa racine de document est "problem", qui utilise l'espace de noms "urn:ietf:rfc:9457".

Par exemple, un problème HTTP sérialisé en JSON comme:

{
 "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"]
}

ressemblerait à ceci en XML:

<?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>

Notez que ce format utilise un élément générique "<i>" à la place des éléments nommés de tableau en JSON. Cela est dû aux contraintes inhérentes à XML, où les noms d'éléments doivent être des noms XML valides -- ce qui exclut les caractères tels que les espaces, la plupart des ponctuations et les chiffres au début du nom.

Ce format XML pour les détails de problème suit les conventions du schéma XML [ISO-19757-2] non normatif présenté ici. Cette section présente également les mappages entre noms de membres JSON et noms d'éléments XML ainsi que quelques considérations supplémentaires.

Voici le schéma non normatif RELAX NG [ISO-19757-2]:

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

Notez que l'ordre des éléments dans les détails de problème est explicitement non spécifié. Bien que XML soit utilisé dans certaines situations pour véhiculer un ordre de processus (par exemple, XSLT [XSLT]), cela n'est généralement pas le cas pour un objet de détails de problème, car tous les membres de l'objet sont facultatifs et peuvent être traités dans n'importe quel ordre.

Les détails de problème peuvent contenir des membres d'extension qui ne peuvent pas être mappés sur XML. Lors de la sérialisation, de tels membres peuvent ne pas apparaître dans le document XML ou peuvent être ignorés lors de la désérialisation. Comme indiqué dans la section 3.2, les clients DOIVENT ignorer toutes les extensions qu'ils ne reconnaissent pas.

Lorsqu'un objet de détails de problème contient des membres dont les valeurs JSON ne peuvent pas être directement représentées en XML (par exemple, un objet JSON), il sera nécessaire de définir des mappages spécifiques pour ces valeurs vers un format XML.