idnits 2.17.1 draft-ietf-httpapi-rfc7807bis-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC7807, but the abstract doesn't seem to directly say this. It does mention RFC7807 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 593 has weird spacing: '...element type ...' == Line 594 has weird spacing: '...element title...' == Line 595 has weird spacing: '...element detai...' == Line 596 has weird spacing: '...element statu...' == Line 597 has weird spacing: '...element insta...' == (1 more instance...) -- The document date (14 April 2021) is 1102 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft 4 Obsoletes: 7807 (if approved) E. Wilde 5 Intended status: Standards Track 6 Expires: 16 October 2021 S. Dalal 7 14 April 2021 9 Problem Details for HTTP APIs 10 draft-ietf-httpapi-rfc7807bis-00 12 Abstract 14 This document defines a "problem detail" as a way to carry machine- 15 readable details of errors in a HTTP response to avoid the need to 16 define new error response formats for HTTP APIs. 18 Discussion Venues 20 This note is to be removed before publishing as an RFC. 22 Source for this draft and an issue tracker can be found at 23 https://github.com/ietf-wg-httpapi/rfc7807bis. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 16 October 2021. 42 Copyright Notice 44 Copyright (c) 2021 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. Code Components 52 extracted from this document must include Simplified BSD License text 53 as described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4 61 3.1. Members of a Problem Details Object . . . . . . . . . . . 5 62 3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6 63 4. Defining New Problem Types . . . . . . . . . . . . . . . . . 7 64 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 4.2. Predefined Problem Types . . . . . . . . . . . . . . . . 8 66 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 68 6.1. application/problem+json . . . . . . . . . . . . . . . . 9 69 6.2. application/problem+xml . . . . . . . . . . . . . . . . . 10 70 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 72 7.2. Informative References . . . . . . . . . . . . . . . . . 12 73 Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 13 74 Appendix B. Using Problem Details with Other Formats . . . . . . 15 75 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 78 1. Introduction 80 HTTP [RFC7230] status codes are sometimes not sufficient to convey 81 enough information about an error to be helpful. While humans behind 82 Web browsers can be informed about the nature of the problem with an 83 HTML [HTML5] response body, non-human consumers of so-called "HTTP 84 APIs" are usually not. 86 This specification defines simple JSON [RFC7159] and XML [XML] 87 document formats to suit this purpose. They are designed to be 88 reused by HTTP APIs, which can identify distinct "problem types" 89 specific to their needs. 91 Thus, API clients can be informed of both the high-level error class 92 (using the status code) and the finer-grained details of the problem 93 (using one of these formats). 95 For example, consider a response that indicates that the client's 96 account doesn't have enough credit. The 403 Forbidden status code 97 might be deemed most appropriate to use, as it will inform HTTP- 98 generic software (such as client libraries, caches, and proxies) of 99 the general semantics of the response. 101 However, that doesn't give the API client enough information about 102 why the request was forbidden, the applicable account balance, or how 103 to correct the problem. If these details are included in the 104 response body in a machine-readable format, the client can treat it 105 appropriately; for example, triggering a transfer of more credit into 106 the account. 108 This specification does this by identifying a specific type of 109 problem (e.g., "out of credit") with a URI [RFC3986]; HTTP APIs can 110 do this by nominating new URIs under their control, or by reusing 111 existing ones. 113 Additionally, problem details can contain other information, such as 114 a URI that identifies the specific occurrence of the problem 115 (effectively giving an identifier to the concept "The time Joe didn't 116 have enough credit last Thursday"), which can be useful for support 117 or forensic purposes. 119 The data model for problem details is a JSON [RFC7159] object; when 120 formatted as a JSON document, it uses the "application/problem+json" 121 media type. Appendix A defines how to express them in an equivalent 122 XML format, which uses the "application/problem+xml" media type. 124 Note that problem details are (naturally) not the only way to convey 125 the details of a problem in HTTP; if the response is still a 126 representation of a resource, for example, it's often preferable to 127 accommodate describing the relevant details in that application's 128 format. Likewise, in many situations, there is an appropriate HTTP 129 status code that does not require extra detail to be conveyed. 131 Instead, the aim of this specification is to define common error 132 formats for those applications that need one, so that they aren't 133 required to define their own, or worse, tempted to redefine the 134 semantics of existing HTTP status codes. Even if an application 135 chooses not to use it to convey errors, reviewing its design can help 136 guide the design decisions faced when conveying errors in an existing 137 format. 139 2. Requirements 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 document are to be interpreted as described in [RFC2119]. 145 3. The Problem Details JSON Object 147 The canonical model for problem details is a JSON [RFC7159] object. 149 When serialized as a JSON document, that format is identified with 150 the "application/problem+json" media type. 152 For example, an HTTP response carrying JSON problem details: 154 HTTP/1.1 403 Forbidden 155 Content-Type: application/problem+json 156 Content-Language: en 158 { 159 "type": "https://example.com/probs/out-of-credit", 160 "title": "You do not have enough credit.", 161 "detail": "Your current balance is 30, but that costs 50.", 162 "instance": "/account/12345/msgs/abc", 163 "balance": 30, 164 "accounts": ["/account/12345", 165 "/account/67890"] 166 } 168 Here, the out-of-credit problem (identified by its type URI) 169 indicates the reason for the 403 in "title", gives a reference for 170 the specific problem occurrence with "instance", gives occurrence- 171 specific details in "detail", and adds two extensions; "balance" 172 conveys the account's balance, and "accounts" gives links where the 173 account can be topped up. 175 The ability to convey problem-specific extensions allows more than 176 one problem to be conveyed. For example: 178 HTTP/1.1 400 Bad Request 179 Content-Type: application/problem+json 180 Content-Language: en 182 { 183 "type": "https://example.net/validation-error", 184 "title": "Your request parameters didn't validate.", 185 "invalid-params": [ { 186 "name": "age", 187 "reason": "must be a positive integer" 188 }, 189 { 190 "name": "color", 191 "reason": "must be 'green', 'red' or 'blue'"} 192 ] 193 } 195 Note that this requires each of the subproblems to be similar enough 196 to use the same HTTP status code. If they do not, the 207 (Multi- 197 Status) [RFC4918] code could be used to encapsulate multiple status 198 messages. 200 3.1. Members of a Problem Details Object 202 A problem details object can have the following members: 204 * "type" (string) - A URI reference [RFC3986] that identifies the 205 problem type. This specification encourages that, when 206 dereferenced, it provide human-readable documentation for the 207 problem type (e.g., using HTML [HTML5]). When this member is not 208 present, its value is assumed to be "about:blank". 210 * "title" (string) - A short, human-readable summary of the problem 211 type. It SHOULD NOT change from occurrence to occurrence of the 212 problem, except for purposes of localization (e.g., using 213 proactive content negotiation; see [RFC7231], Section 3.4). 215 * "status" (number) - The HTTP status code ([RFC7231], Section 6) 216 generated by the origin server for this occurrence of the problem. 218 * "detail" (string) - A human-readable explanation specific to this 219 occurrence of the problem. 221 * "instance" (string) - A URI reference that identifies the specific 222 occurrence of the problem. It may or may not yield further 223 information if dereferenced. 225 Consumers MUST use the "type" string as the primary identifier for 226 the problem type; the "title" string is advisory and included only 227 for users who are not aware of the semantics of the URI and do not 228 have the ability to discover them (e.g., offline log analysis). 229 Consumers SHOULD NOT automatically dereference the type URI. 231 The "status" member, if present, is only advisory; it conveys the 232 HTTP status code used for the convenience of the consumer. 233 Generators MUST use the same status code in the actual HTTP response, 234 to assure that generic HTTP software that does not understand this 235 format still behaves correctly. See Section 5 for further caveats 236 regarding its use. 238 Consumers can use the status member to determine what the original 239 status code used by the generator was, in cases where it has been 240 changed (e.g., by an intermediary or cache), and when message bodies 241 persist without HTTP information. Generic HTTP software will still 242 use the HTTP status code. 244 The "detail" member, if present, ought to focus on helping the client 245 correct the problem, rather than giving debugging information. 247 Consumers SHOULD NOT parse the "detail" member for information; 248 extensions are more suitable and less error-prone ways to obtain such 249 information. 251 Note that both "type" and "instance" accept relative URIs; this means 252 that they must be resolved relative to the document's base URI, as 253 per [RFC3986], Section 5. 255 3.2. Extension Members 257 Problem type definitions MAY extend the problem details object with 258 additional members. 260 For example, our "out of credit" problem above defines two such 261 extensions -- "balance" and "accounts" to convey additional, problem- 262 specific information. 264 Clients consuming problem details MUST ignore any such extensions 265 that they don't recognize; this allows problem types to evolve and 266 include additional information in the future. 268 Note that because extensions are effectively put into a namespace by 269 the problem type, it is not possible to define new "standard" members 270 without defining a new media type. 272 4. Defining New Problem Types 274 When an HTTP API needs to define a response that indicates an error 275 condition, it might be appropriate to do so by defining a new problem 276 type. 278 Before doing so, it's important to understand what they are good for, 279 and what's better left to other mechanisms. 281 Problem details are not a debugging tool for the underlying 282 implementation; rather, they are a way to expose greater detail about 283 the HTTP interface itself. Designers of new problem types need to 284 carefully consider the Security Considerations (Section 5), in 285 particular, the risk of exposing attack vectors by exposing 286 implementation internals through error messages. 288 Likewise, truly generic problems -- i.e., conditions that could 289 potentially apply to any resource on the Web -- are usually better 290 expressed as plain status codes. For example, a "write access 291 disallowed" problem is probably unnecessary, since a 403 Forbidden 292 status code in response to a PUT request is self-explanatory. 294 Finally, an application might have a more appropriate way to carry an 295 error in a format that it already defines. Problem details are 296 intended to avoid the necessity of establishing new "fault" or 297 "error" document formats, not to replace existing domain-specific 298 formats. 300 That said, it is possible to add support for problem details to 301 existing HTTP APIs using HTTP content negotiation (e.g., using the 302 Accept request header to indicate a preference for this format; see 303 [RFC7231], Section 5.3.2). 305 New problem type definitions MUST document: 307 1. a type URI (typically, with the "http" or "https" scheme), 309 2. a title that appropriately describes it (think short), and 311 3. the HTTP status code for it to be used with. 313 Problem type definitions MAY specify the use of the Retry-After 314 response header ([RFC7231], Section 7.1.3) in appropriate 315 circumstances. 317 A problem's type URI SHOULD resolve to HTML [HTML5] documentation 318 that explains how to resolve the problem. 320 A problem type definition MAY specify additional members on the 321 problem details object. For example, an extension might use typed 322 links [RFC5988] to another resource that can be used by machines to 323 resolve the problem. 325 If such additional members are defined, their names SHOULD start with 326 a letter (ALPHA, as per [RFC5234], Appendix B.1) and SHOULD consist 327 of characters from ALPHA, DIGIT ([RFC5234], Appendix B.1), and "_" 328 (so that it can be serialized in formats other than JSON), and they 329 SHOULD be three characters or longer. 331 4.1. Example 333 For example, if you are publishing an HTTP API to your online 334 shopping cart, you might need to indicate that the user is out of 335 credit (our example from above), and therefore cannot make the 336 purchase. 338 If you already have an application-specific format that can 339 accommodate this information, it's probably best to do that. 340 However, if you don't, you might consider using one of the problem 341 details formats -- JSON if your API is JSON-based, or XML if it uses 342 that format. 344 To do so, you might look for an already-defined type URI that suits 345 your purposes. If one is available, you can reuse that URI. 347 If one isn't available, you could mint and document a new type URI 348 (which ought to be under your control and stable over time), an 349 appropriate title and the HTTP status code that it will be used with, 350 along with what it means and how it should be handled. 352 In summary: an instance URI will always identify a specific 353 occurrence of a problem. On the other hand, type URIs can be reused 354 if an appropriate description of a problem type is already available 355 someplace else, or they can be created for new problem types. 357 4.2. Predefined Problem Types 359 This specification reserves the use of one URI as a problem type: 361 The "about:blank" URI [RFC6694], when used as a problem type, 362 indicates that the problem has no additional semantics beyond that of 363 the HTTP status code. 365 When "about:blank" is used, the title SHOULD be the same as the 366 recommended HTTP status phrase for that code (e.g., "Not Found" for 367 404, and so on), although it MAY be localized to suit client 368 preferences (expressed with the Accept-Language request header). 370 Please note that according to how the "type" member is defined 371 (Section 3.1), the "about:blank" URI is the default value for that 372 member. Consequently, any problem details object not carrying an 373 explicit "type" member implicitly uses this URI. 375 5. Security Considerations 377 When defining a new problem type, the information included must be 378 carefully vetted. Likewise, when actually generating a problem -- 379 however it is serialized -- the details given must also be 380 scrutinized. 382 Risks include leaking information that can be exploited to compromise 383 the system, access to the system, or the privacy of users of the 384 system. 386 Generators providing links to occurrence information are encouraged 387 to avoid making implementation details such as a stack dump available 388 through the HTTP interface, since this can expose sensitive details 389 of the server implementation, its data, and so on. 391 The "status" member duplicates the information available in the HTTP 392 status code itself, thereby bringing the possibility of disagreement 393 between the two. Their relative precedence is not clear, since a 394 disagreement might indicate that (for example) an intermediary has 395 modified the HTTP status code in transit (e.g., by a proxy or cache). 397 As such, those defining problem types as well as generators and 398 consumers of problems need to be aware that generic software (such as 399 proxies, load balancers, firewalls, and virus scanners) are unlikely 400 to know of or respect the status code conveyed in this member. 402 6. IANA Considerations 404 This specification defines two new Internet media types [RFC6838]. 406 6.1. application/problem+json 408 Type name: application 410 Subtype name: problem+json 412 Required parameters: None 413 Optional parameters: None; unrecognized parameters should be ignored 415 Encoding considerations: Same as [RFC7159] 417 Security considerations: see Section 5 of this document 419 Interoperability considerations: None 421 Published specification: RFC 7807 (this document) 423 Applications that use this media type: HTTP 425 Fragment identifier considerations: Same as for application/json 426 ([RFC7159]) 428 Deprecated alias names for this type: n/a 430 Magic number(s): n/a 432 File extension(s): n/a 434 Macintosh file type code(s): n/a 436 Person and email address to contact for further information: Mark No 437 ttingham 439 Intended usage: COMMON 441 Restrictions on usage: None. 443 Author: Mark Nottingham 445 Change controller: IESG 447 6.2. application/problem+xml 449 Type name: application 451 Subtype name: problem+xml 453 Required parameters: None 455 Optional parameters: None; unrecognized parameters should be ignored 457 Encoding considerations: Same as [RFC7303] 459 Security considerations: see Section 5 of this document 460 Interoperability considerations: None 462 Published specification: RFC 7807 (this document) 464 Applications that use this media type: HTTP 466 Fragment identifier considerations: Same as for application/xml (as 467 specified by Section 5 of [RFC7303]) 469 Deprecated alias names for this type: n/a 471 Magic number(s): n/a 473 File extension(s): n/a 475 Macintosh file type code(s): n/a 477 Person and email address to contact for further information: Mark No 478 ttingham 480 Intended usage: COMMON 482 Restrictions on usage: None. 484 Author: Mark Nottingham 486 Change controller: IESG 488 7. References 490 7.1. Normative References 492 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 493 Requirement Levels", BCP 14, RFC 2119, 494 DOI 10.17487/RFC2119, March 1997, 495 . 497 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 498 Resource Identifier (URI): Generic Syntax", STD 66, 499 RFC 3986, DOI 10.17487/RFC3986, January 2005, 500 . 502 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 503 Specifications: ABNF", STD 68, RFC 5234, 504 DOI 10.17487/RFC5234, January 2008, 505 . 507 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 508 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 509 2014, . 511 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 512 Protocol (HTTP/1.1): Message Syntax and Routing", 513 RFC 7230, DOI 10.17487/RFC7230, June 2014, 514 . 516 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 517 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 518 DOI 10.17487/RFC7231, June 2014, 519 . 521 [XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 522 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 523 Edition)", World Wide Web Consortium Recommendation REC- 524 xml-20081126, 26 November 2008, 525 . 527 7.2. Informative References 529 [HTML5] Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 530 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 531 World Wide Web Consortium Recommendation REC- 532 html5-20141028, 28 October 2014, 533 . 535 [ISO-19757-2] 536 International Organization for Standardization, 537 "Information Technology -- Document Schema Definition 538 Languages (DSDL) -- Part 2: Grammar-based Validation -- 539 RELAX NG", ISO/IEC 19757-2, 2003. 541 [RDFA] Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa 542 Core 1.1 - Second Edition", World Wide Web Consortium 543 Recommendation REC-rdfa-core-20130822, 22 August 2013, 544 . 546 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 547 Authoring and Versioning (WebDAV)", RFC 4918, 548 DOI 10.17487/RFC4918, June 2007, 549 . 551 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 552 DOI 10.17487/RFC5988, October 2010, 553 . 555 [RFC6694] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694, 556 DOI 10.17487/RFC6694, August 2012, 557 . 559 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 560 Specifications and Registration Procedures", BCP 13, 561 RFC 6838, DOI 10.17487/RFC6838, January 2013, 562 . 564 [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, 565 DOI 10.17487/RFC7303, July 2014, 566 . 568 [XSLT] Clark, J., Pieters, S., and H. Thompson, "Associating 569 Style Sheets with XML documents 1.0 (Second Edition)", 570 World Wide Web Consortium Recommendation REC-xml- 571 stylesheet-20101028, 28 October 2010, 572 . 574 Appendix A. HTTP Problems and XML 576 Some HTTP-based APIs use XML [XML] as their primary format 577 convention. Such APIs can express problem details using the format 578 defined in this appendix. 580 The RELAX NG schema [ISO-19757-2] for the XML format is as follows. 581 Keep in mind that this schema is only meant as documentation, and not 582 as a normative schema that captures all constraints of the XML 583 format. Also, it would be possible to use other XML schema languages 584 to define a similar set of constraints (depending on the features of 585 the chosen schema language). 587 default namespace ns = "urn:ietf:rfc:7807" 589 start = problem 591 problem = 592 element problem { 593 ( element type { xsd:anyURI }? 594 & element title { xsd:string }? 595 & element detail { xsd:string }? 596 & element status { xsd:positiveInteger }? 597 & element instance { xsd:anyURI }? ), 598 anyNsElement 599 } 601 anyNsElement = 602 ( element ns:* { anyNsElement | text } 603 | attribute * { text })* 605 The media type for this format is "application/problem+xml". 607 Extension arrays and objects are serialized into the XML format by 608 considering an element containing a child or children to represent an 609 object, except for elements that contain only child element(s) named 610 'i', which are considered arrays. For example, the example above 611 appears in XML as follows: 613 HTTP/1.1 403 Forbidden 614 Content-Type: application/problem+xml 615 Content-Language: en 617 618 619 https://example.com/probs/out-of-credit 620 You do not have enough credit. 621 Your current balance is 30, but that costs 50. 622 https://example.net/account/12345/msgs/abc 623 30 624 625 https://example.net/account/12345 626 https://example.net/account/67890 627 628 629 Note that this format uses an XML namespace. This is primarily to 630 allow embedding it into other XML-based formats; it does not imply 631 that it can or should be extended with elements or attributes in 632 other namespaces. The RELAX NG schema explicitly only allows 633 elements from the one namespace used in the XML format. Any 634 extension arrays and objects MUST be serialized into XML markup using 635 only that namespace. 637 When using the XML format, it is possible to embed an XML processing 638 instruction in the XML that instructs clients to transform the XML, 639 using the referenced XSLT code [XSLT]. If this code is transforming 640 the XML into (X)HTML, then it is possible to serve the XML format, 641 and yet have clients capable of performing the transformation display 642 human-friendly (X)HTML that is rendered and displayed at the client. 643 Note that when using this method, it is advisable to use XSLT 1.0 in 644 order to maximize the number of clients capable of executing the XSLT 645 code. 647 Appendix B. Using Problem Details with Other Formats 649 In some situations, it can be advantageous to embed problem details 650 in formats other than those described here. For example, an API that 651 uses HTML [HTML5] might want to also use HTML for expressing its 652 problem details. 654 Problem details can be embedded in other formats either by 655 encapsulating one of the existing serializations (JSON or XML) into 656 that format or by translating the model of a problem detail (as 657 specified in Section 3) into the format's conventions. 659 For example, in HTML, a problem could be embedded by encapsulating 660 JSON in a script tag: 662 674 or by inventing a mapping into RDFa [RDFA]. 676 This specification does not make specific recommendations regarding 677 embedding problem details in other formats; the appropriate way to 678 embed them depends both upon the format in use and application of 679 that format. 681 Acknowledgements 683 The authors would like to thank Jan Algermissen, Subbu Allamaraju, 684 Mike Amundsen, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, 685 Julian Reschke, and James Snell for review of this specification. 687 Authors' Addresses 689 Mark Nottingham 690 Prahran VIC 691 Australia 693 Email: mnot@mnot.net 694 URI: https://www.mnot.net/ 696 Erik Wilde 698 Email: erik.wilde@dret.net 699 URI: http://dret.net/netdret/ 701 Sanjay Dalal 703 Email: sanjay.dalal@cal.berkeley.edu 704 URI: https://github.com/sdatspun2