Concise Problem Details for Constrained Application Protocol (CoAP) APIs
Extracted elements (26)
Custom Problem Detail entries may use either URIs (no registration needed, useful during development and in tightly integrated deployments) or unsigned integers (registered, more compact encoding). The URI form avoids needing a 'Private Use' range for integers, while the uint form benefits constrained environments through shorter encoding.
Standard Problem Detail keys use negative integers so they can never conflict with Custom Problem Detail keys, which use unsigned integers or URIs. This partitioning ensures a global namespace for standard entries without collisions from application-specific extensions.
The response-code value is the numeric representation of the CoAP code (e.g., 132 for 4.04), not the dotted presentation form. This is because CoAP response codes are defined as structured bytes, and the numeric form is canonical; it also allows the field to persist in logs and databases without CoAP framing context.
Unlike RFC 7807, Concise Problem Details have no explicit 'problem type' field. Instead, the category of a problem is conveyed by the 'problem shape' — the combination of entries present in the data item. This avoids the overhead of a type URI in constrained environments.
To tunnel RFC 7807 problem details inside a Concise Problem Details data item, the 'title', 'detail', and 'instance' members are moved to their Standard Problem Detail equivalents, 'type' and 'status' go into a Custom Problem Detail entry at key 7807, and all remaining members are placed in that same nested map unchanged.
A URI used as a Custom Problem Detail entry key is for identification only and MUST NOT be dereferenced during normal handling of problem details (only in diagnostic or debugging procedures involving humans), to prevent tracking and information disclosure.
Consumers MUST ignore any Standard Problem Detail entries, Custom Problem Detail entries, or keys inside Custom Problem Detail entries that they do not recognize (the ignore-unknown rule), allowing problem details to evolve.
Consumers SHOULD NOT parse the detail member for structured information; extensions (Section 3) are more suitable and less error-prone ways to convey machine-readable information.
Generators MUST use the same CoAP response code in the response-code field as in the actual CoAP response, to ensure generic CoAP software that does not understand problem details still behaves correctly.
Privacy-sensitive information in problem details SHOULD NOT be obscured in ways that might lead to misclassification as non-sensitive (e.g., by base64-encoding), since such obfuscation can cause it to bypass privacy-filtering logic.
The semantics of each custom attribute MUST be described in the documentation for the extension; for registered extensions identified by unsigned integers, that documentation accompanies the registration.
When storing or forwarding a Concise Problem Details data item, it is strongly RECOMMENDED to retain unrecognized entries; exceptions apply when the target format cannot accommodate them or when filtering privacy-sensitive information.
Problem details may unintentionally disclose information, potentially leading to both privacy and security problems. Particular attention must be paid to avoid unintentionally including Personally Identifiable Information (PII) in problem detail entries.
Custom Problem Detail entries use keys that are either absolute URIs (no registration required, useful for development) or unsigned integers (requires registration, yields compact encoding). Each custom entry maps to a nested CBOR map specific to that application domain.
The response-code entry (key -4) carries the CoAP response code as a one-byte unsigned integer numeric value (e.g., 132 for 4.04 Not Found), not the dotted HTTP-like presentation form. It is advisory and provided for consumer convenience.
The title entry (key -1) is a short, human-readable summary of the problem shape — the category of error, not a full account of specific details. It is advisory and uses either plain text or a language-tagged string (tag38).
The unprocessed-coap-option Standard Problem Detail entry (key -8) carries one or more CoAP option numbers (as uint) that the server could not process. Multiple option numbers are given in a list with no guaranteed completeness; the list may include options added by a proxy.
IANA updated the reference for CBOR tag 38 (language-tagged strings) in the CBOR Tags registry to point to RFC 9290 Appendix A, which now serves as the archival documentation for that tag.
RFC 9290 creates the 'Custom Problem Detail Keys' subregistry in the CoRE Parameters registry. Registration procedure is Expert Review (relaxed toward First Come First Served). Keys are unsigned integers; the initial entry is 7807 (tunnel-7807, for carrying RFC 7807 problem details).
RFC 9290 creates the 'Standard Problem Detail Keys' subregistry in the CoRE Parameters registry. Registration procedure is Specification Required. Keys are negative integers; initial entries are -1 (title) through -8 (unprocessed-coap-option). Names must match [a-z][-a-z0-9]*.
RFC 9290 registers CoAP Content-Format ID 257 for 'application/concise-problem-details+cbor' in the CoAP Content-Formats subregistry of the CoRE Parameters registry.
RFC 9290 registers the media type 'application/concise-problem-details+cbor' in the IANA Media Types registry. Encoding is binary (CBOR data item); intended usage is COMMON for IoT clients and servers.
All security and privacy considerations from RFC 7807 Section 5 apply in full, including care when defining new detail entries and when generating a Concise Problem Details data item not to leak sensitive information. Entities storing or forwarding data items must consider whether doing so transfers sensitive information outside the context where access was acceptable.
URIs in problem details (including identification-only URIs for custom entries and the 'instance' URI) must not be automatically dereferenced, as doing so can cause information disclosure through tracking. Implementations must determine which client component may dereference and which servers are trusted.
A Concise Problem Details data item is a CBOR map with optional fields: title (key -1, text/tag38), detail (key -2, text/tag38), instance (key -3, ~uri), response-code (key -4, uint .size 1), base-uri (key -5, ~uri), base-lang (key -6, tag38-ltag), base-rtl (key -7, tag38-direction), plus standard-problem-detail-entries (negative integer keys) and custom-problem-detail-entries (unsigned integer or URI keys mapping to nested maps). The map must be non-empty.
CBOR tag 38 encodes a language-tagged text string as an array of length 2 or 3: element 0 is a BCP 47 language tag (UTF-8 text), element 1 is an arbitrary UTF-8 text string, and the optional element 2 is a ternary direction indicator (false=ltr, true=rtl, null=auto). Arrays not meeting these criteria are not valid CBOR tag 38 items.