Problem Details For CoAP APIsARMthomas.fossati@arm.comEricssonjaime@iki.fi
ART
CoRE Working GroupCoAP, API, Problem DetailsThis document defines a “problem detail” as a way to carry machine-readable
details of errors in a CoAP response to avoid the need to define new error
response formats for CoAP APIs.CoAP response codes are sometimes not sufficient to convey enough
information about an error to be helpful.This specification defines a simple and extensible CBOR format to
suit this purpose. It is designed to be reused by CoAP 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
format).The format presented is largely inspired by the Problem Details for HTTP APIs
defined in .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.A CoAP Problem Details is encoded as a CBOR map with the following members:“ns” (int) - A code-point that defines the namespace under which the “type”
field needs to be interpreted. This is a mandatory field.“type” (uint) - A code-point that identifies the problem type within the
namespace. This is a mandatory field.“title” (text) - A short, human-readable summary of the problem type. It
SHOULD NOT change from occurrence to occurrence of the problem.“response-code” (8-bit uint) - The CoAP response code (, Section
5.9) generated by the origin server for this occurrence of the problem.“detail” (text) - A human-readable explanation specific to this occurrence of
the problem.“instance” (uri) - A URI reference that identifies the specific occurrence of
the problem. It may or may not yield further information if dereferenced.Consumers MUST use “ns” and “type” 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 “ns” and “type” values.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 in the actual CoAP response, to assure that generic CoAP
software that does not understand this 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 payloads persist without
CoAP information (e.g., in an events log or analytics database). Generic CoAP
software will still use the CoAP response code.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 “instance” accepts relative URIs; this means that it must be resolved
relative to the document’s base URI, as per , Section 5.The definition in CDDL format of a Problem Details for CoAP is
provided in .The format presented can be extended at two separate points that allow the
definition of:New problem type values (see ); andNew problem attributes (see ).The mechanism for defining new problem types is designed to allow private use,
for example by organisations or projects, while at the same time supporting the
use of this error format in public protocols and APIs, as well as ease of
transition between the two – for example if an API is first developed
internally to an organisation and then open-sourced. Another critical design
objective is to enable delegating the administration of the code-points space
to entities (and experts) that are “closer” to the actual usage and intended
meaning of the code-points. In fact, an explicit desiderata is to avoid having
experts looking over a very big and diverse semantic space.To meet these goal, new problem types are always defined (and have a meaning)
within a namespace. The namespace range is itself partitioned in three
separate sub-ranges: a completely private space, one devoted to private
organisations and projects, and a third one used for public APIs and protocols.
The rules for registering a new namespace are outlined in
.The registration procedures for new problem types are not defined in this
document. At a minimum, though, new problem type definitions SHOULD document:A parent namespace;Their own code-point;A title that appropriately describes the problem type (think short); andThe CoAP response-code for it to be used with.A problem type definition may specify additional attributes on the
problem details map (see ).(Note on renumbering: moving a set of error types from the private to the
public space needs only changing the namespace identifier while leaving all
error types the same.)Problem type definitions MAY extend the problem details object with additional
attributes to convey additional, problem-specific information.Clients consuming problem details MUST ignore any such extensions that they do
not recognize; this allows problem types to evolve and include additional
information in the future.CoAP Problem Details can be extended via the coap-problem-details-extension
CDDL socket (see Section 3.9 of ).The security and privacy considerations outlined in Section 5 of
apply in full.This document requests that IANA registers the following Content-Format to the
“CoAP Content-Formats” sub-registry, within the “Constrained RESTful
Environments (CoRE) Parameters” registry, from the Expert Review space
(0..255):Media TypeEncodingIDReferenceapplication/coap-problem+cbor—TBD1RFCthisThis document requests that IANA create the following new registries:CoAP Problem Namespaces ();CoAP Problem Details ().The “CoAP Problem Details” registry keeps track of the allocation of the
integer values used as index values in the coap-problem-details CBOR map.Future registrations for this registry are to be made based on as
described in .RangeRegistration Procedures0…NStandards ActionN+1…4294967295Specification RequiredAll negative values are reserved for Private Use.Initial registrations for the “CoAP Problem Details” registry are provided in
. Assignments consist of an integer index value, the item
name, and a reference to the defining specification.IndexIndex NameSpecification0nsRFCthis1typeRFCthis2titleRFCthis3response-codeRFCthis4detailRFCthis5instanceRFCthisThe “CoAP Problem Namespace” registry keeps track of the problem namespace
values.Future registrations for this registry are to be made based on as
described in .RangeRegistration Procedures-L…-1First Come First Served0…MStandards ActionM+1…4294967295Specification RequiredAll negative values less than L are reserved for Private Use.The “CoAP Problem Namespace” registry has three columns as shown in
. Assignments consist of an integer index value, the item
description, and a reference to the defining specification.ValueDescriptionSpecificationemptyemptyemptyThe registry is initially empty.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.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.Key words for use in RFCs to Indicate Requirement LevelsIn 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 WordsRFC 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.Uniform Resource Identifier (URI): Generic SyntaxA 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]Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data StructuresThis 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.Guidelines for Writing an IANA Considerations Section in RFCsMany 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.Problem Details for HTTP APIsThis 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.The Constrained RESTful Application Language (CoRAL)The Constrained RESTful Application Language (CoRAL) defines a data model and interaction model as well as two specialized serialization formats for the description of typed connections between resources on the Web ("links"), possible operations on such resources ("forms"), and simple resource metadata.Constrained Resource IdentifiersConstrained Resource Identifiers (CoRIs) are an alternate serialization of Uniform Resource Identifiers (URIs) that encodes the URI components in Concise Binary Object Representation (CBOR) instead of a string of characters. This simplifies parsing, reference resolution, and comparison of URIs in environments with severe limitations on processing power, code size, and memory size.This section presents a series of examples in CBOR diagnostic notation
. The examples are fictitious. No identification with actual
products is intended or should be inferred. All examples involve the same CoAP
problem type (5, with pretend semantics “unknown key id”) defined in the
private namespace “-33455”.The example in has the most compact representation.
By avoiding any non-mandatory field, the Problem encodes to seven bytes in
total. This is suitable for a constrained receiver that happens to have
precise knowledge of the semantics associated with the namespace and type
code-points.The example in has all the mandatory as well as the
optional fields populated. This format is appropriate for an unconstrained
receiver. For example, an edge gateway forwarding to a log server that needs
to gather as much contextual information as possible, including details about
the error condition, the associated CoAP response code, and even the URL
describing the specific error instance.The last example () makes use of the built-in
extension mechanism described in to provide some context
specific information - in this made up scenario a list of possible key ids is
provided to the receiving end. This richer format might be enabled for debug
or tracing purposes, possibly on a per-transaction basis. Note that the map
index for key-ids key is minted from the private (negative) space.CoRAL provides a way to address the same problem that
is solved by the format described in this document. (Refer to section 5.2.3 of
for initial discussion around CoRAL Error Responses.)By abstracting the serialization aspects (CBOR, JSON, etc.), the transport
protocol (HTTP, CoAP, etc.) and its response codes, while also providing
compression of the involved resources, CoRAL can potentially support a more
general solution than the one discussed here, in particular one that also
supersedes .In this section, the examples from are converted to CoRAL.The main differences are:CoRAL is using an array of alternating keys and values instead of a map with
array values to get a multi-dict;CoRAL uses as an alternative to URIs that is
optimized for constrained nodes;CoRAL uses its own code-point allocation scheme.Klaus Hartke provided the text in .Mark Nottingham and Erik Wilde, authors of RFC 7807. Carsten Bormann and Klaus
Hartke for discussion on the problem space and extensibility requirements.