Concise Problem Details For CoAP APIs

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 7 January 2023.¶

Copyright Notice

Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

REST response status information such as CoAP response codes (Section 5.9 of [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 "shapes" of these data items 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 the vocabulary defined here). This pattern of communication is illustrated in Figure 1.¶

The framework presented is largely inspired by the Problem Details for HTTP APIs defined in [RFC7807]. Appendix B discusses applications where interworking with [RFC7807] is required.¶

2. Basic Problem Details

A Concise Problem Details data item is a CBOR data item with the following structure (rules named starting 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

(Examples of elaborated Concise Problem Details data items can be found later in the document, e.g., Figure 3.)¶

A number of problem detail entries, the Standard Problem Detail entries, are predefined (more predefined details can be registered, see Section 3.1).¶

Note that, unlike [RFC7807], Concise Problem Details data items have no explicit "problem type". Instead, the category (or, one could say, Gestalt) of the problem can be understood from the shape of the problem details offered. We talk of 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 is not intended to summarize all the specific information given with the problem details. For instance, the summary might include that an account does not have enough money for a transaction to succeed, but not the detail information such as the account number, how much money that account has, and how much would be needed.¶

The detail (key -2):

A human-readable explanation specific to this occurrence of the problem.¶

The instance (key -3):

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.¶

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 (Section 5.1 of [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 (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 (not using tag 38) in this Concise Problem Details data item, see Appendix A.¶

Both "title" and "detail" can use either an unadorned CBOR text string (text) or a language-tagged text string (tag38); see Appendix A for the definition of the latter. Language tag and writing direction information for unadorned text strings are intended to be obtained from context; if that context needs to be saved or forwarded with a Concise Problem Details data item, "base-lang" and "base-rtl" can be used for that. If no such (explicitly saved or implicit) context information is available, unadorned text is interpreted with language-tag "en" and writing-direction "false" (ltr).¶

The "title" string is advisory and included to give consumers a shorthand for the category (problem shape) of the error encountered.¶

The "detail" member, if present, ought to focus on helping the client correct the problem, rather than giving extensive server-side debugging information. Consumers SHOULD NOT parse the "detail" member for information; extensions (see Section 3) are more suitable and less error-prone ways to obtain such information. Note that the "instance" URI reference may be relative; this means that it must be resolved relative to the representation's base URI, as per Section 5 of [STD66].¶

The "response-code" member, if present, is only advisory; it conveys the CoAP response code used for the convenience of the consumer. Generators MUST use the same response code here as in the actual CoAP response; the latter is needed to assure that generic CoAP software that does not understand the problem-details format still behaves correctly. Consumers can use the response-code member to determine what the original response code used by the generator was, in cases where it has been changed (e.g., by an intermediary or cache), and when message bodies persist without CoAP information (e.g., in an events log or analytics database). Generic CoAP software will still use the CoAP response code. To support the use case of message body persistence without support by the problem-details generator, the entity that persists the Concise Problem Details data item can copy over the CoAP response code that it received on the CoAP level. Note that the "response-code" value is a numeric representation of the actual code (see Section 3 of [RFC7252]), so it does not take the usual presentation form that resembles an HTTP status code -- 4.04 Not found is represented by the number 132.¶

The "base-uri" member is usually not present in the initial request-response communication as it can be inferred as per Section 5.1.3 of [STD66]. An entity that stores a Concise Problem Details data item or otherwise makes it available for consumers without this context might add in a base-uri member to allow those consumers to perform resolution of any relative URI references embedded in the data item.¶

3. Extending Concise Problem Details

This specification defines a generic problem details 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 Section 3.1.¶

Application-specific attributes will be allocated in the custom-problem-detail-entries slot according to the procedure described in Section 3.2.¶

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

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

4. Privacy Considerations

Problem details may unintentionally disclose information. This can lead to both privacy and security problems. See Section 5 for more details that apply to both domains; particular attention needs to be given to unintentionally 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). One reason is that dereferencing these can lead to information disclosure (tracking). Information disclosure can also be caused by URIs in problem details that are intended for dereferencing, e.g., the "instance" URI. Implementations need to consider which component of a client should perform the dereferencing, and which servers are trusted with serving them. In any case, the security considerations of Section 7 of [STD66] apply.¶

The security and privacy considerations outlined in Section 5 of [RFC7807] apply in full. While these are phrased in terms of security considerations for new RFC 7807 problem types, they equally apply to the problem detail entry definitions used here Section 3; in summary: both when defining new detail entries, and when actually generating a Concise Problem Details data item, care needs to be taken that they do not leak sensitive information. Entities storing or forwarding Concise Problem Details data items need to consider whether this leads to information being transferred out of the context within which access to sensitive information was acceptable. See also Section 3, Paragraph 6 (the last paragraph of the introduction to that section). Privacy-sensitive information in the problem details SHOULD NOT be obscured in ways that might lead to misclassification as non-sensitive (e.g., by base64-encoding).¶

6. IANA Considerations

RFC Editor: please replace RFC XXXX with the RFC number of this RFC and remove this note.¶

Appendix A. Language-Tagged Strings

This appendix serves as the archival documentation for CBOR Tag 38, a tag for serializing language-tagged text strings in CBOR. The text of this appendix is adapted from the specification text supplied for its initial registration. It has been extended to allow supplementing the language tag 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 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.¶

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)

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

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

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

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

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

On certain occasions, it will be necessary to carry ("tunnel") [RFC7807] problem details in a Concise Problem Details data item.¶

This appendix defines a Custom Problem Details entry for that purpose. This is assigned Custom Problem Detail key 7807 in Section 6.2. 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, first convert the JSON object to CBOR as per Section 6.2 of [STD94]. Create an empty Concise Problem Details data item.¶

Move the values for "title", "detail", and "instance", if present, from the [RFC7807] problem details to the equivalent Standard Problem Detail entries. Create a Custom Problem Details entry with key 7807. Move the values for "type" and "status", if present, to the equivalent keys 0 and 1 of the Custom Problem Details entry. Move all remaining key/value pairs (additional members as per Section 3.2 of [RFC7807]) in the converted [RFC7807] problem details object to the Custom Problem Details map unchanged.¶

The inverse direction, carrying Concise Problem Details in a Problem Details JSON object requires the additional support provided by [I-D.ietf-httpapi-rfc7807bis], which is planned to create the HTTP Problem Types Registry. An HTTP Problem Type can then be registered that extracts top-level items from the Concise Problem Details data item in a similar way to the conversion described above, and which carries the rest of the Concise Problem Details data item in an additional member via base64url encoding without padding (Section 5 of [RFC4648]). Details can be defined in a separate document when the work on [I-D.ietf-httpapi-rfc7807bis] is completed.¶

Acknowledgments

Mark Nottingham and Erik Wilde, authors of RFC 7807. Klaus Hartke and Jaime Jiménez, co-authors of an earlier generation of this specification. Christian Amsüss, Marco Tiloca, Ari Keränen and Michael Richardson for review and comments on this document. Francesca Palombini for her review (and support) as responsible AD, and Joel Jaeggli for his OPSDIR review, both of which brought significant additional considerations to this document.¶

For Appendix A, John Cowan and Doug Ewell are also to be acknowledged. The content of an earlier version of this appendix was also discussed in the "apps-discuss at ietf.org" and "ltru at ietf.org" mailing lists. More recently, the authors initiated a discussion about the handling of writing direction information in conjunction with language tags. That led to discussions within the W3C Internationalization Core Working Group. The authors would like to acknowledge that cross-organization cooperation and particular contributions from John Klensin and Addison Phillips, and specific text proposals by Martin Dürst.¶

Contributors

Peter defined CBOR tag 38, basis of Appendix A.¶

Christian contributed what became Section 3.1.1.¶

Authors' Addresses