Draft: draft-ietf-core-problem-details

Commentary: Note that this PR sits on top of 
 CoAP Response Codes are an optional feature and should be discussed in a separate section . Rationale for the feature The CoAP response - code is already carried by the CoAP header , so it does n't make sense adding it to the PD payload that goes from Server to Client . It does however make sense for a Client that is about to ingest the received PD into a log pipeline to " enrich " it with ancillary Information from the underlying CoAP transaction . In this context , response - code is probably the most basic attribute that one wants to carry over as it is also commonly used as a high - level partition key for log visualisation . 
 addressed by 
 We should provide a default set of ready - to - use PD types associated with the existing CoAP status codes , intended for carrying ( and enriching ) the associated status code semantics . The ( rough ) plan is to define an “ about : coap ”  with one PD type for each registered . An application could use such PDs without the need to register anything . Just pick the " right " type and populate the relevant fields , job done . As a nice side - effect , this would allow exercising the registration procedure , including the definition of the PD type 's registry structure and providing a first set of registrations .
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.
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.
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.