Draft: draft-ietf-core-problem-details

Commentary: described in the former    LGTM !
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.
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.
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.  The proposed format
is inspired by the Problem Details for HTTP APIs defined in RFC 7807.
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 CoRAL I-D.ietf-core-coral vocabulary
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 vocabulary), as shown in fig-problem-details.
The vocabulary presented is largely inspired by the Problem Details
for HTTP APIs defined in RFC7807.
"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.
"response-code" (8-bit uint) - The CoAP response code (RFC7252,
Section 5.9) generated by the origin server for this occurrence of
the problem.
"type" (id) - The problem type.  This is a mandatory element.
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.
Consumers MUST use "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 "type" value.
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 fig-cddl.
New problem attributes (see sec-new-attributes).
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 iana-namespace-registry.
The CoAP response-code for it to be used with.
A problem type definition may specify additional attributes on the
problem details map (see sec-new-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 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).
CoAP Problem Details (iana-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 tab-details.
All negative values are reserved for Private Use.
Initial registrations for the "CoAP Problem Details" registry are
provided in tab-details-init.  Assignments consist of an integer
index value, the item name, and a reference to the defining
specification.
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 tab-types.
All negative values less than L are reserved for Private Use.
The "CoAP Problem Namespace" registry has three columns as shown in
tab-ns-fmt.  Assignments consist of an integer index value, the item
description, and a reference to the defining specification.
Note that the "instance" URI reference may be relative; this means
that it must be resolved relative to the document's base URI, as per
I-D.ietf-core-coral.
This section presents a series of examples of the basic vocabulary in
CoRAL textual format (Section 4 of I-D.ietf-core-coral).  The
examples are fictitious.  No identification with actual products is
intended or should be inferred.  All examples involve the same CoAP
problem type with semantics of "unknown key id", defined in the
fictitious namespace "http://vocabulary.private-api.example".
Note that CoRAL documents are exchanged in CoRAL binary format
(Section 3 of I-D.ietf-core-coral) in practice.  This includes the
use of I-D.ietf-core-href as an alternative to URIs that is optimized
for constrained nodes.
The example in fig-example-minimalist has the most compact
representation.  It avoids any non-mandatory element.  This is
suitable for a constrained receiver that happens to have precise
knowledge of the semantics associated with the "type".
The example in fig-example-full-fledged has all the mandatory as well
as the optional elements populated.  This format is appropriate for a
less constrained receiver (for example, an edge gateway forwarding to
a log server that needs to gather as much contextual information as
possible, including the problem "headline", details about the error
condition, and an error-specific instance URL).
Problem type definitions MAY extend the Problem Details document with
additional elements to convey additional, problem-specific
information.
Clients consuming problem details MUST ignore any such elements that
they do not recognize; this allows problem types to evolve and
include additional information in the future.
The example in fig-example-ext-full has all the basic elements as
well as an additional, type-specific element.
Problem Details for CoAP APIs are serialized in the CoRAL binary
format.  See Section 11 of RFC7252 for security considerations
relating to CoAP.  See Section 7 of I-D.ietf-core-coral for security
considerations relating to CoRAL.