[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-fossati-core-coap-problem) 00 01

CoRE Working Group                                            T. Fossati
Internet-Draft                                                       arm
Intended status: Standards Track                              J. Jimenez
Expires: November 14, 2020                                     K. Hartke
                                                                Ericsson
                                                            May 13, 2020


                     Problem Details For CoAP APIs
                  draft-ietf-core-problem-details-00

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 November 14, 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, et al.         Expires November 14, 2020               [Page 1]


Internet-Draft            CoRE Problem Details                  May 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  . . . . . . . . . . . . . . . . . . . . . . .   9
     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  . . . . . . . . . . . . . . . . . . . .  12
       B.1.3.  Full-Fledged with Extensions  . . . . . . . . . . . .  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, et al.         Expires November 14, 2020               [Page 2]


Internet-Draft            CoRE Problem Details                  May 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:

   o  "ns" (int) - A code-point that defines the namespace under which
      the "type" field needs to be interpreted.  This is a mandatory
      field.

   o  "type" (uint) - A code-point that identifies the problem type
      within the namespace.  This is a mandatory field.

   o  "title" (text) - A short, human-readable summary of the problem
      type.  It SHOULD NOT change from occurrence to occurrence of the
      problem.

   o  "response-code" (8-bit uint) - The CoAP response code ([RFC7252],
      Section 5.9) generated by the origin server for this occurrence of
      the problem.

   o  "detail" (text) - A human-readable explanation specific to this
      occurrence of the problem.

   o  "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, et al.         Expires November 14, 2020               [Page 3]


Internet-Draft            CoRE Problem Details                  May 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:

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

   o  New problem attributes (see Section 3.2).





Fossati, et al.         Expires November 14, 2020               [Page 4]


Internet-Draft            CoRE Problem Details                  May 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, et al.         Expires November 14, 2020               [Page 5]


Internet-Draft            CoRE Problem Details                  May 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   |
      +-------------------------------+----------+------+-----------+

5.2.  New Registries

   This document requests that IANA create the following new registries:

   o  CoAP Problem Namespaces (Section 5.2.2);

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







Fossati, et al.         Expires November 14, 2020               [Page 6]


Internet-Draft            CoRE Problem Details                  May 2020


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

           Table 1: 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 2.  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 2: 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 3.










Fossati, et al.         Expires November 14, 2020               [Page 7]


Internet-Draft            CoRE Problem Details                  May 2020


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

            Table 3: 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 4.  Assignments consist of an integer index value, the item
   description, and a reference to the defining specification.

                  +-------+-------------+---------------+
                  | Value | Description | Specification |
                  +-------+-------------+---------------+
                  | empty | empty       | empty         |
                  +-------+-------------+---------------+

                 Table 4: 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, et al.         Expires November 14, 2020               [Page 8]


Internet-Draft            CoRE Problem Details                  May 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)", draft-ietf-core-coral-03 (work in progress),
              March 2020.

   [I-D.ietf-core-href]
              Hartke, K., "Constrained Resource Identifiers", draft-
              ietf-core-href-03 (work in progress), March 2020.

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

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



Fossati, et al.         Expires November 14, 2020               [Page 9]


Internet-Draft            CoRE Problem Details                  May 2020


   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, et al.         Expires November 14, 2020              [Page 10]


Internet-Draft            CoRE Problem Details                  May 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:

   o  CoRAL is using an array of alternating keys and values instead of
      a map with array values to get a multi-dict;

   o  CoRAL uses [I-D.ietf-core-href] as an alternative to URIs that is
      optimized for constrained nodes;

   o  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






Fossati, et al.         Expires November 14, 2020              [Page 11]


Internet-Draft            CoRE Problem Details                  May 2020


B.1.2.  Full-Fledged

   #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

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 Jimenez
   Ericsson

   Email: jaime@iki.fi








Fossati, et al.         Expires November 14, 2020              [Page 12]


Internet-Draft            CoRE Problem Details                  May 2020


   Klaus Hartke
   Ericsson

   Email: klaus.hartke@ericsson.com















































Fossati, et al.         Expires November 14, 2020              [Page 13]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/