Internet-Draft CoAP Problem November 2019
Fossati Expires 23 May 2020 [Page]
Workgroup:
CoRE Working Group
Internet-Draft:
draft-fossati-core-coap-problem-00
Published:
Intended Status:
Standards Track
Expires:
Author:
T. Fossati
ARM

Problem Details For CoAP APIs

Abstract

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.

Status of This Memo

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 23 May 2020.

Table of Contents

1. Introduction

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

1.1. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. CoAP Problem Details Definition

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

2.1. CDDL

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
Figure 1: CoAP Problem Details: CDDL Definition

3. Extensibility

The format presented can be extended at two separate points that allow the definition of:

3.1. Defining New Problem Types

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:

  1. A parent namespace;
  2. Their own code-point;
  3. A title that appropriately describes the problem type (think short); and
  4. The CoAP response-code for it to be used with.

A problem type definition may specify additional attributes on the problem details map (see Section 3.2).

(Note: 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.)

3.2. Defining New Problem Attributes

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 don't 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]).

4. Security Considerations

The security and privacy considerations outlined in Section 5 of [RFC7807] apply in full.

5. IANA Considerations

5.1. Registration of a Content-Format identifier for application/coap-problem+cbor

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):

Table 1
Media Type Encoding ID Reference
application/coap-problem+cbor -- TBD1 RFCthis

5.2. New Registries

This document requests that IANA create the following new registries:

5.2.1. CoAP Problem Details Registry

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.

Table 2: CoAP Problem Details Registration Procedures
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.

Table 3: CoAP Problem Details Initial Registrations
Index Index Name Specification
0 ns RFCthis
1 type RFCthis
2 title RFCthis
3 response-code RFCthis
4 detail RFCthis
5 instance RFCthis

5.2.2. CoAP Problem Namespace Registry

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.

Table 4: CoAP Problem Types Registration Procedures
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 initial registration for the "CoAP Problem Namespace" registry is provided in Table 5. Assignments consist of an integer index value, the item name, and a reference to the defining specification.

Table 5: CoAP Problem Namespace Initial Registrations
Value Description Specification
0 The "global" namespace RFCthis

6. References

6.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/info/rfc3986>.
[RFC7049]
Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, , <https://www.rfc-editor.org/info/rfc7049>.
[RFC7252]
Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, , <https://www.rfc-editor.org/info/rfc7252>.
[RFC8126]
Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, , <https://www.rfc-editor.org/info/rfc8126>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8610]
Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, , <https://www.rfc-editor.org/info/rfc8610>.

6.2. Informative References

[RFC7807]
Nottingham, M. and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, , <https://www.rfc-editor.org/info/rfc7807>.

Acknowledgments

Mark Nottingham and Erik Wilde, authors of RFC 7807. Carsten Bormann and Klaus Hartke for discussion on the problem space and extensibility requirements.

Author's Address

Thomas Fossati
ARM