idnits 2.17.1 draft-ietf-core-problem-details-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 (May 13, 2020) is 1444 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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) == Outdated reference: A later version (-06) exists of draft-ietf-core-coral-03 == Outdated reference: A later version (-15) exists of draft-ietf-core-href-03 -- Obsolete informational reference (is this intentional?): RFC 7807 (Obsoleted by RFC 9457) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 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 J. Jimenez 5 Expires: November 14, 2020 K. Hartke 6 Ericsson 7 May 13, 2020 9 Problem Details For CoAP APIs 10 draft-ietf-core-problem-details-00 12 Abstract 14 This document defines a "problem detail" as a way to carry machine- 15 readable details of errors in a CoAP response to avoid the need to 16 define new error response formats for CoAP APIs. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on November 14, 2020. 35 Copyright Notice 37 Copyright (c) 2020 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 54 2. CoAP Problem Details Definition . . . . . . . . . . . . . . . 3 55 2.1. CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 3. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3.1. Defining New Problem Types . . . . . . . . . . . . . . . 5 58 3.2. Defining New Problem Attributes . . . . . . . . . . . . . 5 59 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 61 5.1. Registration of a Content-Format identifier for 62 application/coap-problem+cbor . . . . . . . . . . . . . . 6 63 5.2. New Registries . . . . . . . . . . . . . . . . . . . . . 6 64 5.2.1. CoAP Problem Details Registry . . . . . . . . . . . . 6 65 5.2.2. CoAP Problem Namespace Registry . . . . . . . . . . . 7 66 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 6.1. Normative References . . . . . . . . . . . . . . . . . . 8 68 6.2. Informative References . . . . . . . . . . . . . . . . . 9 69 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 9 70 A.1. Minimalist . . . . . . . . . . . . . . . . . . . . . . . 9 71 A.2. Full-Fledged . . . . . . . . . . . . . . . . . . . . . . 10 72 A.3. Full-Fledged with Extensions . . . . . . . . . . . . . . 10 73 Appendix B. Doing it with CoRAL . . . . . . . . . . . . . . . . 11 74 B.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 11 75 B.1.1. Minimalist . . . . . . . . . . . . . . . . . . . . . 11 76 B.1.2. Full-Fledged . . . . . . . . . . . . . . . . . . . . 12 77 B.1.3. Full-Fledged with Extensions . . . . . . . . . . . . 12 78 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 12 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 81 1. Introduction 83 CoAP [RFC7252] response codes are sometimes not sufficient to convey 84 enough information about an error to be helpful. 86 This specification defines a simple and extensible CBOR [RFC7049] 87 format to suit this purpose. It is designed to be reused by CoAP 88 APIs, which can identify distinct "problem types" specific to their 89 needs. 91 Thus, API clients can be informed of both the high-level error class 92 (using the response code) and the finer-grained details of the 93 problem (using this format). 95 The format presented is largely inspired by the Problem Details for 96 HTTP APIs defined in [RFC7807]. 98 1.1. Requirements Language 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 102 "OPTIONAL" in this document are to be interpreted as described in 103 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 104 capitals, as shown here. 106 2. CoAP Problem Details Definition 108 A CoAP Problem Details is encoded as a CBOR map with the following 109 members: 111 o "ns" (int) - A code-point that defines the namespace under which 112 the "type" field needs to be interpreted. This is a mandatory 113 field. 115 o "type" (uint) - A code-point that identifies the problem type 116 within the namespace. This is a mandatory field. 118 o "title" (text) - A short, human-readable summary of the problem 119 type. It SHOULD NOT change from occurrence to occurrence of the 120 problem. 122 o "response-code" (8-bit uint) - The CoAP response code ([RFC7252], 123 Section 5.9) generated by the origin server for this occurrence of 124 the problem. 126 o "detail" (text) - A human-readable explanation specific to this 127 occurrence of the problem. 129 o "instance" (uri) - A URI reference that identifies the specific 130 occurrence of the problem. It may or may not yield further 131 information if dereferenced. 133 Consumers MUST use "ns" and "type" as primary identifiers for the 134 problem type; the "title" string is advisory and included only for 135 consumers who are not aware of the semantics of the "ns" and "type" 136 values. 138 The "response-code" member, if present, is only advisory; it conveys 139 the CoAP response code used for the convenience of the consumer. 140 Generators MUST use the same response code in the actual CoAP 141 response, to assure that generic CoAP software that does not 142 understand this format still behaves correctly. Consumers can use 143 the response-code member to determine what the original response code 144 used by the generator was, in cases where it has been changed (e.g., 145 by an intermediary or cache), and when message payloads persist 146 without CoAP information (e.g., in an events log or analytics 147 database). Generic CoAP software will still use the CoAP response 148 code. 150 The "detail" member, if present, ought to focus on helping the client 151 correct the problem, rather than giving debugging information. 152 Consumers SHOULD NOT parse the "detail" member for information; 153 extensions (see Section 3.2) are more suitable and less error-prone 154 ways to obtain such information. 156 Note that "instance" accepts relative URIs; this means that it must 157 be resolved relative to the document's base URI, as per [RFC3986], 158 Section 5. 160 2.1. CDDL 162 The definition in CDDL format [RFC8610] of a Problem Details for CoAP 163 is provided in Figure 1. 165 coap-problem-details = { 166 ns => int, 167 type => uint, 168 ? title => text, 169 ? response-code => uint .size 1, 170 ? detail => text, 171 ? instance => uri, 172 * $$coap-problem-details-extension, 173 } 175 ns = 0 176 type = 1 177 title = 2 178 response-code = 3 179 detail = 4 180 instance = 5 182 Figure 1: CoAP Problem Details: CDDL Definition 184 3. Extensibility 186 The format presented can be extended at two separate points that 187 allow the definition of: 189 o New problem type values (see Section 3.1); and 191 o New problem attributes (see Section 3.2). 193 3.1. Defining New Problem Types 195 The mechanism for defining new problem types is designed to allow 196 private use, for example by organisations or projects, while at the 197 same time supporting the use of this error format in public protocols 198 and APIs, as well as ease of transition between the two - for example 199 if an API is first developed internally to an organisation and then 200 open-sourced. Another critical design objective is to enable 201 delegating the administration of the code-points space to entities 202 (and experts) that are "closer" to the actual usage and intended 203 meaning of the code-points. In fact, an explicit desiderata is to 204 avoid having experts looking over a very big and diverse semantic 205 space. 207 To meet these goal, new problem types are always defined (and have a 208 meaning) within a namespace. The namespace range is itself 209 partitioned in three separate sub-ranges: a completely private space, 210 one devoted to private organisations and projects, and a third one 211 used for public APIs and protocols. The rules for registering a new 212 namespace are outlined in Section 5.2.2. 214 The registration procedures for new problem types are not defined in 215 this document. At a minimum, though, new problem type definitions 216 SHOULD document: 218 1. A parent namespace; 220 2. Their own code-point; 222 3. A title that appropriately describes the problem type (think 223 short); and 225 4. The CoAP response-code for it to be used with. 227 A problem type definition may specify additional attributes on the 228 problem details map (see Section 3.2). 230 (Note on renumbering: moving a set of error types from the private to 231 the public space needs only changing the namespace identifier while 232 leaving all error types the same.) 234 3.2. Defining New Problem Attributes 236 Problem type definitions MAY extend the problem details object with 237 additional attributes to convey additional, problem-specific 238 information. 240 Clients consuming problem details MUST ignore any such extensions 241 that they do not recognize; this allows problem types to evolve and 242 include additional information in the future. 244 CoAP Problem Details can be extended via the coap-problem-details- 245 extension CDDL socket (see Section 3.9 of [RFC8610]). 247 4. Security Considerations 249 The security and privacy considerations outlined in Section 5 of 250 [RFC7807] apply in full. 252 5. IANA Considerations 254 5.1. Registration of a Content-Format identifier for application/coap- 255 problem+cbor 257 This document requests that IANA registers the following Content- 258 Format to the "CoAP Content-Formats" sub-registry, within the 259 "Constrained RESTful Environments (CoRE) Parameters" registry, from 260 the Expert Review space (0..255): 262 +-------------------------------+----------+------+-----------+ 263 | Media Type | Encoding | ID | Reference | 264 +-------------------------------+----------+------+-----------+ 265 | application/coap-problem+cbor | -- | TBD1 | RFCthis | 266 +-------------------------------+----------+------+-----------+ 268 5.2. New Registries 270 This document requests that IANA create the following new registries: 272 o CoAP Problem Namespaces (Section 5.2.2); 274 o CoAP Problem Details (Section 5.2.1). 276 5.2.1. CoAP Problem Details Registry 278 The "CoAP Problem Details" registry keeps track of the allocation of 279 the integer values used as index values in the coap-problem-details 280 CBOR map. 282 Future registrations for this registry are to be made based on 283 [RFC8126] as described in Table 1. 285 +------------------+-------------------------+ 286 | Range | Registration Procedures | 287 +------------------+-------------------------+ 288 | 0...N | Standards Action | 289 | | | 290 | N+1...4294967295 | Specification Required | 291 +------------------+-------------------------+ 293 Table 1: CoAP Problem Details Registration Procedures 295 All negative values are reserved for Private Use. 297 Initial registrations for the "CoAP Problem Details" registry are 298 provided in Table 2. Assignments consist of an integer index value, 299 the item name, and a reference to the defining specification. 301 +-------+---------------+---------------+ 302 | Index | Index Name | Specification | 303 +-------+---------------+---------------+ 304 | 0 | ns | RFCthis | 305 | | | | 306 | 1 | type | RFCthis | 307 | | | | 308 | 2 | title | RFCthis | 309 | | | | 310 | 3 | response-code | RFCthis | 311 | | | | 312 | 4 | detail | RFCthis | 313 | | | | 314 | 5 | instance | RFCthis | 315 +-------+---------------+---------------+ 317 Table 2: CoAP Problem Details Initial Registrations 319 5.2.2. CoAP Problem Namespace Registry 321 The "CoAP Problem Namespace" registry keeps track of the problem 322 namespace values. 324 Future registrations for this registry are to be made based on 325 [RFC8126] as described in Table 3. 327 +------------------+-------------------------+ 328 | Range | Registration Procedures | 329 +------------------+-------------------------+ 330 | -L...-1 | First Come First Served | 331 | | | 332 | 0...M | Standards Action | 333 | | | 334 | M+1...4294967295 | Specification Required | 335 +------------------+-------------------------+ 337 Table 3: CoAP Problem Types Registration Procedures 339 All negative values less than L are reserved for Private Use. 341 The "CoAP Problem Namespace" registry has three columns as shown in 342 Table 4. Assignments consist of an integer index value, the item 343 description, and a reference to the defining specification. 345 +-------+-------------+---------------+ 346 | Value | Description | Specification | 347 +-------+-------------+---------------+ 348 | empty | empty | empty | 349 +-------+-------------+---------------+ 351 Table 4: CoAP Problem Namespace Registry 353 The registry is initially empty. 355 6. References 357 6.1. Normative References 359 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 360 Requirement Levels", BCP 14, RFC 2119, 361 DOI 10.17487/RFC2119, March 1997, 362 . 364 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 365 Resource Identifier (URI): Generic Syntax", STD 66, 366 RFC 3986, DOI 10.17487/RFC3986, January 2005, 367 . 369 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 370 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 371 October 2013, . 373 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 374 Application Protocol (CoAP)", RFC 7252, 375 DOI 10.17487/RFC7252, June 2014, 376 . 378 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 379 Writing an IANA Considerations Section in RFCs", BCP 26, 380 RFC 8126, DOI 10.17487/RFC8126, June 2017, 381 . 383 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 384 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 385 May 2017, . 387 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 388 Definition Language (CDDL): A Notational Convention to 389 Express Concise Binary Object Representation (CBOR) and 390 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 391 June 2019, . 393 6.2. Informative References 395 [I-D.ietf-core-coral] 396 Hartke, K., "The Constrained RESTful Application Language 397 (CoRAL)", draft-ietf-core-coral-03 (work in progress), 398 March 2020. 400 [I-D.ietf-core-href] 401 Hartke, K., "Constrained Resource Identifiers", draft- 402 ietf-core-href-03 (work in progress), March 2020. 404 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 405 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 406 . 408 Appendix A. Examples 410 This section presents a series of examples in CBOR diagnostic 411 notation [RFC7049]. The examples are fictitious. No identification 412 with actual products is intended or should be inferred. All examples 413 involve the same CoAP problem type (5, with pretend semantics 414 "unknown key id") defined in the private namespace "-33455". 416 A.1. Minimalist 418 The example in Figure 2 has the most compact representation. By 419 avoiding any non-mandatory field, the Problem encodes to seven bytes 420 in total. This is suitable for a constrained receiver that happens 421 to have precise knowledge of the semantics associated with the 422 namespace and type code-points. 424 { 425 / ns / 0: -33455, / a private namespace / 426 / type / 1: 5 / "unknown key id" semantics / 427 } 429 Figure 2: Private Namespace: Minimal Payload 431 A.2. Full-Fledged 433 The example in Figure 3 has all the mandatory as well as the optional 434 fields populated. This format is appropriate for an unconstrained 435 receiver. For example, an edge gateway forwarding to a log server 436 that needs to gather as much contextual information as possible, 437 including details about the error condition, the associated CoAP 438 response code, and even the URL describing the specific error 439 instance. 441 { 442 / ns / 0: -33455, 443 / type / 1: 5, 444 / title / 2: "unknown key id", 445 / response-code / 3: 132, / 4.04 Not Found / 446 / detail / 4: "Key with id 0x01020304 not registered", 447 / instance / 5: 32("https://private-api.example/errors/5") 448 } 450 Figure 3: Private Namespace: Full Payload 452 A.3. Full-Fledged with Extensions 454 The last example (Figure 4) makes use of the built-in extension 455 mechanism described in Section 3.2 to provide some context specific 456 information - in this made up scenario a list of possible key ids is 457 provided to the receiving end. This richer format might be enabled 458 for debug or tracing purposes, possibly on a per-transaction basis. 459 Note that the map index for key-ids key is minted from the private 460 (negative) space. 462 { 463 / ns / 0: -33455, 464 / type / 1: 5, 465 / title / 2: "unknown key id", 466 / response-code / 3: 132, / 4.04 Not Found / 467 / detail / 4: "Key with id 0x01020304 not registered", 468 / instance / 5: 32("https://private-api.example/errors/5"), 469 / key-ids / -1: [ 0x01020300, 0x01020301, 0x01020302 ] 470 } 472 Figure 4: Private Namespace: Full Payload and Extension 474 Appendix B. Doing it with CoRAL 476 CoRAL [I-D.ietf-core-coral] provides a way to address the same 477 problem that is solved by the format described in this document. 478 (Refer to section 5.2.3 of [I-D.ietf-core-coral] for initial 479 discussion around CoRAL Error Responses.) 481 By abstracting the serialization aspects (CBOR, JSON, etc.), the 482 transport protocol (HTTP, CoAP, etc.) and its response codes, while 483 also providing compression of the involved resources, CoRAL can 484 potentially support a more general solution than the one discussed 485 here, in particular one that also supersedes [RFC7807]. 487 B.1. Examples 489 In this section, the examples from Appendix A are converted to CoRAL. 491 The main differences are: 493 o CoRAL is using an array of alternating keys and values instead of 494 a map with array values to get a multi-dict; 496 o CoRAL uses [I-D.ietf-core-href] as an alternative to URIs that is 497 optimized for constrained nodes; 499 o CoRAL uses its own code-point allocation scheme. 501 B.1.1. Minimalist 503 #using 504 #using ex = 506 type ex:unknown-key-id 508 B.1.2. Full-Fledged 510 #using 511 #using ex = 513 type ex:unknown-key-id 514 title "unknown key id" 515 response-code 132 516 detail "Key with id 0x01020304 not registered" 517 instance 519 B.1.3. Full-Fledged with Extensions 521 #using 522 #using ex = 524 type 5 525 title "unknown key id" 526 response-code 132 527 detail "Key with id 0x01020304 not registered" 528 instance 529 ex:key-id 0x01020300 530 ex:key-id 0x01020301 531 ex:key-id 0x01020302 533 Acknowledgments 535 Mark Nottingham and Erik Wilde, authors of RFC 7807. Carsten Bormann 536 and Klaus Hartke for discussion on the problem space and 537 extensibility requirements. 539 Authors' Addresses 541 Thomas Fossati 542 arm 544 Email: thomas.fossati@arm.com 546 Jaime Jimenez 547 Ericsson 549 Email: jaime@iki.fi 550 Klaus Hartke 551 Ericsson 553 Email: klaus.hartke@ericsson.com