RFC 9290

Concise Problem Details for Constrained Application Protocol (CoAP) APIs

📅 published October 2022, from ietf

RFC 9290: Concise Problem Details for CoAP APIs 🌸

okay bestie, let's talk about RFC 9290, which is titled Concise Problem Details for Constrained Application Protocol (CoAP) APIs. It's a Standards Track doc, so it's the real deal. Authors T. Fossati (Arm Limited) and C. Bormann (Universität Bremen TZI) wrote it, and it came out in October 2022 with ISSN 2070-1721. The title block doesn't list any Obsoletes or Updates lines, so there's no drama about replacing or changing other RFCs here 💅

Abstract ✨

okay so this doc defines a concise "problem detail" 🎀 It's a way to pack machine-readable error details into a Representational State Transfer (REST) response, so constrained environments don't have to invent a brand new error response format for every REST API. It's inspired by the problem details for HTTP APIs in RFC 7807, but way more concise, which is the whole point 🦋

Status of This Memo 💅

this is an Internet Standards Track document 🔥

it's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 7841.

info about the current status, errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc9290 💖

Copyright Notice 🔥

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date. Please actually read those, because they spell out your rights and restrictions for this document 🙈

Code Components pulled out of this doc must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions. They come with no warranty, as described in the Revised BSD License.

Table of Contents 🦋

1.  Introduction
  1.1.  Terminology and Requirements Language
2.  Basic Problem Details
3.  Extending Concise Problem Details
  3.1.  Standard Problem Detail Entries
    3.1.1.  Standard Problem Detail Entry: Unprocessed CoAP Option
  3.2.  Custom Problem Detail Entries
4.  Privacy Considerations
5.  Security Considerations
6.  IANA Considerations
  6.1.  Standard Problem Detail Keys Registry
  6.2.  Custom Problem Detail Keys Registry
  6.3.  Media Type
  6.4.  Content-Format
  6.5.  CBOR Tag 38
7.  References
  7.1.  Normative References
  7.2.  Informative References
Appendix A.  Language-Tagged Strings
  A.1.  Introduction
  A.2.  Detailed Semantics
  A.3.  Examples
Appendix B.  Interworking with RFC 7807
Acknowledgments
Contributors
Authors' Addresses

1. Introduction ✨

okay so REST response status info, like CoAP response codes (Section 5.9 of [RFC7252]), isn't always enough to tell you what actually went wrong, and that's a real problem 😭 This spec gives you a simple, extensible framework for defining Concise Binary Object Representation (CBOR) [STD94] data items to fill that gap.

The framework is built so REST APIs can reuse it and pick out their own distinct "shapes" of these data items. That means API clients get both the high-level error class (from the response code) and the finer-grained details of the problem (from the vocabulary defined here). Figure 1 shows how this plays out 🌈

                 .--------.          .--------.
                 |  CoAP  |          |  CoAP  |
                 | Client |          | Server |
                 '----+---'          '---+----'
                      |                  |
                      | Request          |
                      o----------------->|
                      |                  | (failure)
                      |<-----------------o
                      |   Error Response |
                      |      with a CBOR |
                      | data item giving |
                      |  Problem Details |
                      |                  |

Figure 1: Problem Details: Example with CoAP

this whole thing is largely inspired by the problem details for HTTP APIs in [RFC7807]. Appendix B covers the situations where you need to interwork with [RFC7807] 🧚

1.1. Terminology and Requirements Language

the terminology from [RFC7252], [STD94], and [RFC8610] applies here. Specifically, CBOR diagnostic notation is defined in Section 8 of RFC 8949 [STD94] and Appendix G of [RFC8610]. Readers are also expected to already know the terminology from [RFC7807] 💜

the structure of the data is specified in Concise Data Definition Language (CDDL) [RFC8610] [RFC9165].

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. So lowercase versions are just regular words, no cap 🙈

2. Basic Problem Details 🎀

a Concise Problem Details data item is a CBOR data item with the following structure. Rules whose names start with tag38 are defined in Appendix A 💖

problem-details = non-empty<{
  ? &(title: -1) => oltext
  ? &(detail: -2) => oltext
  ? &(instance: -3) => ~uri
  ? &(response-code: -4) => uint .size 1
  ? &(base-uri: -5) => ~uri
  ? &(base-lang: -6) => tag38-ltag
  ? &(base-rtl: -7) => tag38-direction
  standard-problem-detail-entries
  custom-problem-detail-entries
}>

standard-problem-detail-entries = (
  * nint => any
)

custom-problem-detail-entries = (
  * (uint/~uri) => { + any => any }
)

non-empty<M> = (M) .and ({ + any => any })

oltext = text / tag38

Figure 2: Structure of Concise Problem Details Data Item

(elaborated examples of Concise Problem Details data items show up later in the doc, like Figure 3, so stay tuned 👑)

a bunch of problem detail entries are predefined. These are called the Standard Problem Detail entries, and you can register more predefined details too (see Section 3.1) ✨

ok, big difference from [RFC7807]: Concise Problem Details data items have no explicit "problem type" 😤 Instead, the category (or, you could say, the Gestalt) of the problem is understood from the shape of the problem details you get. We call that a "problem shape" for short 🔥

The title (key -1): A short, human-readable summary of the problem shape. Beyond the shape of the problem, it isn't meant to summarize all the specific info given with the problem details. For example, the summary might say that an account doesn't have enough money for a transaction to succeed, but it won't include the detailed stuff like the account number, how much money is in the account, or how much would be needed 💸

The detail (key -2): A human-readable explanation specific to this particular occurrence of the problem 🌸

The instance (key -3): A URI reference that identifies this specific occurrence of the problem. It may or may not give you more info if you dereference it 🦋

The response-code (key -4): The CoAP response code (Sections 5.9 and 12.1.2 of [RFC7252]) generated by the origin server for this occurrence of the problem 🍓

The base-uri (key -5): The base URI (see Section 5.1 of RFC 3986 [STD66]) that should be used to resolve relative URI references embedded in this Concise Problem Details data item 🌈

The base-lang (key -6): The language-tag (tag38-ltag) that applies to the presentation of unadorned text strings (the ones not using tag 38) in this Concise Problem Details data item. See Appendix A 🌍

The base-rtl (key -7): The writing-direction (tag38-direction) that applies to the presentation of unadorned text strings (the ones not using tag 38) in this Concise Problem Details data item. See Appendix A too ➡️

okay so both "title" and "detail" can use either an unadorned CBOR text string (text) or a language-tagged text string (tag38). Appendix A has the definition of the latter 🎀 Language tag and writing direction info for unadorned text strings is meant to come from context. If that context needs to be saved or forwarded along with a Concise Problem Details data item, then "base-lang" and "base-rtl" can be used. If there's no such context available (explicitly saved or implicit), unadorned text is interpreted with language-tag "en" and writing-direction "false" (ltr) 💅

the "title" string is advisory. It's there to give consumers a shorthand for the category (problem shape) of the error they hit ✨

the "detail" member, if it's present, ought to focus on helping the client fix the problem, rather than dumping extensive server-side debugging info 🙈 Consumers SHOULD NOT parse the "detail" member for information. Extensions (see Section 3) are way more suitable and less error-prone for getting that kind of info 😭 Also, the "instance" URI reference may be relative. That means it must be resolved relative to the representation's base URI, as per Section 5 of RFC 3986 [STD66] 🦋

the "response-code" member, if present, is only advisory. It conveys the CoAP response code used for the consumer's convenience 🍓 Generators MUST use the same response code here as in the actual CoAP response. The actual CoAP response is needed so generic CoAP software that doesn't understand the problem-details format still behaves correctly 💖 Consumers can use the "response-code" member to figure out what the original response code from the generator was, in cases where it's been changed (for example, by an intermediary or cache), and when message bodies stick around without CoAP info (like in an events log or analytics database) 📊 Generic CoAP software will still use the CoAP response code, no matter what. And to support message-body persistence when the problem-details generator doesn't support it, the entity doing the persisting can copy over the CoAP response code it received at the CoAP level 🫶

one more thing about "response-code": it's a numeric representation of the actual code (see Section 3 of [RFC7252]). So it does NOT look like the usual presentation form you'd expect from an HTTP status code. For example, 4.04 Not Found is represented by the number 132 🤯

the "base-uri" member is usually not present in the initial request-response communication, because it can be inferred as per Section 5.1.3 of RFC 3986 [STD66] 🌸 An entity that stores a Concise Problem Details data item, or otherwise makes it available to consumers without this context, might add a "base-uri" member. That lets those consumers resolve any relative URI references embedded in the data item 💜

3. Extending Concise Problem Details ✨

okay so this spec only gives you a super minimal, generic problem-details container 💖. It's totally expected that apps will extend the base format by defining new attributes 🧚

Those new attributes come in two flavours: generic and application specific 🎀

Generic attributes get allocated in the standard-problem-detail-entries slot, following the registration procedure in Section 3.1 🌸

Application-specific ones go in the custom-problem-detail-entries slot, following the procedure in Section 3.2 💅

Consumers of a Concise Problem Details data item MUST ignore any Standard Problem Detail entries or Custom Problem Detail entries, or keys inside the Custom Problem Detail entries, that they do not recognize ("ignore-unknown rule"). This is what lets problem details evolve over time 🦋 When you're storing the data item for later or forwarding it to other consumers, it is strongly RECOMMENDED to keep the unrecognized entries 🫶 The exceptions? Storage or forwarding that happens in a different format or protocol that can't fit them, or a storage or forwarding step that needs to filter out privacy-sensitive info. In that second case, it has to assume the unrecognized entries might be privacy-sensitive 🙈

3.1. Standard Problem Detail Entries

Beyond the Standard Problem Detail keys defined in Figure 2, more Standard Problem Detail keys can be registered for use in the standard-problem-detail-entries slot (see Section 6.1) 🍓

Standard Problem Detail keys are negative integers, so they can never clash with Custom Problem Detail keys defined for a specific application domain. Those are unsigned integers or URIs (iykyk) 🔥

In summary, the keys for Standard Problem Detail entries live in a global namespace that isn't tied to any one application domain 👑

3.1.1. Standard Problem Detail Entry: Unprocessed CoAP Option

Section 2 already gives a bunch of generally useful Standard Problem Detail entries. This section registers another useful one, and it doubles as an example of what a Standard Problem Detail Entry registration looks like, written in the registration template format ready for registration 📝✨

   Key value:
      -8
   Name:
      unprocessed-coap-option
   CDDL type:
      one-or-more<uint>, where
      one-or-more<T> = T / [ 2* T ]
   Brief description:
      Option number(s) of CoAP option(s) that were not understood
   Specification reference:
      Section 3.1.1 of RFC 9290

Here's the spec for the Standard Problem Detail entry referenced by that template 💅

The unprocessed-coap-option entry gives the option number or numbers of any CoAP options in the request that the server couldn't process 🌈

That could be a critical option the server doesn't know about. Or it could be an option the server does know about but couldn't process (and either chose not to ignore it, or wasn't allowed to) 🙈

A Concise Problem Details data item that includes this Standard Problem Detail Entry can be used to fulfil the "SHOULD" requirement in Section 5.4.1 of [RFC7252]. That's a whole vibe 🎀

Several option numbers can come in a list (in no particular order). There's no guarantee the list is a complete picture of every problem in the request, though, because the server might have stopped processing already at one of the problematic options 😭

If an option with a given number was repeated, there's no way to tell which of the values caused the error 💀

Clients need to expect options in the list that they never sent. That can happen if the request went through a proxy that added the option but didn't act on the problem-details response that the origin server sent back 🦋

For a few special values of unprocessed CoAP options (like Accept or Proxy-Uri), there are special response codes to send instead of 4.02 Bad Option. Those are 4.06 Not Acceptable and 5.05 Proxying Not Supported, respectively 💖

3.2. Custom Problem Detail Entries

Applications can extend the Concise Problem Details data item with extra entries to carry additional, application-specific info 🧚

Those new entries get allocated in the custom-problem-detail-entries slot and carry a nested map that belongs to that application. The map key can be either an (absolute!) URI, under the control of the entity defining the extension, or an unsigned integer. Only the unsigned integer ones need to be registered (Section 6.2) ✨

Inside the nested map, a single extension can have any number of attributes. The semantics of each custom attribute MUST be described in the documentation for the extension. For extensions that are registered (meaning they're identified by an unsigned int), that documentation goes along with the registration 📚

Unsigned integer keys are more compact. The trade-off is that authors are expected to go through the required registration and documentation process. The URI form is less space efficient, but it needs no registration. That makes it handy for experimenting during development, and for apps deployed where producers and consumers of Concise Problem Details are tightly integrated 🌸 (So the URI form covers the potential need we might otherwise have had for a "Private Use" range of unsigned integers 💅)

Here's a note that matters: the URI given for the extension is only for identification. Even if it could be dereferenced in principle, it MUST NOT be dereferenced in the normal course of handling problem details. The only exception is diagnostic or debugging procedures that involve humans 🙈

Figure 3 shows an example in CBOR diagnostic notation of a custom extension that uses a (made-up) URI as the custom-problem-detail-entries key 👀

   {
     / title /         -1: "title of the error",
     / detail /        -2: "detailed information about the error",
     / instance /      -3: "coaps://pd.example/FA317434",
     / response-code / -4: 128, / 4.00 /

     "tag:3gpp.org,2022-03:TS29112": {
       / cause /  0: "machine-readable error cause",
       / invalidParams / 1: [
         [
           / param / "first parameter name",
           / reason / "must be a positive integer"
         ],
         [
           / param / "second parameter name"
         ]
       ],
       / supportedFeatures / 2: "d34db33f"
     }
   }

                  Figure 3: Example Extension with URI Key

Obviously, a Standards Development Organization (SDO) like 3GPP can also easily register a Custom Problem Detail entry like this to get a more efficient unsigned integer key 🏆 Figure 4 shows how the same example would look using a (made-up) registered unsigned int as the custom-problem-detail-entries key 🧁

   {
     / title /         -1: "title of the error",
     / detail /        -2: "detailed information about the error",
     / instance /      -3: "coaps://pd.example/FA317434",
     / response-code / -4: 128, / 4.00 /

     /4711 is made-up example key that is not actually registered:/
     4711: {
       / cause /  0: "machine-readable error cause",
       / invalidParams / 1: [
         [
           / param / "first parameter name",
           / reason / "must be a positive integer"
         ],
         [
           / param / "second parameter name"
         ]
       ],
       / supportedFeatures / 2: "d34db33f"
     }
   }

       Figure 4: Example Extension with Unsigned Int (Registered) Key

In summary, the keys for the maps inside Custom Problem Detail entries are defined specifically for use with the identifier of that Custom Problem Detail entry. The documentation for that entry defines these internal entries, usually chosen to suit a given application domain 🌈

When a Custom Problem Detail entry definition needs to evolve, the "ignore-unknown rule" from Section 3 gives an easy way to add more info. The idea is that this is done in a backward- and forward-compatible way 🫶 Sometimes, though, forward compatibility via the "ignore-unknown rule" wouldn't be appropriate. For example, when adding a "must-understand" member, which can only be ignored at the peril of misunderstanding the Concise Problem Details data item ("false interoperability") 😱 In that case, a new Custom Problem Detail key can simply be registered, which keeps the old key backward and forward compatible ✨

4. Privacy Considerations 🙈

Problem details can unintentionally disclose information. That can lead to both privacy and security problems. See Section 5 for more details that apply to both areas. Particular attention needs to go to accidentally disclosing Personally Identifiable Information (PII) 🔒

5. Security Considerations 🚨

Concise Problem Details can contain URIs that are not intended to be dereferenced (Section 3.2, Paragraph 5). Dereferencing them can lead to information disclosure (tracking), which is a major yikes 😭 Information disclosure can also come from URIs in problem details that _are_ intended for dereferencing, like the "instance" URI. Implementations need to think carefully about which component of a client should do the dereferencing, and which servers are trusted to serve them. Either way, the security considerations of Section 7 of RFC 3986 [STD66] apply 🛡️

Heads up: the security and privacy considerations in Section 5 of [RFC7807] apply in full. ⚠️

Those considerations are phrased in terms of new RFC 7807 problem types, but they apply just as much to the problem detail entry definitions used here (Section 3). So, both when defining new detail entries and when actually using them to generate a Concise Problem Details data item, you need to take care that they don't leak sensitive information 🔐 Entities that store or forward Concise Problem Details data items need to consider whether that moves information out of the context where access to the sensitive info was acceptable. See also Section 3, Paragraph 6 (the last paragraph of the introduction to that section) 🧐 Privacy-sensitive information in problem details SHOULD NOT be obscured in ways that might get it misclassified as non-sensitive (for example, by base64-encoding). Don't let it slip through in disguise, bestie 💀

6. IANA Considerations 🌸

6.1. Standard Problem Detail Keys Registry ✨

okay so this bit makes a brand new subregistry called "Standard Problem Detail Keys" inside the "Constrained RESTful Environments (CoRE) Parameters" registry [IANA.core-parameters] 🎀 The registration procedure is "Specification Required" (Section 4.6 of [RFC8126]), so it's serious business 💅

Each entry in the registry must include:

Key Value: a negative integer to be used as the value of the key
Name: a name that could be used in implementations for the key
CDDL Type: type of the data associated with the key in CDDL notation
Brief Description: a brief description
Reference: a reference document
Change Controller: (see Section 2.3 of [RFC8126])

The designated expert is requested to give the shortest key values (1+0 and 1+1 encoding) to registrations that are likely to be widely used and can benefit from short encodings 🧚

To be immediately useful in CDDL and programming-language contexts, a name has to be a lowercase ASCII letter (a-z) followed by zero or more additional ASCII characters that are lowercase letters, digits, or a hyphen-minus. In other words, it matches [a-z][-a-z0-9]*. Just like the key values, names need to be unique 🌸

The specification in the reference document needs to describe the Standard Problem Detail entry. It should replicate the CDDL description in "CDDL Type" and explain what it means for this entry to be present, plus what the value given with it means 🫶

Initial entries in this subregistry are as follows:

+=====+============+===============+===========+=========+==========+
|Key  |Name        |CDDL Type      |Brief      |Reference|Change    |
|Value|            |               |Description|         |Controller|
+=====+============+===============+===========+=========+==========+
|-1   |title       |text / tag38   |Short,     |RFC 9290 |IETF      |
|     |            |               |human-     |         |          |
|     |            |               |readable   |         |          |
|     |            |               |summary of |         |          |
|     |            |               |the problem|         |          |
|     |            |               |shape      |         |          |
+-----+------------+---------------+-----------+---------+----------+
|-2   |detail      |text / tag38   |Human-     |RFC 9290 |IETF      |
|     |            |               |readable   |         |          |
|     |            |               |explanation|         |          |
|     |            |               |specific to|         |          |
|     |            |               |this       |         |          |
|     |            |               |occurrence |         |          |
|     |            |               |of the     |         |          |
|     |            |               |problem    |         |          |
+-----+------------+---------------+-----------+---------+----------+
|-3   |instance    |~uri           |URI        |RFC 9290 |IETF      |
|     |            |               |reference  |         |          |
|     |            |               |identifying|         |          |
|     |            |               |specific   |         |          |
|     |            |               |occurrence |         |          |
|     |            |               |of the     |         |          |
|     |            |               |problem    |         |          |
+-----+------------+---------------+-----------+---------+----------+
|-4   |response-   |uint .size 1   |CoAP       |RFC 9290 |IETF      |
|     |code        |               |response   |         |          |
|     |            |               |code       |         |          |
+-----+------------+---------------+-----------+---------+----------+
|-5   |base-uri    |~uri           |Base URI   |RFC 9290 |IETF      |
+-----+------------+---------------+-----------+---------+----------+
|-6   |base-lang   |tag38-ltag     |Base       |RFC 9290 |IETF      |
|     |            |               |language   |         |          |
|     |            |               |tag (see   |         |          |
|     |            |               |Appendix A)|         |          |
+-----+------------+---------------+-----------+---------+----------+
|-7   |base-rtl    |tag38-direction|Base       |RFC 9290 |IETF      |
|     |            |               |writing    |         |          |
|     |            |               |direction  |         |          |
|     |            |               |(see       |         |          |
|     |            |               |Appendix A)|         |          |
+-----+------------+---------------+-----------+---------+----------+
|-8   |unprocessed-|one-or-        |Option     |RFC 9290,|IETF      |
|     |coap-option |more<uint>     |number(s)  |Section  |          |
|     |            |               |of CoAP    |3.1.1    |          |
|     |            |               |option(s)  |         |          |
|     |            |               |that were  |         |          |
|     |            |               |not        |         |          |
|     |            |               |understood |         |          |
+-----+------------+---------------+-----------+---------+----------+

Table 1: Initial Entries in the Standard Problem Detail Keys Registry

6.2. Custom Problem Detail Keys Registry 🦋

This one makes a new subregistry called "Custom Problem Detail Keys" in that same CoRE Parameters registry [IANA.core-parameters]. The registration procedure is "Expert Review" (Section 4.5 of [RFC8126]) 🌈

The designated expert is told to make registration feel as close to First Come First Served as is reasonably achievable, while still checking that the reference document gives a description as set out below. (This is a relaxed version of "Specification Required" as defined in Section 4.6 of [RFC8126]. Lowkey a chill vibe 😌)

Each entry in the registry must include:

Key Value: an unsigned integer to be used as the value of the key
Name: a name that could be used in implementations for the key
Brief Description: a brief description
Reference: a reference document that provides a description of the map, including a CDDL description, that describes all inside keys and values
Change Controller: (see Section 2.3 of [RFC8126])

The designated expert is requested to give the shortest key values (1+0 and 1+1 encoding) to registrations that are likely to be widely used and can benefit from short encodings 💖

The naming rules are the same as before: a name is a lowercase ASCII letter (a-z) followed by zero or more lowercase letters, digits, or hyphen-minuses, matching [a-z][-a-z0-9]*, so it's CDDL and programming-language friendly. Names and key values both need to be unique 🧚

Initial entries in this subregistry are as follows:

+=======+=============+====================+===========+============+
| Key   | Name        | Brief              | Reference | Change     |
| Value |             | Description        |           | Controller |
+=======+=============+====================+===========+============+
| 7807  | tunnel-7807 | Carry RFC 7807     | RFC 9290, | IETF       |
|       |             | problem details    | Appendix  |            |
|       |             | in a Concise       | B         |            |
|       |             | Problem Details    |           |            |
|       |             | data item          |           |            |
+-------+-------------+--------------------+-----------+------------+

Table 2: Initial Entries in the Custom Problem Detail Key Registry

6.3. Media Type 🎀

IANA has added the following media type to the "Media Types" registry [IANA.media-types] 💅

+============================+============================+=========+
|Name                        |Template                    |Reference|
+============================+============================+=========+
|concise-problem-details+cbor|application/concise-problem-|RFC 9290,|
|                            |details+cbor                |Section  |
|                            |                            |6.3      |
+----------------------------+----------------------------+---------+

Table 3: New Media Type 'application/concise-problem-details+cbor'

The registration template for this media type is below, copied exactly as written:

Type name:  application

Subtype name:  concise-problem-details+cbor

Required parameters:  N/A

Optional parameters:  N/A

Encoding considerations:  binary (CBOR data item)

Security considerations:  Section 5 of RFC 9290

Interoperability considerations:  none

Published specification:  Section 6.3 of RFC 9290

Applications that use this media type:  Clients and servers in the
   Internet of Things

Fragment identifier considerations:  The syntax and semantics of
   fragment identifiers is as specified for "application/cbor".  (At
   publication of RFC 9290, there is no fragment identification
   syntax defined for "application/cbor".)

Additional information:

   Deprecated alias names for this type:  N/A
   Magic number(s):  N/A
   File extension(s):  N/A
   Macintosh file type code(s):  N/A

Person & email address to contact for further information:  CoRE WG
   mailing list (core@ietf.org) or IETF Applications and Real-Time
   Area (art@ietf.org)

Intended usage:  COMMON

Restrictions on usage:  none

Author/Change controller:  IETF

Provisional registration:  no

6.4. Content-Format 🍓

IANA has registered a Content-Format number in the "CoAP Content-Formats" subregistry, within the "Constrained RESTful Environments (CoRE) Parameters" registry [IANA.core-parameters], like so:

+==============================+==========+=====+===========+
| Media Type                   | Encoding | ID  | Reference |
+==============================+==========+=====+===========+
| application/concise-problem- | -        | 257 | RFC 9290  |
| details+cbor                 |          |     |           |
+------------------------------+----------+-----+-----------+

Table 4: Content-Format Registration

6.5. CBOR Tag 38 🌙

In the "CBOR Tags" registry [IANA.cbor-tags], IANA has registered CBOR tag 38. IANA has also updated the reference for CBOR tag 38 so it points to RFC 9290, Appendix A. That's the whole glow-up 🔥

7. References 📚

7.1. Normative References 📚

[IANA.cbor-tags] IANA, "Concise Binary Object Representation (CBOR) Tags", <https://www.iana.org/assignments/cbor-tags>. 🏷️
[IANA.core-parameters] IANA, "Constrained RESTful Environments (CoRE) Parameters", <https://www.iana.org/assignments/core-parameters>. 🌸
[IANA.media-types] IANA, "Provisional Standard Media Type Registry", <https://www.iana.org/assignments/provisional-standard-media-types>. 💅
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. 👑
[RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 2006, <https://www.rfc-editor.org/info/rfc4647>. 🌈
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009, <https://www.rfc-editor.org/info/rfc5646>. 🫶
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, <https://www.rfc-editor.org/info/rfc7252>. 🦋
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, <https://www.rfc-editor.org/info/rfc7807>. 🧚
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/info/rfc8126>. 📋
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. 🔥
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019, <https://www.rfc-editor.org/info/rfc8610>. 🍓
[RFC9165] Bormann, C., "Additional Control Operators for the Concise Data Definition Language (CDDL)", RFC 9165, DOI 10.17487/RFC9165, December 2021, <https://www.rfc-editor.org/info/rfc9165>. ⭐
[STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. <https://www.rfc-editor.org/info/std66> 🌸
[STD94] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, December 2020. <https://www.rfc-editor.org/info/std94> 💜

7.2. Informative References 🔍

[HTTPAPI] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", Work in Progress, Internet-Draft, draft-ietf-httpapi-rfc7807bis-04, 5 September 2022, <https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-rfc7807bis-04>. 🎀
[RDF] Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 Concepts and Abstract Syntax", W3C Recommendation, 25 February 2014, <http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/>. 🌐
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, <https://www.rfc-editor.org/info/rfc4648>. 🔤
[RFC6082] Whistler, K., Adams, G., Duerst, M., Presuhn, R., Ed., and J. Klensin, "Deprecating Unicode Language Tag Characters: RFC 2482 is Historic", RFC 6082, DOI 10.17487/RFC6082, November 2010, <https://www.rfc-editor.org/info/rfc6082>. 🪦
[Unicode-14.0.0] The Unicode Consortium, "The Unicode Standard, Version 14.0.0", Mountain View: The Unicode Consortium, ISBN 978-1-936213-29-0, September 2021, <https://www.unicode.org/versions/Unicode14.0.0/>. 🌍
[Unicode-14.0.0-bidi] The Unicode Consortium, "Unicode Standard Annex #9 --- Unicode Bidirectional Algorithm", 27 August 2021, <https://www.unicode.org/reports/tr9/#Markup_And_Formatting>. ↔️

Appendix A. Language-Tagged Strings 🏷️

This appendix is the archive for CBOR tag 38, the tag that serializes language-tagged text strings in CBOR. ✨ The text is adapted from the specification text supplied for its initial registration, and it has been extended so the language tag can be supplemented by a direction indication. 🧁

As with any IANA-registered item, a specification that further updates this registration needs to update the reference column of the IANA registry (see Section 6.5). 📌 Future specifications may update this appendix, other parts of this document, or both. (When updating this appendix, keep in mind that applications beyond Concise Problem Details data items may adopt the tag defined here.) 💭 Users of this tag are advised to consult the registry to obtain the most recent update for this appendix. 🫶

A.1. Introduction 🌷

In some cases, it is useful to specify the natural language of a text string. 🗣️ This specification defines a tag that does just that. One technology that supports language-tagged strings is the Resource Description Framework (RDF) [RDF]. 🧠

A.2. Detailed Semantics 💖

A language-tagged text string in CBOR has the tag 38 and consists of an array with a length of 2 or 3. 🎀

The first element is a well-formed language tag described in BCP 47 ([RFC5646] and [RFC4647]), represented as a UTF-8 text string (major type 3). 🌈

The second element is an arbitrary UTF-8 text string (major type 3). Both the language tag and the arbitrary string can optionally be annotated with CBOR tags; this is not shown in the CDDL below. 🦋

The optional third element, if present, represents a ternary value that indicates a direction, as follows: 🧭

false: left-to-right direction ("ltr"). The text is expected to be displayed with left-to-right base direction if standalone and isolated with left-to-right direction (as if enclosed in LRI ... PDI or equivalent, see [Unicode-14.0.0-bidi]) in the context of a longer string or text. ➡️
true: right-to-left direction ("rtl"). The text is expected to be displayed with right-to-left base direction if standalone and isolated with right-to-left direction (as if enclosed in RLI ... PDI or equivalent, see [Unicode-14.0.0-bidi]) in the context of a longer string or text. ⬅️
null: indicates that no indication is made about the direction ("auto"), enabling an internationalization library to make an auto-detection decision such as treating the string as if enclosed in FSI ... PDI or equivalent, see [Unicode-14.0.0-bidi]. 🤖

If the third element is absent, directionality context may be applied (e.g., base-directionality information for an entire CBOR message or part thereof). 🧩 If there is no directionality context applied, the default interpretation is the same as for null ("auto"). 🫧

In CDDL:

tag38 = #6.38([tag38-ltag, text, ?tag38-direction])
tag38-ltag = text .regexp "[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*"
tag38-direction = &(ltr: false, rtl: true, auto: null)

NOTE: Language tags of any combination of case are allowed. 🔠 But Section 2.1.1 of [RFC5646], part of BCP 47, recommends a case combination for language tags that encoders that support tag 38 may wish to follow when generating language tags. 💅

Data items with tag 38 that do not meet the criteria above are not valid (see Section 5.3.2 of RFC 8949 [STD94]). 🚫

NOTE: The Unicode Standard [Unicode-14.0.0] includes a set of characters designed for tagging text (including language tagging) in the range U+E0000 to U+E007F. 🏷️ Although many applications, including RDF, do not disallow these characters in text strings, the Unicode Consortium has deprecated these characters and recommends annotating language via a higher-level protocol instead. 🙈 See the section "Deprecated Tag Characters" in Section 23.9 of [Unicode-14.0.0] as well as [RFC6082]. 📚

NOTE: while this document references a version of Unicode that was recent at the time of writing, the statements made based on this version are expected to remain valid for future versions. ⏳

A.3. Examples 🧁

Examples in this section are given in CBOR diagnostic notation first and then as a pretty-printed hexadecimal representation of the encoded item. 🔍

The following example shows how the English-language string "Hello" is represented. 👋

38(["en", "Hello"])

D8 26               # tag(38)
   82               # array(2)
      62            # text(2)
         656E       # "en"
      65            # text(5)
         48656C6C6F # "Hello"

The following example shows how the French-language string "Bonjour" is represented. 🥖

38(["fr", "Bonjour"])

D8 26                   # tag(38)
   82                   # array(2)
      62                # text(2)
         6672           # "fr"
      67                # text(7)
         426F6E6A6F7572 # "Bonjour"

The following example uses right-to-left (RTL) script, which in the context of this specification may be rendered differently by different document presentation environments. 🌀 The descriptive text may be more reliable to follow than the necessarily device- and application-specific rendering. ✍️ The example shows how the Hebrew-language string

שלום

is represented, where in direction of reading, the sequence of characters is: "ש" (HEBREW LETTER SHIN, U+05E9), "ל" (HEBREW LETTER LAMED, U+05DC), "ו" (HEBREW LETTER VAV, U+05D5), "ם" (HEBREW LETTER FINAL MEM, U+05DD). 🕍 Note the rtl direction expressed by setting the third element in the array to "true". 🎯

38(["he", "שלום", true])

D8 26                     # tag(38)
   83                     # array(3)
      62                  # text(2)
         6865             # "he"
      68                  # text(8)
         D7A9D79CD795D79D # "שלום"
      F5                  # primitive(21)

Appendix B. Interworking with RFC 7807 ✨

okay so sometimes you need to carry ("tunnel") [RFC7807] problem details inside a Concise Problem Details data item 🎀 this is that moment bestie

this appendix defines a Custom Problem Detail entry just for that. it's assigned Custom Problem Detail key 7807 in Section 6.2 💖 and its structure is:

tunnel-7807 = {
  ? &(type: 0) => ~uri
  ? &(status: 1) => 0..999
  * text => any
}

to carry an [RFC7807] problem details JSON object in a Concise Problem Details data item, you first convert the JSON object to CBOR as per Section 6.2 of RFC 8949 [STD94] 🦋 then create an empty Concise Problem Details data item 🌸

next, move the values for "title", "detail", and "instance", if they're present, from the [RFC7807] problem details over to the equivalent Standard Problem Detail entries ✨ then create a Custom Problem Detail entry with key 7807 💅 move the values for "type" and "status", if present, into the equivalent keys 0 and 1 of that Custom Problem Detail entry 👑 and finally move all the remaining key/value pairs (the additional members as per Section 3.2 of [RFC7807]) in the converted [RFC7807] problem details object into the Custom Problem Detail map unchanged 🫶

the inverse direction, carrying Concise Problem Details in an RFC 7807 problem details JSON object, is a little more involved 😭 it needs the additional support provided by [HTTPAPI], which is planned to create the HTTP Problem Types Registry 🧚 once that's in place, an HTTP Problem Type can be registered that pulls top-level items out of the Concise Problem Details data item in a similar way to the conversion above 🔥 and carries the rest of the Concise Problem Details data item in an additional member, encoded with base64url and no padding (Section 5 of [RFC4648]) 🌈 the details can be defined in a separate document once the work on [HTTPAPI] is done 💜

Acknowledgments

the authors would like to thank Mark Nottingham and Erik Wilde, the authors of RFC 7807 🙌 and Klaus Hartke and Jaime Jiménez, the coauthors of an earlier draft version of this specification 💖 plus Christian Amsüss, Marco Tiloca, Ari Keränen, and Michael Richardson for reviewing and commenting on this document 🫶 Francesca Palombini gets a huge thank you for her review (and support) as responsible AD, and so does Joel Jaeggli for his OPSDIR review 👑 both of them brought significant additional considerations to this document, and it's so much better because of them ✨

for Appendix A, John Cowan and Doug Ewell are also owed a shoutout 🎀 the content of an earlier draft version of that appendix was discussed on the "apps-discuss@ietf.org" and "ltru@ietf.org" mailing lists 🌸 more recently, the authors started a discussion about handling writing direction information together with language tags 🦋 which led to discussions within the W3C Internationalization Core Working Group 🌈 the authors want to acknowledge that cross-organization cooperation, plus the particular contributions from John Klensin and Addison Phillips and the specific text proposals by Martin Dürst 💅

Contributors

Peter Occil 🍓

Email: poccil14@gmail.com
URI:   http://peteroupc.github.io/CBOR/

Peter defined CBOR tag 38, which is the basis of Appendix A 💜

Christian Amsüss 🧚

Email: christian@amsuess.com

Christian contributed what became Section 3.1.1 ⭐

Authors' Addresses

Thomas Fossati 🦋

Arm Limited
Email: thomas.fossati@arm.com

Carsten Bormann 🌸

Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org

📦 where this page comes from

ietf: rfc9290 2022-10
💖 girlified by claude-haiku-5-5 on 2026-10-19: a language model's rewrite of the original, under its terms