Internet DRAFT - draft-fossati-core-coap-problem

draft-fossati-core-coap-problem







CoRE Working Group                                            T. Fossati
Internet-Draft                                                       ARM
Intended status: Standards Track                              J. Jiménez
Expires: 6 September 2020                                       Ericsson
                                                            5 March 2020


                     Problem Details For CoAP APIs
                   draft-fossati-core-coap-problem-02

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 6 September 2020.

Copyright Notice

   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.





Fossati & Jiménez       Expires 6 September 2020                [Page 1]

Internet-Draft                CoAP Problem                    March 2020


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   3
   2.  CoAP Problem Details Definition . . . . . . . . . . . . . . .   3
     2.1.  CDDL  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  Extensibility . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.1.  Defining New Problem Types  . . . . . . . . . . . . . . .   5
     3.2.  Defining New Problem Attributes . . . . . . . . . . . . .   5
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
     5.1.  Registration of a Content-Format identifier for
           application/coap-problem+cbor . . . . . . . . . . . . . .   6
     5.2.  New Registries  . . . . . . . . . . . . . . . . . . . . .   6
       5.2.1.  CoAP Problem Details Registry . . . . . . . . . . . .   6
       5.2.2.  CoAP Problem Namespace Registry . . . . . . . . . . .   7
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
     6.2.  Informative References  . . . . . . . . . . . . . . . . .   9
   Appendix A.  Examples . . . . . . . . . . . . . . . . . . . . . .   9
     A.1.  Minimalist  . . . . . . . . . . . . . . . . . . . . . . .  10
     A.2.  Full-Fledged  . . . . . . . . . . . . . . . . . . . . . .  10
     A.3.  Full-Fledged with Extensions  . . . . . . . . . . . . . .  10
   Appendix B.  Doing it with CoRAL  . . . . . . . . . . . . . . . .  11
     B.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . . .  11
       B.1.1.  Minimalist  . . . . . . . . . . . . . . . . . . . . .  11
       B.1.2.  Full-Fledged  . . . . . . . . . . . . . . . . . . . .  11
       B.1.3.  Full-Fledged with Extensions  . . . . . . . . . . . .  12
   Contributors  . . . . . . . . . . . . . . . . . . . . . . . . . .  12
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  12
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  12

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



Fossati & Jiménez       Expires 6 September 2020                [Page 2]

Internet-Draft                CoAP Problem                    March 2020


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:

   *  "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 ([RFC7252],
      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



Fossati & Jiménez       Expires 6 September 2020                [Page 3]

Internet-Draft                CoAP Problem                    March 2020


   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.

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:

   *  New problem type values (see Section 3.1); and

   *  New problem attributes (see Section 3.2).





Fossati & Jiménez       Expires 6 September 2020                [Page 4]

Internet-Draft                CoAP Problem                    March 2020


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

3.2.  Defining New Problem Attributes

   Problem type definitions MAY extend the problem details object with
   additional attributes to convey additional, problem-specific
   information.





Fossati & Jiménez       Expires 6 September 2020                [Page 5]

Internet-Draft                CoAP Problem                    March 2020


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

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

      +-------------------------------+----------+------+-----------+
      | Media Type                    | Encoding | ID   | Reference |
      +===============================+==========+======+===========+
      | application/coap-problem+cbor | --       | TBD1 | RFCthis   |
      +-------------------------------+----------+------+-----------+

                                  Table 1

5.2.  New Registries

   This document requests that IANA create the following new registries:

   *  CoAP Problem Namespaces (Section 5.2.2);

   *  CoAP Problem Details (Section 5.2.1).

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.





Fossati & Jiménez       Expires 6 September 2020                [Page 6]

Internet-Draft                CoAP Problem                    March 2020


              +------------------+-------------------------+
              | Range            | Registration Procedures |
              +==================+=========================+
              | 0...N            | Standards Action        |
              +------------------+-------------------------+
              | N+1...4294967295 | Specification Required  |
              +------------------+-------------------------+

                Table 2: CoAP Problem Details Registration
                                Procedures

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

                   Table 3: CoAP Problem Details Initial
                               Registrations

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.








Fossati & Jiménez       Expires 6 September 2020                [Page 7]

Internet-Draft                CoAP Problem                    March 2020


              +------------------+-------------------------+
              | Range            | Registration Procedures |
              +==================+=========================+
              | -L...-1          | First Come First Served |
              +------------------+-------------------------+
              | 0...M            | Standards Action        |
              +------------------+-------------------------+
              | M+1...4294967295 | Specification Required  |
              +------------------+-------------------------+

                 Table 4: CoAP Problem Types Registration
                                Procedures

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

                      Table 5: CoAP Problem Namespace
                                  Registry

   The registry is initially empty.

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, March 1997,
              <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, January 2005,
              <https://www.rfc-editor.org/info/rfc3986>.

   [RFC7049]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
              October 2013, <https://www.rfc-editor.org/info/rfc7049>.




Fossati & Jiménez       Expires 6 September 2020                [Page 8]

Internet-Draft                CoAP Problem                    March 2020


   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <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, June 2017,
              <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,
              May 2017, <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,
              June 2019, <https://www.rfc-editor.org/info/rfc8610>.

6.2.  Informative References

   [I-D.ietf-core-coral]
              Hartke, K., "The Constrained RESTful Application Language
              (CoRAL)", Work in Progress, Internet-Draft, draft-ietf-
              core-coral-02, 8 January 2020, <http://www.ietf.org/
              internet-drafts/draft-ietf-core-coral-02.txt>.

   [I-D.ietf-core-href]
              Hartke, K., "Constrained Resource Identifiers", Work in
              Progress, Internet-Draft, draft-ietf-core-href-02, 8
              January 2020, <http://www.ietf.org/internet-drafts/draft-
              ietf-core-href-02.txt>.

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

Appendix A.  Examples

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






Fossati & Jiménez       Expires 6 September 2020                [Page 9]

Internet-Draft                CoAP Problem                    March 2020


A.1.  Minimalist

   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 /
   }

                Figure 2: Private Namespace: Minimal Payload

A.2.  Full-Fledged

   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")
   }

                 Figure 3: Private Namespace: Full Payload

A.3.  Full-Fledged with Extensions

   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.






Fossati & Jiménez       Expires 6 September 2020               [Page 10]

Internet-Draft                CoAP Problem                    March 2020


   {
       / 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 ]
   }

          Figure 4: Private Namespace: Full Payload and Extension

Appendix B.  Doing it with CoRAL

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

B.1.  Examples

   In this section, the examples from Appendix A 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 [I-D.ietf-core-href] as an alternative to URIs that is
      optimized for constrained nodes;

   *  CoRAL uses its own code-point allocation scheme.

B.1.1.  Minimalist

   #using <http://example.org/vocabulary/problem-details#>
   #using ex = <http://vocabulary.private-api.example/#>

   type            ex:unknown-key-id

B.1.2.  Full-Fledged




Fossati & Jiménez       Expires 6 September 2020               [Page 11]

Internet-Draft                CoAP Problem                    March 2020


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

B.1.3.  Full-Fledged with Extensions

   #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

Contributors

   Klaus Hartke provided the text in Appendix B.1.

Acknowledgments

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

Authors' Addresses

   Thomas Fossati
   ARM

   Email: thomas.fossati@arm.com


   Jaime Jiménez
   Ericsson

   Email: jaime@iki.fi






Fossati & Jiménez       Expires 6 September 2020               [Page 12]