Concise Problem Details For CoAP APIs

1.1. Requirements Language

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.¶

3.1. Standard Problem Detail Entries

Beyond the Standard Problem Detail keys defined in Figure 2, additional Standard Problem Detail keys can be registered for use in the standard-problem-detail-entries slot (see Section 5.1).¶

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. Custom Problem Detail Entries

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 (Section 5.2).¶

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 Figure 3.¶

{
  / 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"
  }
}

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 Figure 4.¶

{
  / 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 /

  /example value 4711 not actually registered like this:/
  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"
  }
}

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.¶

5.1. Standard Problem Detail Key registry

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].¶

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¶

Initial entries in this sub-registry are as follows:¶

5.2. Custom Problem Detail Key registry

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].¶

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¶

Initial entries in this sub-registry are as follows:¶

5.3. Media Type

IANA is requested to add the following Media-Type to the "Media Types" registry [IANA.media-types].¶

Type name:

application¶

Subtype name:

concise-problem-details+cbor¶

Required parameters:

none¶

Optional parameters:

none¶

Encoding considerations:

binary (CBOR data item)¶

Security considerations:

Section 4 of RFC XXXX¶

Interoperability considerations:

none¶

Published specification:

Section 5.3 of RFC XXXX¶

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 XXXX, there is no fragment identification syntax defined for "application/cbor".)¶

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¶

5.4. Content-Format

IANA is requested to register a Content-Format number in the "CoAP Content-Formats" sub-registry, within the "Constrained RESTful Environments (CoRE) Parameters" Registry [IANA.core-parameters], as follows:¶

TBD1 is to be assigned from the space 256..999.¶

In the registry as defined by Section 12.3 of [RFC7252] at the time of writing, the column "Content-Type" is called "Media type" and the column "Content Coding" is called "Encoding". This paragraph to be removed by RFC editor.¶

5.5. CBOR Tag 38

In the registry "CBOR Tags" [IANA.cbor-tags], IANA has registered CBOR Tag 38. IANA is requested to replace the reference for this registration with Appendix A, RFC XXXX.¶

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 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 under Best Current Practice 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, is a Boolean value that indicates a direction: false for "ltr" direction, true for "rtl" direction. If the third element is absent, no indication is made about the direction.¶

In CDDL:¶

tag38 = #6.38([tag38-ltag, text, ?tag38-direction])
tag38-ltag = text  .abnf ("Language-Tag" .det RFC5646)
tag38-direction = &(ltr: false, rtl: true)

RFC5646 = '
 Language-Tag  = langtag             ; normal language tags
               / privateuse          ; private use tag
               / legacy              ; legacy tags

 langtag       = language
                 ["-" script]
                 ["-" region]
                 *("-" variant)
                 *("-" extension)
                 ["-" privateuse]

 language      = 2*3ALPHA            ; shortest ISO 639 code
                 ["-" extlang]       ; sometimes followed by
                                     ; extended language subtags
               / 4ALPHA              ; or reserved for future use
               / 5*8ALPHA            ; or registered language subtag

 extlang       = 3ALPHA              ; selected ISO 639 codes
                 *2("-" 3ALPHA)      ; permanently reserved

 script        = 4ALPHA              ; ISO 15924 code

 region        = 2ALPHA              ; ISO 3166-1 code
               / 3DIGIT              ; UN M.49 code

 variant       = 5*8alphanum         ; registered variants
               / (DIGIT 3alphanum)

 extension     = singleton 1*("-" (2*8alphanum))

                                     ; Single alphanumerics
                                     ; "x" reserved for private use
 singleton     = DIGIT               ; 0 - 9
               / %x41-57             ; A - W
               / %x59-5A             ; Y - Z
               / %x61-77             ; a - w
               / %x79-7A             ; y - z

 privateuse    = "x" 1*("-" (1*8alphanum))

 legacy        = irregular / regular ; different word in RFC

 irregular     = "en-GB-oed" / "i-ami" / "i-bnn" / "i-default" /
               "i-enochian" / "i-hak" / "i-klingon" / "i-lux" /
               "i-mingo" / "i-navajo" / "i-pwn" / "i-tao" / "i-tay" /
               "i-tsu" / "sgn-BE-FR" / "sgn-BE-NL" / "sgn-CH-DE"

 regular       = "art-lojban" / "cel-gaulish" / "no-bok" / "no-nyn" /
               "zh-guoyu" / "zh-hakka" / "zh-min" / "zh-min-nan" /
               "zh-xiang"

 alphanum      = (ALPHA / DIGIT)     ; letters and numbers

 ALPHA         =  %x41-5A / %x61-7A  ; A-Z / a-z
 DIGIT         =  %x30-39            ; 0-9
'

NOTE: Language tags of any combination of case are allowed. But section 2.1.1 of [RFC5646], part of Best Current Practice 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 invalid (see Section 5.3.2 of [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].¶

A.3. Examples

Examples in this section are given in CBOR diagnostic mode, 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 shows how the Hebrew-language string "שלום" (HEBREW LETTER SHIN, HEBREW LETTER LAMED, HEBREW LETTER VAV, HEBREW LETTER FINAL MEM, U+05E9 U+05DC U+05D5 U+05DD) is represented. 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)