]> 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 "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. The format is inspired by, but intended to be more concise than, the Problem Details for HTTP APIs defined in RFC 7807.

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 tags to suit this purpose. It is designed to be reused by REST APIs, which can identify distinct "problem types" 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 this vocabulary), as shown in .

Problem Details: Example with CoAP | | | | <----------------- | | 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 .

Requirements Language 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 (notated in CDDL , using 65535 in place of a tag number to be defined for the type of problem details):

Problem Detail Data Item text ? &(detail: -2) => text ? &(instance: -3) => ~uri standard-problem-detail-entries custom-problem-detail-entries }> standard-problem-detail-entries = ( * nint => any ) custom-problem-detail-entries = ( * (uint/detail-label) => any ) detail-label = text .regexp "[^:]+" / ~uri non-empty = (M) .and ({ + any => any }) ]]>

Due to a limitation of the CDDL notation for tags, the problem type cannot be expressed under this name in CDDL. It is represented in the tag number, which is shown here as 65535. One tag has been registered as a generic problem type by this specification (see ). Further problem types can be defined by registering additional tags (see ). A number of problem detail entries, the Standard Problem Detail entries, are predefined (more predefined details can be registered, see ):

The title (key -1):

A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem.

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.

Consumers MUST use the type (tag number) as primary identifiers for the problem type; the "title" string is advisory and included only for consumers who are not aware of the semantics of the CBOR tag number used to indicate the specific problem type. 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 document's base URI, as per . Note that the response code information that may be available together with a problem report is not replicated into a problem detail entry; compare this with "status" in .

Additional Problem Details This specification defines a single problem type, the Generic Problem Details problem type (represented by CBOR tag TBD400, ).

Additional Problem Types To establish a new problem type, different from the Generic Problem Details problem type, a CBOR Tag number needs to be registered in the of . Note that this registry allows the registration of new tags under the First Come First Served policy , making new registrations available in a simple interaction (e.g., via web or email) with IANA, after having filled in the small template provided in . Such a registration SHOULD provide a documentation reference and also SHOULD reference the present specification.

Custom Problem Detail Entries Problem type definitions MAY extend the Problem Details document with additional entries to convey additional, problem-type-specific information, custom problem details. In the definition of a problem type, each custom problem detail receives a map key specific to this problem type (custom problem detail entry map key, unsigned integer or text); this SHOULD be described in the documentation that goes along with the registration of a CBOR Tag for the problem type. For text detail-labels, a name without an embedded colon can be chosen instead of an integer custom label, or a detail-label that is a URI. This URI is for identification purposes only and MUST NOT be dereferenced in the normal course of handling problem details (i.e., outside diagnostic/debugging procedures involving humans). In summary, the keys for Custom Problem Detail entries are in a namespace specific to the Problem Type the documentation of which defines these entries. Consumers of a Problem Type instance MUST ignore any Custom Problem Detail entries that they do not recognize; this allows problem types to evolve and include additional information in the future. If, in the evolution of a problem type, a new problem detail is added that needs to be understood by all consumers, a new problem type needs to be defined (i.e., problem detail entries are always elective, never critical, in the terminology of ).

Standard Problem Detail Entries Beyond the Standard Problem Detail keys defined in , additional Standard Problem Detail keys can be registered (see ). Standard Problem Detail keys are not specific to a particular problem type; they are intended to be used for problem details that cover an area of application that includes multiple registered problem types. Standard Problem Detail keys are negative integers, so they never can conflict with Custom Problem Detail keys defined for a problem type (which are unsigned integers or text strings). In summary, the keys for Standard Problem Detail entries are in a global namespace that applies to all Problem Types. The documentation of a Problem Type MAY provide additional guidance on how a Standard Problem Detail entry applies to this Problem Type, but cannot redefine its generic semantics. Therefore, clients consuming problem details may be able to consume unknown Problem types (i.e., with unknown CBOR Tag numbers), if the general context (e.g., a media type known from the context such as that defined in ) indicates that the present specification is used. Such consumers MUST ignore any Standard Problem Detail entries that they do not recognize (which, for an unknown tag, by definition also applies to all Custom Problem Details entries).

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.

CBOR Tag As per , IANA has created a "" registry , which serves as the registry for problem details types (see ). For use as a predefined, generic problem details type, IANA is requested to allocate the tag defined in . Generic Problem Details tag

Tag	Data Item	Semantics	Reference
TBD400	map	Generic Problem Details	RFCXXXX

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

type:

type of the data associated with the key; preferably in CDDL notation

brief description:

a brief description

reference:

a reference document

Initial entries in this sub-registry are as follows: Initial Entries in Standard Problem Detail Key registry

Key value	Name	Type	Brief Description	Reference
-1	title	text	short, human-readable summary of the problem type	RFCXXXX
-2	detail	text	human-readable explanation specific to this occurrence of the problem	RFCXXXX
-3	instance	~uri	URI reference identifying specific occurrence of the problem	RFCXXXX

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	RFCXXXX,

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".

Normative References 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. 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) 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. 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. 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. 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. 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. IANA 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. IANA IANA

Acknowledgments and , authors of RFC 7807. and , co-authors of an earlier generation of this specification. and for review and comments on this document.