Original text:
<del> Problem Details For CoAP APIs </del>  draft-ietf-core-problem-details-latest Abstract This document defines a "problem detail" as a way to carry machine- <del> 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. </del>  1. <del> 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. </del>  <del> The vocabulary presented is largely inspired by the Problem Details for HTTP APIs defined in RFC7807. </del>  1.1. 2. <del> A CoRE Problem Details is a CoRAL document with the following elements: </del>  <del> "type" (id) - The problem type.  This is a mandatory element. </del>  <del> "title" (text) - A short, human-readable summary of the problem type.  It SHOULD NOT change from occurrence to occurrence of the problem. </del>  <del> "detail" (text) - A human-readable explanation specific to this occurrence of the problem. </del>  <del> "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. </del>  The "detail" member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information. prone ways to obtain such information. Note that the "instance" URI reference may be relative; this means <del> that it must be resolved relative to the document's base URI, as per I-D.ietf-core-coral. 2.1. 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). 3. 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. </del>  <del> When using one such problem type, an application MUST make sure that the type matches the CoAP response code in the underlying CoAP transaction. </del>  <del> If a title element is used in the Problem Details payload, it SHOULD be populated with the title corresponding to the type. </del>  <del> The types defined in this document reflect the state of the relevant portion of the "CoAP Codes" registry at the time of writing. </del>  4. <del> In the following sections we introduce specific (albeit "common enough") use cases, and define the extensions to the basic format needed to support them. 4.1. </del>  <del> 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). </del>  <del> 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. </del>  <del> The additional protocol element is: </del>  <del> "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. </del>  <del> Leaking private or sensitive data SHOULD be avoided. </del>  <del> 4.1.1. </del>  <del> The example in fig-example-diag-stack has a "diag" element with a stack trace associated with the error condition. </del>  <del> 5. </del>  <del> Problem type definitions MAY extend the Problem Details document with additional elements to convey additional, problem-specific information. </del>  <del> 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. </del>  <del> 5.1. </del>  <del> The example in fig-example-ext-full has all the basic elements as well as an additional, type-specific element. </del>  <del> 6. </del>  <del> 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. </del>  <del> The security and privacy considerations outlined in Section 5 of RFC7807 apply in full. </del>  <del> 7. </del>  <del> TODO. </del> 

Reviewer comments:
This PR provides the write-up of the discussed at the interim. Note that it branches off Carsten's "bundled" PR ()
I did a little bit of editing. Comments welcome...

Revised text:
 <ins> Concise Problem Details For CoAP APIs </ins> draft-ietf-core-problem-details-latest Abstract This document defines a "problem detail" as a way to carry machine-  <ins> 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. </ins> 1.  <ins> 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. </ins>  <ins> 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. </ins> 1.1. 2.  <ins> A Concise Problem Details data item is a CBOR data item with the following structure (notated in CDDL RFC8610): </ins>  <ins> A number of problem detail entries, the Standard Problem Detail entries, are predefined (more predefined details can be registered, see new-spdk): </ins>  <ins> Note that, unlike RFC7807, Concise Problem Details data items have no explicit type. </ins>  <ins> 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. </ins>  <ins> The "title" string is advisory and included to give consumers a shorthand for the category of the error encountered. </ins> The "detail" member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information. prone ways to obtain such information. Note that the "instance" URI reference may be relative; this means  <ins> that it must be resolved relative to the representation's base URI, as per STD66. </ins>  <ins> 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. </ins>  <ins> 3. </ins>  <ins> 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. 3.1. 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). Standard Problem Detail keys are negative integers, so they never can conflict with Custom Problem Detail keys defined for a specific application domain (which are unsigned integers or URIs.) 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. 3.2. 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. The unsigned integer form allows a more compact representation, in exchange, authors are expected to comply with the required registration and documentation process.  In comparison, the URI form is less space-efficient but requires no registration.  It is therefore useful for experimenting during the development cycle and for applications deployed in environments where producers and consumers of Concise Problem Details are more tightly integrated. (The URI form thus covers the potential need we might otherwise have for a "private use" range for the unsigned integers.) 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. </ins> 4.  <ins> The security and privacy considerations outlined in Section 5 of RFC7807 apply in full. </ins>  <ins> 5. </ins>  <ins> 5.1. </ins>  <ins> 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. </ins>  <ins> Each entry in the registry must include: </ins>  <ins> Initial entries in this sub-registry are as follows: </ins>  <ins> 5.2. </ins>  <ins> 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. </ins>  <ins> Each entry in the registry must include: </ins>  <ins> Initial entries in this sub-registry are as follows: </ins>  <ins> 5.3. </ins>  <ins> IANA is requested to add the following Media-Type to the "Media Types" registry IANA.media-types. </ins>  <ins> 5.4. </ins>  <ins> IANA is requested to register a Content-Format number in the IANA.core-parameters sub-registry, within the "Constrained RESTful Environments (CoRE) Parameters" Registry IANA.core-parameters, as follows: </ins>  <ins> TBD1 is to be assigned from the space 256..999. </ins>  <ins> 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". </ins>  <ins> 5.5. </ins>  <ins> In the registry "IANA.cbor-tags" IANA.cbor-tags, IANA has registered CBOR Tag 38.  IANA is requested to replace the reference for this registration with tag38, RFC XXXX. </ins>