idnits 2.17.1 draft-fossati-core-coap-problem-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (20 November 2019) is 1618 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7807 (Obsoleted by RFC 9457) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group T. Fossati 3 Internet-Draft ARM 4 Intended status: Standards Track 20 November 2019 5 Expires: 23 May 2020 7 Problem Details For CoAP APIs 8 draft-fossati-core-coap-problem-00 10 Abstract 12 This document defines a "problem detail" as a way to carry machine- 13 readable details of errors in a CoAP response to avoid the need to 14 define new error response formats for CoAP APIs. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on 23 May 2020. 33 Copyright Notice 35 Copyright (c) 2019 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 40 license-info) in effect on the date of publication of this document. 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. Code Components 43 extracted from this document must include Simplified BSD License text 44 as described in Section 4.e of the Trust Legal Provisions and are 45 provided without warranty as described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2 51 2. CoAP Problem Details Definition . . . . . . . . . . . . . . . 3 52 2.1. CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 3. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3.1. Defining New Problem Types . . . . . . . . . . . . . . . 4 55 3.2. Defining New Problem Attributes . . . . . . . . . . . . . 5 56 4. Security Considerations . . . . . . . . . . . . . . . . . . . 5 57 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 58 5.1. Registration of a Content-Format identifier for 59 application/coap-problem+cbor . . . . . . . . . . . . . . 6 60 5.2. New Registries . . . . . . . . . . . . . . . . . . . . . 6 61 5.2.1. CoAP Problem Details Registry . . . . . . . . . . . . 6 62 5.2.2. CoAP Problem Namespace Registry . . . . . . . . . . . 7 63 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 6.1. Normative References . . . . . . . . . . . . . . . . . . 8 65 6.2. Informative References . . . . . . . . . . . . . . . . . 9 66 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 69 1. Introduction 71 CoAP [RFC7252] response codes are sometimes not sufficient to convey 72 enough information about an error to be helpful. 74 This specification defines a simple and extensible CBOR [RFC7049] 75 format to suit this purpose. It is designed to be reused by CoAP 76 APIs, which can identify distinct "problem types" specific to their 77 needs. 79 Thus, API clients can be informed of both the high-level error class 80 (using the response code) and the finer-grained details of the 81 problem (using this format). 83 The format presented is largely inspired by the Problem Details for 84 HTTP APIs defined in [RFC7807]. 86 1.1. Requirements Language 88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 90 "OPTIONAL" in this document are to be interpreted as described in 91 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 92 capitals, as shown here. 94 2. CoAP Problem Details Definition 96 A CoAP Problem Details is encoded as a CBOR map with the following 97 members: 99 * "ns" (int) - A code-point that defines the namespace under which 100 the "type" field needs to be interpreted. This is a mandatory 101 field. 103 * "type" (uint) - A code-point that identifies the problem type 104 within the namespace. This is a mandatory field. 106 * "title" (text) - A short, human-readable summary of the problem 107 type. It SHOULD NOT change from occurrence to occurrence of the 108 problem. 110 * "response-code" (8-bit uint) - The CoAP response code ([RFC7252], 111 Section 5.9) generated by the origin server for this occurrence of 112 the problem. 114 * "detail" (text) - A human-readable explanation specific to this 115 occurrence of the problem. 117 * "instance" (uri) - A URI reference that identifies the specific 118 occurrence of the problem. It may or may not yield further 119 information if dereferenced. 121 Consumers MUST use "ns" and "type" as primary identifiers for the 122 problem type; the "title" string is advisory and included only for 123 consumers who are not aware of the semantics of the "ns" and "type" 124 values. 126 The "response-code" member, if present, is only advisory; it conveys 127 the CoAP response code used for the convenience of the consumer. 128 Generators MUST use the same response code in the actual CoAP 129 response, to assure that generic CoAP software that does not 130 understand this format still behaves correctly. Consumers can use 131 the response-code member to determine what the original response code 132 used by the generator was, in cases where it has been changed (e.g., 133 by an intermediary or cache), and when message payloads persist 134 without CoAP information. Generic CoAP software will still use the 135 CoAP response code. 137 The "detail" member, if present, ought to focus on helping the client 138 correct the problem, rather than giving debugging information. 139 Consumers SHOULD NOT parse the "detail" member for information; 140 extensions (see Section 3.2) are more suitable and less error-prone 141 ways to obtain such information. 143 Note that "instance" accepts relative URIs; this means that it must 144 be resolved relative to the document's base URI, as per [RFC3986], 145 Section 5. 147 2.1. CDDL 149 The definition in CDDL format [RFC8610] of a Problem Details for CoAP 150 is provided in Figure 1. 152 coap-problem-details = { 153 ns => int, 154 type => uint, 155 ? title => text, 156 ? response-code => uint .size 1, 157 ? detail => text, 158 ? instance => uri, 159 * $$coap-problem-details-extension, 160 } 162 ns = 0 163 type = 1 164 title = 2 165 response-code = 3 166 detail = 4 167 instance = 5 169 Figure 1: CoAP Problem Details: CDDL Definition 171 3. Extensibility 173 The format presented can be extended at two separate points that 174 allow the definition of: 176 * New error type values (see Section 3.1); and 178 * New error attributes (see Section 3.2). 180 3.1. Defining New Problem Types 182 The mechanism for defining new problem types is designed to allow 183 private use, for example by organisations or projects, while at the 184 same time supporting the use of this error format in public protocols 185 and APIs, as well as ease of transition between the two - for example 186 if an API is first developed internally to an organisation and then 187 open-sourced. Another critical design objective is to enable 188 delegating the administration of the code-points space to entities 189 (and experts) that are "closer" to the actual usage and intended 190 meaning of the code-points. In fact, an explicit desiderata is to 191 avoid having experts looking over a very big and diverse semantic 192 space. 194 To meet these goal, new problem types are always defined (and have a 195 meaning) within a namespace. The namespace range is itself 196 partitioned in three separate sub-ranges: a completely private space, 197 one devoted to private organisations and projects, and a third one 198 used for public APIs and protocols. The rules for registering a new 199 namespace are outlined in Section 5.2.2. 201 The registration procedures for new problem types are not defined in 202 this document. At a minimum, though, new problem type definitions 203 SHOULD document: 205 1. A parent namespace; 207 2. Their own code-point; 209 3. A title that appropriately describes the problem type (think 210 short); and 212 4. The CoAP response-code for it to be used with. 214 A problem type definition may specify additional attributes on the 215 problem details map (see Section 3.2). 217 (Note: moving a set of error types from the private to the public 218 space needs only changing the namespace identifier while leaving all 219 error types the same.) 221 3.2. Defining New Problem Attributes 223 Problem type definitions MAY extend the problem details object with 224 additional attributes to convey additional, problem-specific 225 information. 227 Clients consuming problem details MUST ignore any such extensions 228 that they don't recognize; this allows problem types to evolve and 229 include additional information in the future. 231 CoAP Problem Details can be extended via the coap-problem-details- 232 extension CDDL socket (see Section 3.9 of [RFC8610]). 234 4. Security Considerations 236 The security and privacy considerations outlined in Section 5 of 237 [RFC7807] apply in full. 239 5. IANA Considerations 241 5.1. Registration of a Content-Format identifier for application/coap- 242 problem+cbor 244 This document requests that IANA registers the following Content- 245 Format to the "CoAP Content-Formats" sub-registry, within the 246 "Constrained RESTful Environments (CoRE) Parameters" registry, from 247 the Expert Review space (0..255): 249 +-------------------------------+----------+------+-----------+ 250 | Media Type | Encoding | ID | Reference | 251 +===============================+==========+======+===========+ 252 | application/coap-problem+cbor | -- | TBD1 | RFCthis | 253 +-------------------------------+----------+------+-----------+ 255 Table 1 257 5.2. New Registries 259 This document requests that IANA create the following new registries: 261 * CoAP Problem Namespaces (Section 5.2.2); 263 * CoAP Problem Details (Section 5.2.1). 265 5.2.1. CoAP Problem Details Registry 267 The "CoAP Problem Details" registry keeps track of the allocation of 268 the integer values used as index values in the coap-problem-details 269 CBOR map. 271 Future registrations for this registry are to be made based on 272 [RFC8126] as described in Table 2. 274 +------------------+-------------------------+ 275 | Range | Registration Procedures | 276 +==================+=========================+ 277 | 0...N | Standards Action | 278 +------------------+-------------------------+ 279 | N+1...4294967295 | Specification Required | 280 +------------------+-------------------------+ 282 Table 2: CoAP Problem Details Registration 283 Procedures 285 All negative values are reserved for Private Use. 287 Initial registrations for the "CoAP Problem Details" registry are 288 provided in Table 3. Assignments consist of an integer index value, 289 the item name, and a reference to the defining specification. 291 +-------+---------------+---------------+ 292 | Index | Index Name | Specification | 293 +=======+===============+===============+ 294 | 0 | ns | RFCthis | 295 +-------+---------------+---------------+ 296 | 1 | type | RFCthis | 297 +-------+---------------+---------------+ 298 | 2 | title | RFCthis | 299 +-------+---------------+---------------+ 300 | 3 | response-code | RFCthis | 301 +-------+---------------+---------------+ 302 | 4 | detail | RFCthis | 303 +-------+---------------+---------------+ 304 | 5 | instance | RFCthis | 305 +-------+---------------+---------------+ 307 Table 3: CoAP Problem Details Initial 308 Registrations 310 5.2.2. CoAP Problem Namespace Registry 312 The "CoAP Problem Namespace" registry keeps track of the problem 313 namespace values. 315 Future registrations for this registry are to be made based on 316 [RFC8126] as described in Table 4. 318 +------------------+-------------------------+ 319 | Range | Registration Procedures | 320 +==================+=========================+ 321 | -L...-1 | First Come First Served | 322 +------------------+-------------------------+ 323 | 0...M | Standards Action | 324 +------------------+-------------------------+ 325 | M+1...4294967295 | Specification Required | 326 +------------------+-------------------------+ 328 Table 4: CoAP Problem Types Registration 329 Procedures 331 All negative values less than L are reserved for Private Use. 333 The initial registration for the "CoAP Problem Namespace" registry is 334 provided in Table 5. Assignments consist of an integer index value, 335 the item name, and a reference to the defining specification. 337 +-------+------------------------+---------------+ 338 | Value | Description | Specification | 339 +=======+========================+===============+ 340 | 0 | The "global" namespace | RFCthis | 341 +-------+------------------------+---------------+ 343 Table 5: CoAP Problem Namespace Initial 344 Registrations 346 6. References 348 6.1. Normative References 350 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 351 Requirement Levels", BCP 14, RFC 2119, 352 DOI 10.17487/RFC2119, March 1997, 353 . 355 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 356 Resource Identifier (URI): Generic Syntax", STD 66, 357 RFC 3986, DOI 10.17487/RFC3986, January 2005, 358 . 360 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 361 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 362 October 2013, . 364 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 365 Application Protocol (CoAP)", RFC 7252, 366 DOI 10.17487/RFC7252, June 2014, 367 . 369 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 370 Writing an IANA Considerations Section in RFCs", BCP 26, 371 RFC 8126, DOI 10.17487/RFC8126, June 2017, 372 . 374 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 375 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 376 May 2017, . 378 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 379 Definition Language (CDDL): A Notational Convention to 380 Express Concise Binary Object Representation (CBOR) and 381 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 382 June 2019, . 384 6.2. Informative References 386 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 387 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 388 . 390 Acknowledgments 392 Mark Nottingham and Erik Wilde, authors of RFC 7807. Carsten Bormann 393 and Klaus Hartke for discussion on the problem space and 394 extensibility requirements. 396 Author's Address 398 Thomas Fossati 399 ARM 401 Email: thomas.fossati@arm.com