[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00

CoRE Working Group                                            T. Fossati
Internet-Draft                                                       ARM
Intended status: Standards Track                        20 November 2019
Expires: 23 May 2020


                     Problem Details For CoAP APIs
                   draft-fossati-core-coap-problem-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 23 May 2020.

Copyright Notice

   Copyright (c) 2019 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                    Expires 23 May 2020                  [Page 1]


Internet-Draft                CoAP Problem                 November 2019


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Requirements Language . . . . . . . . . . . . . . . . . .   2
   2.  CoAP Problem Details Definition . . . . . . . . . . . . . . .   3
     2.1.  CDDL  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  Extensibility . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.1.  Defining New Problem Types  . . . . . . . . . . . . . . .   4
     3.2.  Defining New Problem Attributes . . . . . . . . . . . . .   5
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   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
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

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.





Fossati                    Expires 23 May 2020                  [Page 2]


Internet-Draft                CoAP Problem                 November 2019


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



Fossati                    Expires 23 May 2020                  [Page 3]


Internet-Draft                CoAP Problem                 November 2019


   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 error type values (see Section 3.1); and

   *  New error attributes (see Section 3.2).

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



Fossati                    Expires 23 May 2020                  [Page 4]


Internet-Draft                CoAP Problem                 November 2019


   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.




Fossati                    Expires 23 May 2020                  [Page 5]


Internet-Draft                CoAP Problem                 November 2019


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.

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




Fossati                    Expires 23 May 2020                  [Page 6]


Internet-Draft                CoAP Problem                 November 2019


   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.

              +------------------+-------------------------+
              | 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 initial registration for the "CoAP Problem Namespace" registry is




Fossati                    Expires 23 May 2020                  [Page 7]


Internet-Draft                CoAP Problem                 November 2019


   provided in Table 5.  Assignments consist of an integer index value,
   the item name, and a reference to the defining specification.

            +-------+------------------------+---------------+
            | Value | Description            | Specification |
            +=======+========================+===============+
            | 0     | The "global" namespace | RFCthis       |
            +-------+------------------------+---------------+

                 Table 5: CoAP Problem Namespace Initial
                              Registrations

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

   [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




Fossati                    Expires 23 May 2020                  [Page 8]


Internet-Draft                CoAP Problem                 November 2019


              JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
              June 2019, <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, March 2016,
              <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

   Email: thomas.fossati@arm.com






























Fossati                    Expires 23 May 2020                  [Page 9]


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