Status of This Memo

This is an Internet Standards Track document.¶

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc9290.¶

Copyright Notice

Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1.Introduction

REST response status information such as Constrained Application Protocol (CoAP) responsecodes (Section 5.9 of [RFC7252]) is sometimes not sufficient to convey enough information aboutan error to be helpful. This specification defines a simple and extensibleframework to define Concise Binary Object Representation (CBOR)[STD94] data items to suit this purpose.This framework is designed to be reused by REST APIs, which can identify distinct"shapes" of these data items specific to their needs.Thus, API clients can be informed of both the high-level error class(using the response code) and the finer-grained details of the problem(using the vocabulary defined here). This pattern of communication is illustrated inFigure 1.¶

The framework presented is largely inspired by the problem details for HTTP APIs defined in[RFC7807].Appendix B discusses applications where interworking with[RFC7807] is required.¶

2.Basic Problem Details

A Concise Problem Details data item is a CBOR data item with the followingstructure (rules named starting withtag38 are defined inAppendix A):¶

problem-details = non-empty<{  ? &(title: -1) => oltext  ? &(detail: -2) => oltext  ? &(instance: -3) => ~uri  ? &(response-code: -4) => uint .size 1  ? &(base-uri: -5) => ~uri  ? &(base-lang: -6) => tag38-ltag  ? &(base-rtl: -7) => tag38-direction  standard-problem-detail-entries  custom-problem-detail-entries}>standard-problem-detail-entries = (  * nint => any)custom-problem-detail-entries = (  * (uint/~uri) => { + any => any })non-empty<M> = (M) .and ({ + any => any })oltext = text / tag38

(Examples of elaborated Concise Problem Details data items canbe found later in the document, e.g.,Figure 3.)¶

A number of problem detail entries, the Standard Problem Detailentries, are predefined (more predefined details can be registered,seeSection 3.1).¶

Note that, unlike[RFC7807], Concise Problem Details data items haveno explicit "problem type".Instead, the category (or, one could say, Gestalt) of the problem canbe understood from the shape of the problem details offered. We talk ofa "problem shape" for short.¶

The title (key -1):

A short, human-readable summary of the problem shape.Beyond the shape of the problem, it is not intended to summarize allthe specific information given with the problem details.For instance, the summary might include that an account does nothave enough money for a transaction to succeed but not the detailedinformation such as the account number, how much money that accounthas, and how much would be needed.¶

The detail (key -2):

A human-readable explanation specific to this occurrence of the problem.¶

The instance (key -3):

A URI reference that identifies the specific occurrence of the problem.It may or may not yield further information if dereferenced.¶

The response-code (key -4):

The CoAP response code (Sections5.9 and12.1.2 of[RFC7252]) generated by the originserver for this occurrence of the problem.¶

The base-uri (key -5):

The base URI (see Section5.1 of RFC 3986[STD66]) that should be used to resolverelative URI references embedded in this Concise Problem Detailsdata item.¶

The base-lang (key -6):

The language-tag (tag38-ltag) that applies to the presentation ofunadorned text strings (not using tag 38) in this Concise ProblemDetails data item; seeAppendix A.¶

The base-rtl (key -7):

The writing-direction (tag38-direction) that applies to thepresentation of unadorned text strings (not using tag 38) in thisConcise Problem Details data item; seeAppendix A.¶

Both "title" and "detail" can use either an unadorned CBOR text string(text) or a language-tagged text string (tag38); seeAppendix A forthe definition of the latter.Language tag and writing direction information for unadorned textstrings is intended to be obtained from context; if that contextneeds to be saved or forwarded with a Concise Problem Details dataitem, "base-lang" and "base-rtl" can be used.If no such (explicitly saved or implicit) context information isavailable, unadorned text is interpreted with language-tag "en" andwriting-direction "false" (ltr).¶

The "title" string is advisory and included to giveconsumers a shorthand for the category (problem shape) of the error encountered.¶

The "detail" member, if present, ought to focus on helping the clientcorrect the problem rather than giving extensive server-sidedebugging information.ConsumersSHOULD NOT parse the "detail" member for information;extensions (seeSection 3) are more suitable and lesserror-prone ways to obtain such information.Note that the "instance" URI reference may be relative; this meansthat it must be resolved relative to the representation's base URI, asper Section5 of RFC 3986[STD66].¶

The "response-code" member, if present, is only advisory; it conveysthe CoAP response code used for the convenience of the consumer.GeneratorsMUST use the same response code here as in the actual CoAPresponse; the latter is needed to assure that generic CoAP software thatdoes not understand the problem-details format still behavescorrectly.Consumers can use the "response-code" member to determine what theoriginal response code used by the generator was, in cases where ithas been changed (e.g., by an intermediary or cache), and when messagebodies persist without CoAP information (e.g., in an events log or analyticsdatabase).Generic CoAP software will still use the CoAP response code.To support the use case of message-body persistence without support bythe problem-details generator, the entity that persists the ConciseProblem Details data item can copy over the CoAP response codethat it received on the CoAP level.Note that the "response-code" value is a numeric representation of theactual code (seeSection 3 of [RFC7252]), so it does not take the usualpresentation form that resembles anHTTP status code:4.04 Not Found is represented by the number 132.¶

The "base-uri" member is usually not present in the initialrequest-response communication as it can be inferred as per Section5.1.3 of RFC 3986[STD66].An entity that stores a Concise Problem Details data item or otherwisemakes it available for consumers without this context might add in a"base-uri" member to allow those consumers to perform resolution of anyrelative URI references embedded in the data item.¶

3.Extending Concise Problem Details

This specification defines a generic problem-details container with only aminimal set of attributes to make it usable.¶

It is expected that applications will extend the base format by defining newattributes.¶

These new attributes fall into two categories: generic and applicationspecific.¶

Generic attributes will be allocated in thestandard-problem-detail-entriesslot according to the registration procedure defined inSection 3.1.¶

Application-specific attributes will be allocated in thecustom-problem-detail-entries slot according to the procedure described inSection 3.2.¶

{  / title /         -1: "title of the error",  / detail /        -2: "detailed information about the error",  / instance /      -3: "coaps://pd.example/FA317434",  / response-code / -4: 128, / 4.00 /  "tag:3gpp.org,2022-03:TS29112": {    / cause /  0: "machine-readable error cause",    / invalidParams / 1: [      [        / param / "first parameter name",        / reason / "must be a positive integer"      ],      [        / param / "second parameter name"      ]    ],    / supportedFeatures / 2: "d34db33f"  }}

{  / title /         -1: "title of the error",  / detail /        -2: "detailed information about the error",  / instance /      -3: "coaps://pd.example/FA317434",  / response-code / -4: 128, / 4.00 /  /4711 is made-up example key that is not actually registered:/  4711: {    / cause /  0: "machine-readable error cause",    / invalidParams / 1: [      [        / param / "first parameter name",        / reason / "must be a positive integer"      ],      [        / param / "second parameter name"      ]    ],    / supportedFeatures / 2: "d34db33f"  }}

4.Privacy Considerations

Problem details may unintentionally disclose information.This can lead to both privacy and security problems.SeeSection 5 for more details that apply to both domains; particularattention needs to be given to unintentionally disclosing PersonallyIdentifiable Information (PII).¶

5.Security Considerations

Concise Problem Details can contain URIs that are not intended to bedereferenced (Section 3.2, Paragraph 5). One reason is that dereferencingthese can lead to information disclosure (tracking).Information disclosure can also be caused by URIs in problem detailsthatare intended for dereferencing, e.g., the "instance" URI.Implementations need to consider which component of a client shouldperform the dereferencing and which servers are trusted with servingthem.In any case, the security considerations of Section7 of RFC 3986[STD66] apply.¶

The security and privacy considerations outlined inSection 5 of [RFC7807] apply in full.While these are phrased in terms of security considerations for new RFC 7807 problem types, they equally apply to the problem detailentry definitions used here (Section 3). In summary, bothwhen defining new detail entries and when actually using them to generate aConcise Problem Details data item, care needs to be taken that they donot leak sensitive information.Entities storing or forwarding Concise Problem Details data items needto consider whether this leads to information being transferred out ofthe context within which access to sensitive information was acceptable.See alsoSection 3, Paragraph 6 (the last paragraph of the introduction tothat section).Privacy-sensitive information in the problem detailsSHOULD NOT be obscured in ways that might lead to misclassification asnon-sensitive (e.g., by base64-encoding).¶

6.IANA Considerations

Appendix A.Language-Tagged Strings

This appendix serves as the archival documentation for CBOR tag 38, atag for serializing language-tagged text strings in CBOR.The text of this appendix is adapted from the specification textsupplied for its initial registration.It has been extended to allow supplementing the language tag by adirection indication.¶

As with any IANA-registered item, a specification that further updates thisregistration needs to update the reference column of the IANA registry (seeSection 6.5).Future specifications may update this appendix, other parts of this document,or both.(When updating this appendix, keep in mind that applications beyondConcise Problem Details data items may adopt the tag defined here.)Users of this tag are advised to consult the registry to obtain themost recent update for this appendix.¶

tag38 = #6.38([tag38-ltag, text, ?tag38-direction])tag38-ltag = text .regexp "[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*"tag38-direction = &(ltr: false, rtl: true, auto: null)

38(["en", "Hello"])

D8 26               # tag(38)   82               # array(2)      62            # text(2)         656E       # "en"      65            # text(5)         48656C6C6F # "Hello"

38(["fr", "Bonjour"])

D8 26                   # tag(38)   82                   # array(2)      62                # text(2)         6672           # "fr"      67                # text(7)         426F6E6A6F7572 # "Bonjour"

שלום

38(["he", "שלום", true])

D8 26                     # tag(38)   83                     # array(3)      62                  # text(2)         6865             # "he"      68                  # text(8)         D7A9D79CD795D79D # "שלום"      F5                  # primitive(21)

Appendix B.Interworking with RFC 7807

On certain occasions, it will be necessary to carry ("tunnel")[RFC7807] problem details in a Concise Problem Details data item.¶

This appendix defines a Custom Problem Detail entry for that purpose.This is assigned Custom Problem Detail key 7807 inSection 6.2.Its structure is:¶

tunnel-7807 = {  ? &(type: 0) => ~uri  ? &(status: 1) => 0..999  * text => any}

To carry an[RFC7807] problem details JSON object in a Concise ProblemDetails data item, first convert the JSON object to CBOR as per Section6.2 of RFC 8949[STD94]. Create an empty Concise Problem Details data item.¶

Move the values for "title", "detail", and "instance", if present,from the[RFC7807] problem details to the equivalent Standard ProblemDetail entries.Create a Custom Problem Detail entry with key 7807.Move the values for "type" and "status", if present, to the equivalentkeys 0 and 1 of the Custom Problem Detail entry.Move all remaining key/value pairs (additional members as perSection 3.2 of [RFC7807]) in the converted[RFC7807] problemdetails object to the Custom Problem Detail map unchanged.¶

The inverse direction, carrying Concise Problem Details in an RFC 7807 problemdetails JSON object requires the additional support provided by[HTTPAPI], which is planned to create the HTTP Problem TypesRegistry. An HTTP Problem Type can then be registered that extractstop-level items from the Concise Problem Details data item in a similar wayto the conversion described above and that carries the rest of theConcise Problem Details data item in an additional member via base64urlencoding without padding (Section 5 of [RFC4648]). Details can be definedin a separate document when the work on[HTTPAPI] is completed.¶

Acknowledgments

The authors would like to thankMark Nottingham andErik Wilde, the authors of RFC 7807;Klaus Hartke andJaime Jiménez, the coauthors of an earlier draft version of thisspecification;Christian Amsüss,Marco Tiloca,Ari Keränen,andMichael Richardson for review and comments on this document.Francesca Palombini for her review (and support) as responsible AD,andJoel Jaeggli for his OPSDIR review, both of which broughtsignificant additional considerations to this document.¶

ForAppendix A,John Cowan andDoug Ewell are also to be acknowledged.The content of an earlier draft version of this appendix was also discussedin the "apps-discuss@ietf.org" and "ltru@ietf.org" mailinglists.More recently, the authors initiated a discussion about the handlingof writing direction information in conjunction with language tags.That led to discussions within the W3C Internationalization CoreWorking Group.The authors would like to acknowledge that cross-organizationcooperation and particular contributions fromJohn Klensin andAddison Phillips and specific text proposals byMartin Dürst.¶

Contributors

Peter defined CBOR tag 38, basis ofAppendix A.¶

Christian contributed what becameSection 3.1.1.¶

Authors' Addresses