| < draft-ietf-appsawg-http-problem-00.txt | draft-ietf-appsawg-http-problem-01.txt > | |||
|---|---|---|---|---|
| Network Working Group M. Nottingham | Network Working Group M. Nottingham | |||
| Internet-Draft Akamai | Internet-Draft Akamai | |||
| Intended status: Standards Track E. Wilde | Intended status: Standards Track E. Wilde | |||
| Expires: March 23, 2015 UC Berkeley | Expires: March 10, 2016 UC Berkeley | |||
| September 19, 2014 | September 7, 2015 | |||
| Problem Details for HTTP APIs | Problem Details for HTTP APIs | |||
| draft-ietf-appsawg-http-problem-00 | draft-ietf-appsawg-http-problem-01 | |||
| Abstract | Abstract | |||
| This document defines a "problem detail" as a way to carry machine- | This document defines a "problem detail" as a way to carry machine- | |||
| readable details of errors in a HTTP response, to avoid the need to | readable details of errors in a HTTP response, to avoid the need to | |||
| invent new error response formats for HTTP APIs. | invent new error response formats for HTTP APIs. | |||
| Note to Readers | Note to Readers | |||
| This draft should be discussed on the apps-discuss mailing list [1]. | This draft should be discussed on the apps-discuss mailing list [1]. | |||
| skipping to change at page 1, line 37 ¶ | skipping to change at page 1, line 37 ¶ | |||
| Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
| Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
| working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
| Drafts is at http://datatracker.ietf.org/drafts/current/. | Drafts is at http://datatracker.ietf.org/drafts/current/. | |||
| Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
| and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
| time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
| material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
| This Internet-Draft will expire on March 23, 2015. | This Internet-Draft will expire on March 10, 2016. | |||
| Copyright Notice | Copyright Notice | |||
| Copyright (c) 2014 IETF Trust and the persons identified as the | Copyright (c) 2015 IETF Trust and the persons identified as the | |||
| document authors. All rights reserved. | document authors. All rights reserved. | |||
| This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
| Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
| (http://trustee.ietf.org/license-info) in effect on the date of | (http://trustee.ietf.org/license-info) in effect on the date of | |||
| publication of this document. Please review these documents | publication of this document. Please review these documents | |||
| carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
| to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
| include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
| the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
| described in the Simplified BSD License. | described in the Simplified BSD License. | |||
| Table of Contents | Table of Contents | |||
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 | |||
| 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3 | 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
| 3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4 | 3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4 | |||
| 3.1. Problem Details Object Members . . . . . . . . . . . . . 4 | 3.1. Problem Details Object Members . . . . . . . . . . . . . 5 | |||
| 3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 5 | 3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6 | |||
| 4. Defining New Problem Types . . . . . . . . . . . . . . . . . 5 | 4. Defining New Problem Types . . . . . . . . . . . . . . . . . 6 | |||
| 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 | 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
| 4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 7 | 4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 8 | |||
| 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 | 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 | |||
| 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 | 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 | |||
| 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 | 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 | |||
| 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 | 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 | 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 | |||
| 8.2. Informative References . . . . . . . . . . . . . . . . . 10 | 8.2. Informative References . . . . . . . . . . . . . . . . . 11 | |||
| Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 11 | Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 12 | |||
| Appendix B. Using Problem Details with Other Formats . . . . . . 12 | Appendix B. Using Problem Details with Other Formats . . . . . . 14 | |||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 | |||
| 1. Introduction | 1. Introduction | |||
| HTTP [RFC7230] status codes are sometimes not sufficient to convey | HTTP [RFC7230] status codes are sometimes not sufficient to convey | |||
| enough information about an error to be helpful. While humans behind | enough information about an error to be helpful. While humans behind | |||
| Web browsers can be informed about the nature of the problem with an | Web browsers can be informed about the nature of the problem with an | |||
| HTML [W3C.REC-html401-19991224] response body, non-human consumers of | HTML [W3C.REC-html401-19991224] response body, non-human consumers of | |||
| so-called "HTTP APIs" are usually not. | so-called "HTTP APIs" are usually not. | |||
| This specification defines simple JSON [RFC7159] and XML | This specification defines simple JSON [RFC7159] and XML | |||
| skipping to change at page 3, line 20 ¶ | skipping to change at page 3, line 20 ¶ | |||
| the account. | the account. | |||
| This specification does this by identifying a specific type of | This specification does this by identifying a specific type of | |||
| problem (e.g., "out of credit") with a URI [RFC3986]; HTTP APIs can | problem (e.g., "out of credit") with a URI [RFC3986]; HTTP APIs can | |||
| do this by nominating new URIs under their control, or by reusing | do this by nominating new URIs under their control, or by reusing | |||
| existing ones. | existing ones. | |||
| Additionally, problems can contain other information, such as a URI | Additionally, problems can contain other information, such as a URI | |||
| that identifies the specific occurrence of the problem (effectively | that identifies the specific occurrence of the problem (effectively | |||
| giving an identifier to the concept "The time Joe didn't have enough | giving an identifier to the concept "The time Joe didn't have enough | |||
| credit last Thursday"), which may be useful for support or forensic | credit last Thursday"), which can be useful for support or forensic | |||
| purposes. | purposes. | |||
| The data model for problem details is a JSON [RFC7159] object; when | The data model for problem details is a JSON [RFC7159] object; when | |||
| formatted as a JSON document, it uses the "application/problem+json" | formatted as a JSON document, it uses the "application/problem+json" | |||
| media type. Appendix A defines how to express them in an equivalent | media type. Appendix A defines how to express them in an equivalent | |||
| XML format, which uses the "application/problem+xml" media type. | XML format, which uses the "application/problem+xml" media type. | |||
| Note that problem details are (naturally) not the only way to convey | Note that problem details are (naturally) not the only way to convey | |||
| the details of a problem in HTTP; if the response is still a | the details of a problem in HTTP; if the response is still a | |||
| representation of a resource, for example, it's often preferable to | representation of a resource, for example, it's often preferable to | |||
| skipping to change at page 4, line 19 ¶ | skipping to change at page 4, line 19 ¶ | |||
| When serialised as a JSON document, that format is identified with | When serialised as a JSON document, that format is identified with | |||
| the "application/problem+json" media type. | the "application/problem+json" media type. | |||
| For example, a HTTP response carrying JSON problem details: | For example, a HTTP response carrying JSON problem details: | |||
| HTTP/1.1 403 Forbidden | HTTP/1.1 403 Forbidden | |||
| Content-Type: application/problem+json | Content-Type: application/problem+json | |||
| Content-Language: en | Content-Language: en | |||
| { | { | |||
| "type": "http://example.com/probs/out-of-credit", | "type": "https://example.com/probs/out-of-credit", | |||
| "title": "You do not have enough credit.", | "title": "You do not have enough credit.", | |||
| "detail": "Your current balance is 30, but that costs 50.", | "detail": "Your current balance is 30, but that costs 50.", | |||
| "instance": "http://example.net/account/12345/msgs/abc", | "instance": "/account/12345/msgs/abc", | |||
| "balance": 30, | "balance": 30, | |||
| "accounts": ["http://example.net/account/12345", | "accounts": ["/account/12345", | |||
| "http://example.net/account/67890"] | "/account/67890"] | |||
| } | } | |||
| Here, the out-of-credit problem (identified by its type URI) | Here, the out-of-credit problem (identified by its type URI) | |||
| indicates the reason for the 403 in "title", gives a reference for | indicates the reason for the 403 in "title", gives a reference for | |||
| the specific problem occurrence with "instance", gives occurrence- | the specific problem occurrence with "instance", gives occurrence- | |||
| specific details in "detail", and adds two extensions; "balance" | specific details in "detail", and adds two extensions; "balance" | |||
| conveys the account's balance, and "accounts" gives links where the | conveys the account's balance, and "accounts" gives links where the | |||
| account can be topped up. | account can be topped up. | |||
| The ability to convey problem-specific extensions allows more than | ||||
| one problem to be conveyed. For example: | ||||
| HTTP/1.1 400 Bad Request | ||||
| Content-Type: application/problem+json | ||||
| Content-Language: en | ||||
| { | ||||
| "type": "https://example.net/validation-error", | ||||
| "title": "Your request parameters didn't validate.", | ||||
| "invalid-params": [ { | ||||
| "name": "age", | ||||
| "reason": "must be a positive integer" | ||||
| }, | ||||
| { | ||||
| "name": "color", | ||||
| "reason": "must be 'green', 'red' or 'blue'"} | ||||
| ] | ||||
| } | ||||
| Note that this requires each of the sub-problems to be similar enough | ||||
| to use the same HTTP status code. If they do not, the 207 (Multi- | ||||
| Status) [RFC4918] code could be used to encapsulate multiple status | ||||
| messages. | ||||
| 3.1. Problem Details Object Members | 3.1. Problem Details Object Members | |||
| A problem details object MAY have the following members: | A problem details object MAY have the following members: | |||
| o "type" (string) - An absolute URI [RFC3986] that identifies the | o "type" (string) - A URI reference [RFC3986] that identifies the | |||
| problem type. When dereferenced, it SHOULD provide human-readable | problem type. When dereferenced, it is encouraged to provide | |||
| documentation for the problem type (e.g., using HTML | human-readable documentation for the problem type (e.g., using | |||
| [W3C.REC-html401-19991224]). When this member is not present, its | HTML [W3C.REC-html401-19991224]). When this member is not | |||
| value is assumed to be "about:blank". | present, its value is assumed to be "about:blank". | |||
| o "title" (string) - A short, human-readable summary of the problem | o "title" (string) - A short, human-readable summary of the problem | |||
| type. It SHOULD NOT change from occurrence to occurrence of the | type. It SHOULD NOT change from occurrence to occurrence of the | |||
| problem, except for purposes of localisation. | problem, except for purposes of localisation. | |||
| o "status" (number) - The HTTP status code ([RFC7231], Section 6) | o "status" (number) - The HTTP status code ([RFC7231], Section 6) | |||
| generated by the origin server for this occurrence of the problem. | generated by the origin server for this occurrence of the problem. | |||
| o "detail" (string) - An human readable explanation specific to this | o "detail" (string) - An human readable explanation specific to this | |||
| occurrence of the problem. | occurrence of the problem. | |||
| o "instance" (string) - An absolute URI that identifies the specific | o "instance" (string) - A URI reference that identifies the specific | |||
| occurrence of the problem. It may or may not yield further | occurrence of the problem. It may or may not yield further | |||
| information if dereferenced. | information if dereferenced. | |||
| Consumers MUST use the type string as the primary identifier for the | Consumers MUST use the type string as the primary identifier for the | |||
| problem type; the title string is advisory, and included only for | problem type; the title string is advisory, and included only for | |||
| users who are not aware of the semantics of the URI, and don't have | users who are not aware of the semantics of the URI, and don't have | |||
| the ability to discover them (e.g., offline log analysis). Consumers | the ability to discover them (e.g., offline log analysis). Consumers | |||
| SHOULD NOT automatically dereference the type URI. | SHOULD NOT automatically dereference the type URI. | |||
| The status member, if present, is only advisory; it conveys the HTTP | The status member, if present, is only advisory; it conveys the HTTP | |||
| skipping to change at page 5, line 32 ¶ | skipping to change at page 6, line 22 ¶ | |||
| behaves correctly. See Section 5 for further caveats regarding its | behaves correctly. See Section 5 for further caveats regarding its | |||
| use. | use. | |||
| The detail member, if present, SHOULD focus on helping the client | The detail member, if present, SHOULD focus on helping the client | |||
| correct the problem, rather than giving debugging information. | correct the problem, rather than giving debugging information. | |||
| Consumers SHOULD NOT parse the detail member for information; | Consumers SHOULD NOT parse the detail member for information; | |||
| extensions are more suitable and less error-prone ways to obtain such | extensions are more suitable and less error-prone ways to obtain such | |||
| information. | information. | |||
| Note that both "type" and "instance" accept relative URIs; this means | ||||
| that they must be resolved relative to the document's base URI, as | ||||
| per {{RFC3986}}, Section 5. | ||||
| 3.2. Extension Members | 3.2. Extension Members | |||
| Problem type definitions MAY extend the problem details object with | Problem type definitions MAY extend the problem details object with | |||
| additional members. | additional members. | |||
| For example, our "out of credit" problem above defines two such | For example, our "out of credit" problem above defines two such | |||
| extensions, "balance" and "accounts" to convey additional, problem- | extensions, "balance" and "accounts" to convey additional, problem- | |||
| specific information. | specific information. | |||
| Clients consuming problem details MUST ignore any such extensions | Clients consuming problem details MUST ignore any such extensions | |||
| that they don't recognise; this allows problem types to evolve and | that they don't recognise; this allows problem types to evolve and | |||
| include additional information in the future. | include additional information in the future. | |||
| Note that because extensions are effectively name spaced by the | ||||
| problem type, it is not possible to define new "standard" members | ||||
| without defining a new media type. | ||||
| 4. Defining New Problem Types | 4. Defining New Problem Types | |||
| When an HTTP API needs to define a response that indicates an error | When an HTTP API needs to define a response that indicates an error | |||
| condition, it might be appropriate to do so by defining a new problem | condition, it might be appropriate to do so by defining a new problem | |||
| type. | type. | |||
| Before doing so, it's important to understand what they are good for, | Before doing so, it's important to understand what they are good for, | |||
| and what's better left to other mechanisms. | and what's better left to other mechanisms. | |||
| Problem details are not a debugging tool for the underlying | Problem details are not a debugging tool for the underlying | |||
| skipping to change at page 10, line 10 ¶ | skipping to change at page 11, line 10 ¶ | |||
| The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu | The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu | |||
| Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, | Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall, | |||
| Julian Reschke, and James Snell for review of this specification. | Julian Reschke, and James Snell for review of this specification. | |||
| 8. References | 8. References | |||
| 8.1. Normative References | 8.1. Normative References | |||
| [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
| Requirement Levels", BCP 14, RFC 2119, March 1997. | Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ | |||
| RFC2119, March 1997, | ||||
| <http://www.rfc-editor.org/info/rfc2119>. | ||||
| [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | |||
| Resource Identifier (URI): Generic Syntax", STD 66, RFC | Resource Identifier (URI): Generic Syntax", STD 66, RFC | |||
| 3986, January 2005. | 3986, DOI 10.17487/RFC3986, January 2005, | |||
| <http://www.rfc-editor.org/info/rfc3986>. | ||||
| [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax | |||
| Specifications: ABNF", STD 68, RFC 5234, January 2008. | Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ | |||
| RFC5234, January 2008, | ||||
| <http://www.rfc-editor.org/info/rfc5234>. | ||||
| [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data | [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data | |||
| Interchange Format", RFC 7159, March 2014. | Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March | |||
| 2014, <http://www.rfc-editor.org/info/rfc7159>. | ||||
| [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol | [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer | |||
| (HTTP/1.1): Message Syntax and Routing", RFC 7230, June | Protocol (HTTP/1.1): Message Syntax and Routing", RFC | |||
| 2014. | 7230, DOI 10.17487/RFC7230, June 2014, | |||
| <http://www.rfc-editor.org/info/rfc7230>. | ||||
| [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol | [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer | |||
| (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. | Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI | |||
| 10.17487/RFC7231, June 2014, | ||||
| <http://www.rfc-editor.org/info/rfc7231>. | ||||
| 8.2. Informative References | 8.2. Informative References | |||
| [ISO-19757-2] | [ISO-19757-2] | |||
| International Organization for Standardization, | International Organization for Standardization, | |||
| "Information Technology --- Document Schema Definition | "Information Technology --- Document Schema Definition | |||
| Languages (DSDL) --- Part 2: Grammar-based Validation --- | Languages (DSDL) --- Part 2: Grammar-based Validation --- | |||
| RELAX NG", ISO/IEC 19757-2, 2003. | RELAX NG", ISO/IEC 19757-2, 2003. | |||
| [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. | [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed | |||
| Authoring and Versioning (WebDAV)", RFC 4918, DOI | ||||
| 10.17487/RFC4918, June 2007, | ||||
| <http://www.rfc-editor.org/info/rfc4918>. | ||||
| [RFC6694] Moonesamy, S., "The "about" URI Scheme", RFC 6694, August | [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ | |||
| 2012. | RFC5988, October 2010, | |||
| <http://www.rfc-editor.org/info/rfc5988>. | ||||
| [RFC6694] Moonesamy, S., Ed., "The "about" URI Scheme", RFC 6694, | ||||
| DOI 10.17487/RFC6694, August 2012, | ||||
| <http://www.rfc-editor.org/info/rfc6694>. | ||||
| [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type | [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type | |||
| Specifications and Registration Procedures", BCP 13, RFC | Specifications and Registration Procedures", BCP 13, RFC | |||
| 6838, January 2013. | 6838, DOI 10.17487/RFC6838, January 2013, | |||
| <http://www.rfc-editor.org/info/rfc6838>. | ||||
| [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, | [RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303, | |||
| July 2014. | DOI 10.17487/RFC7303, July 2014, | |||
| <http://www.rfc-editor.org/info/rfc7303>. | ||||
| [W3C.REC-html401-19991224] | [W3C.REC-html401-19991224] | |||
| Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 | Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 | |||
| Specification", World Wide Web Consortium Recommendation | Specification", World Wide Web Consortium Recommendation | |||
| REC-html401-19991224, December 1999, | REC-html401-19991224, December 1999, | |||
| <http://www.w3.org/TR/1999/REC-html401-19991224>. | <http://www.w3.org/TR/1999/REC-html401-19991224>. | |||
| [W3C.REC-rdfa-core-20120607] | [W3C.REC-rdfa-core-20120607] | |||
| Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa | Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa | |||
| Core 1.1", World Wide Web Consortium Recommendation REC- | Core 1.1", World Wide Web Consortium Recommendation REC- | |||
| skipping to change at page 12, line 17 ¶ | skipping to change at page 13, line 37 ¶ | |||
| object, except for elements that contain only child element(s) named | object, except for elements that contain only child element(s) named | |||
| 'i', which are considered arrays. For example, an alternate version | 'i', which are considered arrays. For example, an alternate version | |||
| of the example above would appear in XML as: | of the example above would appear in XML as: | |||
| HTTP/1.1 403 Forbidden | HTTP/1.1 403 Forbidden | |||
| Content-Type: application/problem+xml | Content-Type: application/problem+xml | |||
| Content-Language: en | Content-Language: en | |||
| <?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | |||
| <problem xmlns="urn:ietf:rfc:XXXX"> | <problem xmlns="urn:ietf:rfc:XXXX"> | |||
| <type>http://example.com/probs/out-of-credit</type> | <type>https://example.com/probs/out-of-credit</type> | |||
| <title>You do not have enough credit.</title> | <title>You do not have enough credit.</title> | |||
| <detail>Your current balance is 30, but that costs 50.</detail> | <detail>Your current balance is 30, but that costs 50.</detail> | |||
| <instance> | <instance> | |||
| http://example.net/account/12345/msgs/abc | https://example.net/account/12345/msgs/abc | |||
| </instance> | </instance> | |||
| <balance>30</balance> | <balance>30</balance> | |||
| <accounts> | <accounts> | |||
| <i>http://example.net/account/12345</i> | <i>https://example.net/account/12345</i> | |||
| <i>http://example.net/account/67890</i> | <i>https://example.net/account/67890</i> | |||
| </accounts> | </accounts> | |||
| </problem> | </problem> | |||
| Note that this format uses an XML Namespace. This is primarily to | Note that this format uses an XML Namespace. This is primarily to | |||
| allow embedding it into other XML-based formats; it does not imply | allow embedding it into other XML-based formats; it does not imply | |||
| that it can or should be extended with elements or attributes in | that it can or should be extended with elements or attributes in | |||
| other namespaces. The RELAX NG schema explicitly only allows | other namespaces. The RELAX NG schema explicitly only allows | |||
| elements from the one namespace used in the XML format. Any | elements from the one namespace used in the XML format. Any | |||
| extension arrays and objects MUST be serialized into XML markup using | extension arrays and objects MUST be serialized into XML markup using | |||
| only that namespace. | only that namespace. | |||
| skipping to change at page 13, line 7 ¶ | skipping to change at page 14, line 26 ¶ | |||
| Problem details can be embedded in other formats by either | Problem details can be embedded in other formats by either | |||
| encapsulating one of the existing serializations (JSON or XML) into | encapsulating one of the existing serializations (JSON or XML) into | |||
| that format, or by translating the model of a Problem Detail (as | that format, or by translating the model of a Problem Detail (as | |||
| specified in Section 3) into the format's conventions. | specified in Section 3) into the format's conventions. | |||
| For example, in HTML, a problem could be embedded by encapsulating | For example, in HTML, a problem could be embedded by encapsulating | |||
| JSON in a script tag: | JSON in a script tag: | |||
| <script type="application/problem+json"> | <script type="application/problem+json"> | |||
| { | { | |||
| "type": "http://example.com/probs/out-of-credit", | "type": "https://example.com/probs/out-of-credit", | |||
| "title": "You do not have enough credit.", | "title": "You do not have enough credit.", | |||
| "detail": "Your current balance is 30, but that costs 50.", | "detail": "Your current balance is 30, but that costs 50.", | |||
| "instance": "http://example.net/account/12345/msgs/abc", | "instance": "/account/12345/msgs/abc", | |||
| "balance": 30, | "balance": 30, | |||
| "accounts": ["http://example.net/account/12345", | "accounts": ["/account/12345", | |||
| "http://example.net/account/67890"] | "/account/67890"] | |||
| } | } | |||
| </script> | </script> | |||
| } | } | |||
| or by inventing a mapping into RDFa [W3C.REC-rdfa-core-20120607]. | or by inventing a mapping into RDFa [W3C.REC-rdfa-core-20120607]. | |||
| This specification does not make specific recommendations regarding | This specification does not make specific recommendations regarding | |||
| embedding Problem Details in other formats; the appropriate way to | embedding Problem Details in other formats; the appropriate way to | |||
| embed them depends both upon the format in use and application of | embed them depends both upon the format in use and application of | |||
| that format. | that format. | |||
| End of changes. 30 change blocks. | ||||
| 54 lines changed or deleted | 106 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||