Draft: draft-ietf-core-problem-details

Commentary: This PR provides the write - up of the discussed at the interim . Note that it branches off  's " bundled " PR ( ) 
 I did a little bit of editing . Comments welcome ...
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.
This document defines a "problem detail" as a way to carry machine-
readable details of errors in a REST response to avoid the need to
define new error response formats for REST APIs.  The format is
inspired by, but intended to be more concise than, the Problem
Details for HTTP APIs defined in RFC 7807.
REST response status information such as CoAP response codes
(RFC7252) is sometimes not sufficient to convey enough information
about an error to be helpful.  This specification defines a simple
and extensible framework to define CBOR STD94 data items to suit this
purpose.  It is designed to be reused by REST 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 framework presented is largely inspired by the Problem Details
for HTTP APIs defined in RFC7807.  comp7807 discusses applications
where interworking with RFC7807 is required.
"type" (id) - The problem type.  This is a mandatory element.
"title" (text) - A short, human-readable summary of the problem
type.  It SHOULD NOT change from occurrence to 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 "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.  An initial
set of "type"s and corresponding "title"s is defined in sec-response-
code-types.
Note that, unlike RFC7807, Concise Problem Details data items have no
explicit type.
Both "title" and "detail" can use either an unadorned CBOR text
string ("text") or a language-tagged text string ("tag38"); see tag38
for the definition of the latter.
The "title" string is advisory and included to give consumers a
shorthand for the category of the error encountered.
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).
This document defines an initial set of Problem Detail types that
match the corresponding CoAP response codes in the 4.xx (client
error) and 5.xx (server error) space.  See tbl-response-code-types.
When using one such problem type, an application MUST make sure that
the type matches the CoAP response code in the underlying CoAP
transaction.
If a title element is used in the Problem Details payload, it SHOULD
be populated with the title corresponding to the type.
The types defined in this document reflect the state of the relevant
portion of the "CoAP Codes" registry at the time of writing.
In the following sections we introduce specific (albeit "common
enough") use cases, and define the extensions to the basic format
needed to support them.
Consumers of Problem Details might be located at the far end of a
logging and analytics pipeline.  For example, this might be the case
when a CoAP server or CoAP API gateway is located in an edge gateway
node and forwards its logs to a cloud collector, which in turn
aggregates a potentially huge number of different servers and
transactions (see fig-log-pipeline).
It is quite common in a situation like the above that an already
deployed server is temporarily put in "tracing mode" to diagnose a
failure.  In this case having a separate channel for the tracing info
provides a superior solution (in terms of ease of ingesting and
processing) to overloading the "detail" field and having to write ad-
hoc filtering logics to extract the relevant information from it.
Cost-wise, the producer would not incur any added overhead while,
from the transport perspective, the slight increase in bandwidth to
support the extra structuring is typically dwarfed by the (verbose)
content of the diagnostic payload.  The same mechanism would also be
useful during the development and test of a new application, giving
the developer insight into the internal state of the application.
"diag" (text) - a string.  It may contain anything of user's
choice: extra information complementing the what already present
in "detail", a stack trace, a distributed trace span ending in an
error condition, etc.
Leaking private or sensitive data SHOULD be avoided.
The example in fig-example-diag-stack has a "diag" element with a
stack trace associated with the error condition.
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.
Note that the "instance" URI reference may be relative; this means
that it must be resolved relative to the representation's base URI,
as per STD66.
Note that the "response code" value is a numeric representation of
the actual code, so it does not take the usual form that resembles an
HTTP status code -- "4.04 Not found" is represented by the number
132.
This specification defines a generic problem type container with only
a minimal set of attributes to make it usable.
It is expected that applications will extend the base format by
defining new attributes.
These new attributes fall into two categories: generic and
application specific.
Generic attributes will be allocated in the "standard-problem-detail-
entries" slot according to the registration procedure defined in new-
spdk.
Application-specific attributes will be allocated in the "custom-
problem-detail-entries" slot according to the procedure described in
new-cpdk.
Beyond the Standard Problem Detail keys defined in cddl, additional
Standard Problem Detail keys can be registered for use in the
"standard-problem-detail-entries" slot (see iana-spdk).
In summary, the keys for Standard Problem Detail entries are in a
global namespace that is not specific to a particular application
domain.
Consumers of a Concise Problem Details instance MUST ignore any
Standard Problem Detail entries that they do not recognize; this
allows problem details to evolve.
Applications may extend the Problem Details data item with additional
entries to convey additional, application-specific information.
Such new entries are allocated in the "custom-problem-detail-entries"
slot, and carry a nested map specific to that application.  The map
key can either be an (absolute!)  URI (controlled by the entity
defining this extension), or an unsigned integer.  Only the latter
needs to be registered (iana-cpdk).
Within the nested map any number of attributes can be given for a
single extension.  The semantics of each custom attribute MUST be
described in the documentation for the extension; for extension that
are registered (i.e., are identified by an unsigned int) that
documentation goes along with the registration.
Note that the URI given for the extension is for identification
purposes only and, even if dereferenceable in principle, MUST NOT be
dereferenced in the normal course of handling problem details (i.e.,
outside diagnostic/debugging procedures involving humans).
An example of a custom extension using a URI as "custom-problem-
detail-entries" key is shown in fig-example-custom-with-uri.
Obviously, an SDO like 3GPP can also easily register such a custom
problem detail entry to receive a more efficient unsigned integer
key; the same example but using a registered unsigned int as "custom-
problem-detail-entries" key is shown in fig-example-custom-with-uint.
In summary, the keys for the maps used inside Custom Problem Detail
entries are defined specifically to the identifier of that Custom
Problem Detail entry, the documentation of which defines these
internal entries, typically chosen to address a given application
domain.  Consumers of a Concise Problem Details instance MUST ignore
any Custom Problem Detail entries, or keys inside the Custom Problem
Detail entries, that they do not recognize; this allows Custom
Problem Detail entries to evolve and include additional information
in the future.
This specification defines a new sub-registry for Standard Problem
Detail Keys in the CoRE Parameters registry IANA.core-parameters,
with the policy "specification required" RFC8126.
This specification defines a new sub-registry for Custom Problem
Detail Keys in the CoRE Parameters registry IANA.core-parameters,
with the policy "first come first served" RFC8126.
IANA is requested to add the following Media-Type to the "Media
Types" registry IANA.media-types.
TBD1 is to be assigned from the space 256..999.
In the registry as defined by RFC7252 at the time of writing, the
column "Content-Type" is called "Media type" and the column "Content
Coding" is called "Encoding".