]> Concise Problem Details For CoAP APIs arm
thomas.fossati@arm.com
Universität Bremen TZI
Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org
ART CoRE Working Group CoAP, API, Problem Details This document defines a concise "problem detail" as a way to carry machine-readable details of errors in a REST response to avoid the need to define new error response formats for REST APIs for constrained environments. The format is inspired by, but intended to be more concise than, the Problem Details for HTTP APIs defined in RFC 7807. About This Document Status information for this document may be found at . Discussion of this document takes place on the Constrained RESTful Environments Working Group mailing list (), which is archived at . Source for this draft and an issue tracker can be found at .
Introduction REST response status information such as CoAP response codes () is sometimes not sufficient to convey enough information about an error to be helpful. This specification defines a simple and extensible framework to define CBOR data items to suit this purpose. It 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 in .
Problem Details: Example with CoAP CoAP CoAP Client Server Request (failure) Error Response with a CBOR data item giving Problem Details | | | (failure) |<-----------------o | Error Response | | with a CBOR | | data item giving | | Problem Details | | | ]]>
The framework presented is largely inspired by the Problem Details for HTTP APIs defined in . discusses applications where interworking with is required.
Terminology and Requirements Language The terminology from , , and applies; in particular CBOR diagnostic notation is defined in and . Readers are also expected to be familiar with the terminology from . In this document, the structure of data is specified in CDDL . The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.
Basic Problem Details A Concise Problem Details data item is a CBOR data item with the following structure (rules named starting with tag38 are defined in ):
Structure of Concise Problem Details Data Item 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) .and ({ + any => any }) oltext = text / tag38 ]]>
A number of problem detail entries, the Standard Problem Detail entries, are predefined (more predefined details can be registered, see ). Note that, unlike , Concise Problem Details data items have no explicit "problem type". Instead, the category (or, one could say, Gestalt) of the problem can be understood from the shape of the problem details offered. We talk of a "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 all the specific information given with the problem details. For instance, the summary might include that an account does not have enough money for a transaction to succeed, but not the detail information such as the account number, how much money that account has, 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 (Sections and of ) generated by the origin server for this occurrence of the problem.
The base-uri (key -5):
The base URI () that should be used to resolve relative URI references embedded in this Concise Problem Details data item.
The base-lang (key -6):
The language-tag (tag38-ltag) that applies to the presentation of unadorned text strings in this Concise Problem Details data item, see .
The base-rtl (key -7):
The writing-direction (tag38-direction) that applies to the presentation of unadorned text strings in this Concise Problem Details data item, see .
Both "title" and "detail" can use either an unadorned CBOR text string (text) or a language-tagged text string (tag38); see for the definition of the latter. Language tag and writing direction information for unadorned text strings are intended to be obtained from context; if that context needs to be saved or forwarded with a Concise Problem Details data item, "base-lang" and "base-rtl" can be used for that. If no such (explicitly saved or implicit) context information is available, unadorned text is interpreted with language-tag "en" and writing-direction "false" (ltr). The "title" string is advisory and included to give consumers a shorthand for the category (problem shape) of the error encountered. The "detail" member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information. Consumers SHOULD NOT parse the "detail" member for information; extensions (see ) are more suitable and less error-prone ways to obtain such information. Note that the "instance" URI reference may be relative; this means that it must be resolved relative to the representation's base URI, as per . The "response-code" member, if present, is only advisory; it conveys the CoAP response code used for the convenience of the consumer. Generators MUST use the same response code here as in the actual CoAP response; the latter is needed to assure that generic CoAP software that does not understand the problem-details format still behaves correctly. Consumers can use the response-code member to determine what the original response code used by the generator was, in cases where it has been changed (e.g., by an intermediary or cache), and when message bodies persist without CoAP information (e.g., in an events log or analytics database). Generic CoAP software will still use the CoAP response code. To support the use case of message body persistence without support by the problem-details generator, the entity that persists the Concise Problem Details data item can copy over the CoAP response code that it received on the CoAP level. Note that the "response-code" value is a numeric representation of the actual code (see ), so it does not take the usual presentation form that resembles an HTTP status code -- 4.04 Not found is represented by the number 132. The "base-uri" member is usually not present in the initial request-response communication as it can be inferred as per . An entity that stores a Concise Problem Details data item or otherwise makes it available for consumers without this context might add in a base-uri member to allow those consumers to perform resolution of any relative URI references embedded in the data item.
Extending Concise Problem Details This specification defines a generic problem details container with only a minimal set of attributes to make it usable. It is expected that applications will extend the base format by defining new attributes. These new attributes fall into two categories: generic and application specific. Generic attributes will be allocated in the standard-problem-detail-entries slot according to the registration procedure defined in . Application-specific attributes will be allocated in the custom-problem-detail-entries slot according to the procedure described in . Consumers of a Concise Problem Details data item MUST ignore any Standard or Custom Problem Detail entries, or keys inside the Custom Problem Detail entries, that they do not recognize ("ignore-unknown rule"); this allows problem details to evolve. When storing the data item for future use or forwarding it to other consumers, it is strongly RECOMMENDED to retain the unrecognized entries; exceptions might be when storage/forwarding occurs in a different format/protocol that cannot accommodate them, or when the storage/forwarding function needs to filter out privacy-sensitive information and for that needs to assume unrecognized entries might be privacy-sensitive.
Standard Problem Detail Entries Beyond the Standard Problem Detail keys defined in , additional Standard Problem Detail keys can be registered for use in the standard-problem-detail-entries slot (see ). Standard Problem Detail keys are negative integers, so they can never conflict with Custom Problem Detail keys defined for a specific application domain (which are unsigned integers or URIs.) In summary, the keys for Standard Problem Detail entries are in a global namespace that is not specific to a particular application domain.
Standard Problem Detail Entry: Unprocessed CoAP Option provides a number of generally applicable Standard Problem Detail Entries. The present section both registers another useful Standard Problem Detail entry and serves as an example of a Standard Problem Detail Entry registration, in the registration template format that would be ready for registration.
Key Value:
TBD (assigned at registration)
Name:
unprocessed-coap-option
CDDL type:
one-or-more<uint>, where = T / [ 2* T ] ]]>
Brief description:
Option number(s) of CoAP option(s) that were not understood
Specification reference:
of RFC XXXX
The specification of the Standard Problem Detail entry referenced by the above registration template follows: The Standard Problem Detail entry unprocessed-coap-option provides the option number(s) of CoAP option(s) present in the request that could not be processed by the server. This may be a critical option that the server is unaware of, or an option the server is aware of but could not process (and chose not to, or was not allowed to, ignore it). The Concise Problem Details data item including this Standard Problem Detail Entry can be used in fulfillment of the "SHOULD" requirement in . Several option numbers may be given in a list (in no particular order), without any guarantee that the list is a complete representation of all the problems in the request (as the server might have stopped processing already at one of the problematic options). If an option with the given number was repeated, there is no indication which of the values caused the error. Clients need to expect seeing options in the list they did not send in the request; this can happen if the request traversed a proxy that added the option but did not act on the problem details response being returned by the origin server. Note that for a few special values of unprocessed CoAP options (such as Accept or Proxy-Uri), there are special response codes (4.06 Not Acceptable, 5.05 Proxying Not Supported, respectively) to be sent instead of 4.02 Bad Option.
Custom Problem Detail Entries Applications may extend the Problem Details data item with additional entries to convey additional, application-specific information. Such new entries are allocated in the custom-problem-detail-entries slot, and carry a nested map specific to that application. The map key can either be an (absolute!) URI (under control of the entity defining this extension), or an unsigned integer. Only the latter needs to be registered (). Within the nested map, any number of attributes can be given for a single extension. The semantics of each custom attribute MUST be described in the documentation for the extension; for extensions that are registered (i.e., are identified by an unsigned int) that documentation goes along with the registration. The unsigned integer form allows a more compact representation. In exchange, authors are expected to comply with the required registration and documentation process. In comparison, the URI form is less space-efficient but requires no registration. It is therefore useful for experimenting during the development cycle and for applications deployed in environments where producers and consumers of Concise Problem Details are more tightly integrated. (The URI form thus covers the potential need we might otherwise have for a "private use" range for the unsigned integers.) Note that the URI given for the extension is for identification purposes only and, even if dereferenceable in principle, it MUST NOT be dereferenced in the normal course of handling problem details (i.e., outside diagnostic/debugging procedures involving humans). shows an example (in CBOR diagnostic notation) of a custom extension using a (made-up) URI as custom-problem-detail-entries key.
Example Extension with URI key
Obviously, an SDO like 3GPP can also easily register such a custom problem detail entry to receive a more efficient unsigned integer key; shows how the same example would look like using a (made-up) registered unsigned int as custom-problem-detail-entries key:
Example Extension with unsigned int (registered) key
In summary, the keys for the maps used inside Custom Problem Detail entries are defined specifically to the identifier of that Custom Problem Detail entry, the documentation of which defines these internal entries, typically chosen to address a given application domain. When there is a need to evolve a Custom Problem Detail entry definition, the "ignore-unknown rule" discussed in the introduction to provides an easy way to include additional information. The assumption is that this is done in a backward and forward compatible way. Sometimes, Custom Problem Detail entries may need to evolve in a way where forward compatibility by applying the "ignore-unknown rule" would not be appropriate: e.g., when adding a "must-understand" member, which can only be ignored at the peril of misunderstanding the Concise Problem Details data item ("false interoperability"). In this case, a new Custom Problem Detail key can simply be registered for this case, keeping the old key backward and forward compatible.
Security Considerations The security and privacy considerations outlined in Section 5 of apply in full.
IANA Considerations RFC Editor: please replace RFC XXXX with this RFC number and remove this note.
Standard Problem Detail Key registry This specification defines a new sub-registry for Standard Problem Detail Keys in the CoRE Parameters registry , with the policy "specification required" . Each entry in the registry must include:
Key value:
a negative integer to be used as the value of the key
Name:
a name that could be used in implementations for the key
CDDL type:
type of the data associated with the key in CDDL notation
Brief description:
a brief description
reference:
a reference document
Initial entries in this sub-registry are as follows: Initial Entries in the Standard Problem Detail Key registry
Key value Name CDDL Type Brief description Reference
-1 title text / tag38 short, human-readable summary of the problem shape RFC XXXX
-2 detail text / tag38 human-readable explanation specific to this occurrence of the problem RFC XXXX
-3 instance ~uri URI reference identifying specific occurrence of the problem RFC XXXX
-4 response-code uint .size 1 CoAP response code RFC XXXX
-5 base-uri ~uri Base URI RFC XXXX
-6 base-lang tag38-ltag Base language tag (see ) RFC XXXX
-7 base-rtl tag38-direction Base writing direction (see ) RFC XXXX
TBD unprocessed-coap-option one-or-more<uint> Option number(s) of CoAP option(s) that were not understood RFC XXXX,
Custom Problem Detail Key registry This specification defines a new sub-registry for Custom Problem Detail Keys in the CoRE Parameters registry , with the policy "first come first served" . Each entry in the registry must include:
Key value:
an unsigned integer to be used as the value of the key
Name:
a name that could be used in implementations for the key
Brief description:
a brief description
Reference:
a reference document that provides a description of the map, including a CDDL description, that describes all inside keys and values
Initial entries in this sub-registry are as follows: Initial Entries in the Custom Problem Detail Key registry
Key value Name Brief description Reference
7807 tunnel-7807 Carry RFC 7807 problem details in a Concise Problem Details data item RFC XXXX,
Media Type IANA is requested to add the following Media-Type to the "Media Types" registry . New Media Type application/concise-problem-details+cbor
Name Template Reference
concise-problem-details+cbor application/concise-problem-details+cbor RFC XXXX,
Type name:
application
Subtype name:
concise-problem-details+cbor
Required parameters:
none
Optional parameters:
none
Encoding considerations:
binary (CBOR data item)
Security considerations:
of RFC XXXX
Interoperability considerations:
none
Published specification:
of RFC XXXX
Applications that use this media type:
Clients and servers in the Internet of Things
Fragment identifier considerations:
The syntax and semantics of fragment identifiers is as specified for "application/cbor". (At publication of RFC XXXX, there is no fragment identification syntax defined for "application/cbor".)
Person & email address to contact for further information:
CoRE WG mailing list (core@ietf.org), or IETF Applications and Real-Time Area (art@ietf.org)
Intended usage:
COMMON
Restrictions on usage:
none
Author/Change controller:
IETF
Provisional registration:
no
Content-Format IANA is requested to register a Content-Format number in the sub-registry, within the "Constrained RESTful Environments (CoRE) Parameters" Registry , as follows: New Content-Format
Content-Type Content Coding ID Reference
application/concise-problem-details+cbor - TBD1 RFC XXXX
TBD1 is to be assigned from the space 256..999. In the registry as defined by at the time of writing, the column "Content-Type" is called "Media type" and the column "Content Coding" is called "Encoding". This paragraph to be removed by RFC editor.
CBOR Tag 38 In the registry "" , IANA has registered CBOR Tag 38. IANA is requested to replace the reference for this registration with , RFC XXXX.
References Normative References Concise Binary Object Representation (CBOR) The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. Uniform Resource Identifier (URI): Generic Syntax A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] The Constrained Application Protocol (CoAP) The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. Problem Details for HTTP APIs 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 define new error response formats for HTTP APIs. Concise Binary Object Representation (CBOR) Tags IANA Tags for Identifying Languages This document describes the structure, content, construction, and semantics of language tags for use in cases where it is desirable to indicate the language used in an information object. It also describes how to register values for use in language tags and the creation of user-defined extensions for private interchange. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Matching of Language Tags This document describes a syntax, called a "language-range", for specifying items in a user's list of language preferences. It also describes different mechanisms for comparing and matching these to language tags. Two kinds of matching mechanisms, filtering and lookup, are defined. Filtering produces a (potentially empty) set of language tags, whereas lookup produces a single language tag. Possible applications include language negotiation or content selection. This document, in combination with RFC 4646, replaces RFC 3066, which replaced RFC 1766. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. Additional Control Operators for the Concise Data Definition Language (CDDL) The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. The present document defines a number of control operators that were not yet ready at the time RFC 8610 was completed: , , and for the construction of constants; / for including ABNF (RFC 5234 and RFC 7405) in CDDL specifications; and for indicating the use of a non-basic feature in an instance. Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Constrained RESTful Environments (CoRE) Parameters IANA Guidelines for Writing an IANA Considerations Section in RFCs Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. Media Types IANA Informative References The Base16, Base32, and Base64 Data Encodings This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] Problem Details for HTTP APIs This document defines a "problem detail" to carry machine-readable details of errors in HTTP response content and/or fields to avoid the need to define new error response formats for HTTP APIs. Discussion Venues This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/ietf-wg-httpapi/rfc7807bis. RDF 1.1 Concepts and Abstract Syntax W3C Recommendation Strings on the Web: Language and Direction Metadata W3C group draft note The Unicode Standard, Version 14.0.0 The Unicode Consortium Note that while this document references a version that was recent at the time of writing, the statements made based on this version are expected to remain valid for future versions. Mountain View: The Unicode Consortium
Language-Tagged Strings This appendix serves as the archival documentation for CBOR Tag 38, a tag for serializing language-tagged text strings in CBOR. The text of this appendix is adapted from the specification text supplied for its initial registration. It has been extended to allow supplementing the language tag by a direction indication.
Introduction In some cases it is useful to specify the natural language of a text string. This specification defines a tag that does just that. One technology that supports language-tagged strings is the Resource Description Framework (RDF) .
Detailed Semantics A language-tagged string in CBOR has the tag 38 and consists of an array with a length of 2 or 3. The first element is a well-formed language tag under Best Current Practice 47 ( and ), represented as a UTF-8 text string (major type 3). The second element is an arbitrary UTF-8 text string (major type 3). Both the language tag and the arbitrary string can optionally be annotated with CBOR tags; this is not shown in the CDDL below. The optional third element, if present, is a Boolean value that indicates a direction: false for "ltr" direction, true for "rtl" direction. If the third element is absent, no indication is made about the direction; it can be explicitly given as null to express the same while overriding any context that might be considered applying to this element. Note that the proper processing of Language and Direction Metadata is an active area of investigation; the reader is advised to consult ongoing standardization activities such as when processing the information represented in this tag. In CDDL: NOTE: Language tags of any combination of case are allowed. But section 2.1.1 of , part of Best Current Practice 47, recommends a case combination for language tags, that encoders that support tag 38 may wish to follow when generating language tags. Data items with tag 38 that do not meet the criteria above are invalid (see ). NOTE: The Unicode Standard includes a set of characters designed for tagging text (including language tagging), in the range U+E0000 to U+E007F. Although many applications, including RDF, do not disallow these characters in text strings, the Unicode Consortium has deprecated these characters and recommends annotating language via a higher-level protocol instead. See the section "Deprecated Tag Characters" in Section 23.9 of .
Examples Examples in this section are given in CBOR diagnostic notation first and then as a pretty-printed hexadecimal representation of the encoded item. The following example shows how the English-language string "Hello" is represented. The following example shows how the French-language string "Bonjour" is represented. The following example shows how the Hebrew-language string שלום is represented. Note the rtl direction expressed by setting the third element in the array to "true".
Interworking with RFC 7807 On certain occasions, it will be necessary to carry ("tunnel") problem details in a Concise Problem Details data item. This appendix defines a Custom Problem Details entry for that purpose. This is assigned Custom Problem Detail key 7807 in . Its structure is: ~uri ? &(status: 1) => 0..999 * text => any } ]]> To carry an problem details JSON object in a Concise Problem Details data item, first convert the JSON object to CBOR as per . Create an empty Concise Problem Details data item. Move the values for "title", "detail", and "instance", if present, from the problem details to the equivalent Standard Problem Detail entries. Create a Custom Problem Details entry with key 7807. Move the values for "type" and "status", if present, to the equivalent keys 0 and 1 of the Custom Problem Details entry. Move all remaining key/value pairs (additional members as per ) in the converted problem details object to the Custom Problem Details map unchanged. The inverse direction, carrying Concise Problem Details in a Problem Details JSON object requires the additional support provided by , which is planned to create the HTTP Problem Types Registry. An HTTP Problem Type can then be registered that extracts top-level items from the Concise Problem Details data item in a similar way to the conversion described above, and which carries the rest of the Concise Problem Details data item in an additional member via base64url encoding without padding (). Details can be defined in a separate document when the work on is completed.
Acknowledgments and , authors of RFC 7807. and , co-authors of an earlier generation of this specification. , , and for review and comments on this document. For , John Cowan and Doug Ewell are also to be acknowledged. The content of an earlier version of this appendix was also discussed in the "apps-discuss at ietf.org" and "ltru at ietf.org" mailing lists. More recently, the authors initiated a discussion about the handling of writing direction information in conjunction with language tags. That led to discussions within the W3C Internationalization Core Working Group. The authors would like to acknowledge that cross-organization cooperation and particular contributions from John Klensin and Addison Phillips.
Contributors
poccil14 at gmail dot com http://peteroupc.github.io/CBOR/
Peter defined CBOR tag 38, basis of .