| Internet-Draft | CoAP Problem | March 2020 |
| Fossati & Jiménez | Expires 6 September 2020 | [Page] |
This 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.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 6 September 2020.¶
Copyright (c) 2020 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
CoAP [RFC7252] response codes are sometimes not sufficient to convey enough information about an error to be helpful.¶
This specification defines a simple and extensible CBOR [RFC7049] 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 [RFC7807].¶
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 [RFC2119] [RFC8174] 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:¶
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 Section 3.2) 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 [RFC3986], Section 5.¶
The definition in CDDL format [RFC8610] of a Problem Details for CoAP is provided in Figure 1.¶
coap-problem-details = {
ns => int,
type => uint,
? title => text,
? response-code => uint .size 1,
? detail => text,
? instance => uri,
* $$coap-problem-details-extension,
}
ns = 0
type = 1
title = 2
response-code = 3
detail = 4
instance = 5
The format presented can be extended at two separate points that allow the definition of:¶
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 Section 5.2.2.¶
The registration procedures for new problem types are not defined in this document. At a minimum, though, new problem type definitions SHOULD document:¶
A problem type definition may specify additional attributes on the problem details map (see Section 3.2).¶
(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 [RFC8610]).¶
The security and privacy considerations outlined in Section 5 of [RFC7807] 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 Type | Encoding | ID | Reference |
|---|---|---|---|
| application/coap-problem+cbor | -- | TBD1 | RFCthis |
This document requests that IANA create the following new registries:¶
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 [RFC8126] as described in Table 2.¶
| Range | Registration Procedures |
|---|---|
| 0...N | Standards Action |
| N+1...4294967295 | Specification Required |
All negative values are reserved for Private Use.¶
Initial registrations for the "CoAP Problem Details" registry are provided in Table 3. Assignments consist of an integer index value, the item name, and a reference to the defining specification.¶
| Index | Index Name | Specification |
|---|---|---|
| 0 | ns | RFCthis |
| 1 | type | RFCthis |
| 2 | title | RFCthis |
| 3 | response-code | RFCthis |
| 4 | detail | RFCthis |
| 5 | instance | RFCthis |
The "CoAP Problem Namespace" registry keeps track of the problem namespace values.¶
Future registrations for this registry are to be made based on [RFC8126] as described in Table 4.¶
| Range | Registration Procedures |
|---|---|
| -L...-1 | First Come First Served |
| 0...M | Standards Action |
| M+1...4294967295 | Specification Required |
All negative values less than L are reserved for Private Use.¶
The "CoAP Problem Namespace" registry has three columns as shown in Table 5. Assignments consist of an integer index value, the item description, and a reference to the defining specification.¶
| Value | Description | Specification |
|---|---|---|
| empty | empty | empty |
The registry is initially empty.¶
This section presents a series of examples in CBOR diagnostic notation [RFC7049]. 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 Figure 2 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.¶
{
/ ns / 0: -33455, / a private namespace /
/ type / 1: 5 / "unknown key id" semantics /
}
The example in Figure 3 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.¶
{
/ ns / 0: -33455,
/ type / 1: 5,
/ title / 2: "unknown key id",
/ response-code / 3: 132, / 4.04 Not Found /
/ detail / 4: "Key with id 0x01020304 not registered",
/ instance / 5: 32("https://private-api.example/errors/5")
}
The last example (Figure 4) makes use of the built-in extension mechanism described in Section 3.2 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.¶
{
/ ns / 0: -33455,
/ type / 1: 5,
/ title / 2: "unknown key id",
/ response-code / 3: 132, / 4.04 Not Found /
/ detail / 4: "Key with id 0x01020304 not registered",
/ instance / 5: 32("https://private-api.example/errors/5"),
/ key-ids / -1: [ 0x01020300, 0x01020301, 0x01020302 ]
}
CoRAL [I-D.ietf-core-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 [I-D.ietf-core-coral] 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 [RFC7807].¶
In this section, the examples from Appendix A are converted to CoRAL.¶
The main differences are:¶
#using <http://example.org/vocabulary/problem-details#> #using ex = <http://vocabulary.private-api.example/#> type ex:unknown-key-id¶
#using <http://example.org/vocabulary/problem-details#> #using ex = <http://vocabulary.private-api.example/#> type ex:unknown-key-id title "unknown key id" response-code 132 detail "Key with id 0x01020304 not registered" instance <https://private-api.example/errors/5>¶
#using <http://example.org/vocabulary/problem-details#> #using ex = <http://vocabulary.private-api.example/#> type 5 title "unknown key id" response-code 132 detail "Key with id 0x01020304 not registered" instance <https://private-api.example/errors/5> ex:key-id 0x01020300 ex:key-id 0x01020301 ex:key-id 0x01020302¶
Klaus Hartke provided the text in Appendix B.1.¶
Mark Nottingham and Erik Wilde, authors of RFC 7807. Carsten Bormann and Klaus Hartke for discussion on the problem space and extensibility requirements.¶