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