idnits 2.17.1 draft-ietf-core-problem-details-07.txt: -(5): 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 10 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 (28 June 2022) is 669 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 7807 (Obsoleted by RFC 9457) == Outdated reference: A later version (-07) exists of draft-ietf-httpapi-rfc7807bis-03 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). 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 C. Bormann 5 Expires: 30 December 2022 Universität Bremen TZI 6 28 June 2022 8 Concise Problem Details For CoAP APIs 9 draft-ietf-core-problem-details-07 11 Abstract 13 This document defines a concise "problem detail" as a way to carry 14 machine-readable details of errors in a REST response to avoid the 15 need to define new error response formats for REST APIs for 16 constrained environments. The format is inspired by, but intended to 17 be more concise than, the Problem Details for HTTP APIs defined in 18 RFC 7807. 20 About This Document 22 This note is to be removed before publishing as an RFC. 24 Status information for this document may be found at 25 https://datatracker.ietf.org/doc/draft-ietf-core-problem-details/. 27 Discussion of this document takes place on the Constrained RESTful 28 Environments Working Group mailing list (mailto:core@ietf.org), which 29 is archived at https://mailarchive.ietf.org/arch/browse/core/. 31 Source for this draft and an issue tracker can be found at 32 https://github.com/core-wg/core-problem-details. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on 30 December 2022. 50 Copyright Notice 52 Copyright (c) 2022 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 57 license-info) in effect on the date of publication of this document. 58 Please review these documents carefully, as they describe your rights 59 and restrictions with respect to this document. Code Components 60 extracted from this document must include Revised BSD License text as 61 described in Section 4.e of the Trust Legal Provisions and are 62 provided without warranty as described in the Revised BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Terminology and Requirements Language . . . . . . . . . . 3 68 2. Basic Problem Details . . . . . . . . . . . . . . . . . . . . 4 69 3. Extending Concise Problem Details . . . . . . . . . . . . . . 6 70 3.1. Standard Problem Detail Entries . . . . . . . . . . . . . 7 71 3.1.1. Standard Problem Detail Entry: Unprocessed CoAP 72 Option . . . . . . . . . . . . . . . . . . . . . . . 7 73 3.2. Custom Problem Detail Entries . . . . . . . . . . . . . . 9 74 4. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12 75 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 77 6.1. Standard Problem Detail Key registry . . . . . . . . . . 12 78 6.2. Custom Problem Detail Key registry . . . . . . . . . . . 14 79 6.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 16 80 6.4. Content-Format . . . . . . . . . . . . . . . . . . . . . 16 81 6.5. CBOR Tag 38 . . . . . . . . . . . . . . . . . . . . . . . 17 82 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 83 7.1. Normative References . . . . . . . . . . . . . . . . . . 17 84 7.2. Informative References . . . . . . . . . . . . . . . . . 18 85 Appendix A. Language-Tagged Strings . . . . . . . . . . . . . . 19 86 A.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 20 87 A.2. Detailed Semantics . . . . . . . . . . . . . . . . . . . 20 88 A.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 21 89 Appendix B. Interworking with RFC 7807 . . . . . . . . . . . . . 22 90 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 23 91 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 23 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 94 1. Introduction 96 REST response status information such as CoAP response codes 97 (Section 5.9 of [RFC7252]) is sometimes not sufficient to convey 98 enough information about an error to be helpful. This specification 99 defines a simple and extensible framework to define CBOR [STD94] data 100 items to suit this purpose. It is designed to be reused by REST 101 APIs, which can identify distinct "shapes" of these data items 102 specific to their needs. Thus, API clients can be informed of both 103 the high-level error class (using the response code) and the finer- 104 grained details of the problem (using the vocabulary defined here). 105 This pattern of communication is illustrated in Figure 1. 107 .--------. .--------. 108 | CoAP | | CoAP | 109 | Client | | Server | 110 '----+---' '---+----' 111 | | 112 | Request | 113 o----------------->| 114 | | (failure) 115 |<-----------------o 116 | Error Response | 117 | with a CBOR | 118 | data item giving | 119 | Problem Details | 120 | | 122 Figure 1: Problem Details: Example with CoAP 124 The framework presented is largely inspired by the Problem Details 125 for HTTP APIs defined in [RFC7807]. Appendix B discusses 126 applications where interworking with [RFC7807] is required. 128 1.1. Terminology and Requirements Language 130 The terminology from [RFC7252], [STD94], and [RFC8610] applies; in 131 particular CBOR diagnostic notation is defined in Section 8 of 132 [STD94] and Appendix G of [RFC8610]. Readers are also expected to be 133 familiar with the terminology from [RFC7807]. 135 In this document, the structure of data is specified in CDDL 136 [RFC8610] [RFC9165]. 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in 141 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 142 capitals, as shown here. 144 2. Basic Problem Details 146 A Concise Problem Details data item is a CBOR data item with the 147 following structure (rules named starting with tag38 are defined in 148 Appendix A): 150 problem-details = non-empty<{ 151 ? &(title: -1) => oltext 152 ? &(detail: -2) => oltext 153 ? &(instance: -3) => ~uri 154 ? &(response-code: -4) => uint .size 1 155 ? &(base-uri: -5) => ~uri 156 ? &(base-lang: -6) => tag38-ltag 157 ? &(base-rtl: -7) => tag38-direction 158 standard-problem-detail-entries 159 custom-problem-detail-entries 160 }> 162 standard-problem-detail-entries = ( 163 * nint => any 164 ) 166 custom-problem-detail-entries = ( 167 * (uint/~uri) => { + any => any } 168 ) 170 non-empty = (M) .and ({ + any => any }) 172 oltext = text / tag38 174 Figure 2: Structure of Concise Problem Details Data Item 176 (Examples of elaborated Concise Problem Details data items can be 177 found later in the document, e.g., Figure 3.) 179 A number of problem detail entries, the Standard Problem Detail 180 entries, are predefined (more predefined details can be registered, 181 see Section 3.1). 183 Note that, unlike [RFC7807], Concise Problem Details data items have 184 no explicit "problem type". Instead, the category (or, one could 185 say, Gestalt) of the problem can be understood from the shape of the 186 problem details offered. We talk of a "problem shape" for short. 188 The title (key -1): 189 A short, human-readable summary of the problem shape. Beyond the 190 shape of the problem, it is not intended to summarize all the 191 specific information given with the problem details. For 192 instance, the summary might include that an account does not have 193 enough money for a transaction to succeed, but not the detail 194 information such as the account number, how much money that 195 account has, and how much would be needed. 197 The detail (key -2): 198 A human-readable explanation specific to this occurrence of the 199 problem. 201 The instance (key -3): 202 A URI reference that identifies the specific occurrence of the 203 problem. It may or may not yield further information if 204 dereferenced. 206 The response-code (key -4): 207 The CoAP response code (Sections 5.9 and 12.1.2 of [RFC7252]) 208 generated by the origin server for this occurrence of the problem. 210 The base-uri (key -5): 211 The base URI (Section 5.1 of [STD66]) that should be used to 212 resolve relative URI references embedded in this Concise Problem 213 Details data item. 215 The base-lang (key -6): 216 The language-tag (tag38-ltag) that applies to the presentation of 217 unadorned text strings (not using tag 38) in this Concise Problem 218 Details data item, see Appendix A. 220 The base-rtl (key -7): 221 The writing-direction (tag38-direction) that applies to the 222 presentation of unadorned text strings (not using tag 38) in this 223 Concise Problem Details data item, see Appendix A. 225 Both "title" and "detail" can use either an unadorned CBOR text 226 string (text) or a language-tagged text string (tag38); see 227 Appendix A for the definition of the latter. Language tag and 228 writing direction information for unadorned text strings are intended 229 to be obtained from context; if that context needs to be saved or 230 forwarded with a Concise Problem Details data item, "base-lang" and 231 "base-rtl" can be used for that. If no such (explicitly saved or 232 implicit) context information is available, unadorned text is 233 interpreted with language-tag "en" and writing-direction "false" 234 (ltr). 236 The "title" string is advisory and included to give consumers a 237 shorthand for the category (problem shape) of the error encountered. 239 The "detail" member, if present, ought to focus on helping the client 240 correct the problem, rather than giving extensive server-side 241 debugging information. Consumers SHOULD NOT parse the "detail" 242 member for information; extensions (see Section 3) are more suitable 243 and less error-prone ways to obtain such information. Note that the 244 "instance" URI reference may be relative; this means that it must be 245 resolved relative to the representation's base URI, as per Section 5 246 of [STD66]. 248 The "response-code" member, if present, is only advisory; it conveys 249 the CoAP response code used for the convenience of the consumer. 250 Generators MUST use the same response code here as in the actual CoAP 251 response; the latter is needed to assure that generic CoAP software 252 that does not understand the problem-details format still behaves 253 correctly. Consumers can use the response-code member to determine 254 what the original response code used by the generator was, in cases 255 where it has been changed (e.g., by an intermediary or cache), and 256 when message bodies persist without CoAP information (e.g., in an 257 events log or analytics database). Generic CoAP software will still 258 use the CoAP response code. To support the use case of message body 259 persistence without support by the problem-details generator, the 260 entity that persists the Concise Problem Details data item can copy 261 over the CoAP response code that it received on the CoAP level. Note 262 that the "response-code" value is a numeric representation of the 263 actual code (see Section 3 of [RFC7252]), so it does not take the 264 usual presentation form that resembles an HTTP status code -- 4.04 265 Not found is represented by the number 132. 267 The "base-uri" member is usually not present in the initial request- 268 response communication as it can be inferred as per Section 5.1.3 of 269 [STD66]. An entity that stores a Concise Problem Details data item 270 or otherwise makes it available for consumers without this context 271 might add in a base-uri member to allow those consumers to perform 272 resolution of any relative URI references embedded in the data item. 274 3. Extending Concise Problem Details 276 This specification defines a generic problem details container with 277 only a minimal set of attributes to make it usable. 279 It is expected that applications will extend the base format by 280 defining new attributes. 282 These new attributes fall into two categories: generic and 283 application specific. 285 Generic attributes will be allocated in the standard-problem-detail- 286 entries slot according to the registration procedure defined in 287 Section 3.1. 289 Application-specific attributes will be allocated in the custom- 290 problem-detail-entries slot according to the procedure described in 291 Section 3.2. 293 Consumers of a Concise Problem Details data item MUST ignore any 294 Standard or Custom Problem Detail entries, or keys inside the Custom 295 Problem Detail entries, that they do not recognize ("ignore-unknown 296 rule"); this allows problem details to evolve. When storing the data 297 item for future use or forwarding it to other consumers, it is 298 strongly RECOMMENDED to retain the unrecognized entries; exceptions 299 might be when storage/forwarding occurs in a different format/ 300 protocol that cannot accommodate them, or when the storage/forwarding 301 function needs to filter out privacy-sensitive information and for 302 that needs to assume unrecognized entries might be privacy-sensitive. 304 3.1. Standard Problem Detail Entries 306 Beyond the Standard Problem Detail keys defined in Figure 2, 307 additional Standard Problem Detail keys can be registered for use in 308 the standard-problem-detail-entries slot (see Section 6.1). 310 Standard Problem Detail keys are negative integers, so they can never 311 conflict with Custom Problem Detail keys defined for a specific 312 application domain (which are unsigned integers or URIs.) 314 In summary, the keys for Standard Problem Detail entries are in a 315 global namespace that is not specific to a particular application 316 domain. 318 3.1.1. Standard Problem Detail Entry: Unprocessed CoAP Option 320 Section 2 provides a number of generally applicable Standard Problem 321 Detail Entries. The present section both registers another useful 322 Standard Problem Detail entry and serves as an example of a Standard 323 Problem Detail Entry registration, in the registration template 324 format that would be ready for registration. 326 | Key Value: TBD (assigned at registration) 327 | 328 | Name: unprocessed-coap-option 329 | 330 | CDDL type: one-or-more, where 331 | 332 | one-or-more = T / [ 2* T ] 333 | 334 | Brief description: Option number(s) of CoAP option(s) that were 335 | not understood 336 | 337 | Specification reference: Section 3.1.1 of RFC XXXX 339 // RFC Editor: please replace RFC XXXX with the RFC number of this 340 // RFC and remove this note. 342 The specification of the Standard Problem Detail entry referenced by 343 the above registration template follows: 345 The Standard Problem Detail entry unprocessed-coap-option provides 346 the option number(s) of CoAP option(s) present in the request that 347 could not be processed by the server. 349 This may be a critical option that the server is unaware of, or an 350 option the server is aware of but could not process (and chose not 351 to, or was not allowed to, ignore it). 353 The Concise Problem Details data item including this Standard Problem 354 Detail Entry can be used in fulfillment of the "SHOULD" requirement 355 in Section 5.4.1 of [RFC7252]. 357 Several option numbers may be given in a list (in no particular 358 order), without any guarantee that the list is a complete 359 representation of all the problems in the request (as the server 360 might have stopped processing already at one of the problematic 361 options). If an option with the given number was repeated, there is 362 no indication which of the values caused the error. 364 Clients need to expect seeing options in the list they did not send 365 in the request; this can happen if the request traversed a proxy that 366 added the option but did not act on the problem details response 367 being returned by the origin server. 369 Note that for a few special values of unprocessed CoAP options (such 370 as Accept or Proxy-Uri), there are special response codes (4.06 Not 371 Acceptable, 5.05 Proxying Not Supported, respectively) to be sent 372 instead of 4.02 Bad Option. 374 3.2. Custom Problem Detail Entries 376 Applications may extend the Problem Details data item with additional 377 entries to convey additional, application-specific information. 379 Such new entries are allocated in the custom-problem-detail-entries 380 slot, and carry a nested map specific to that application. The map 381 key can either be an (absolute!) URI (under control of the entity 382 defining this extension), or an unsigned integer. Only the latter 383 needs to be registered (Section 6.2). 385 Within the nested map, any number of attributes can be given for a 386 single extension. The semantics of each custom attribute MUST be 387 described in the documentation for the extension; for extensions that 388 are registered (i.e., are identified by an unsigned int) that 389 documentation goes along with the registration. 391 The unsigned integer form allows a more compact representation. In 392 exchange, authors are expected to comply with the required 393 registration and documentation process. In comparison, the URI form 394 is less space-efficient but requires no registration. It is 395 therefore useful for experimenting during the development cycle and 396 for applications deployed in environments where producers and 397 consumers of Concise Problem Details are more tightly integrated. 398 (The URI form thus covers the potential need we might otherwise have 399 for a "private use" range for the unsigned integers.) 401 Note that the URI given for the extension is for identification 402 purposes only and, even if dereferenceable in principle, it MUST NOT 403 be dereferenced in the normal course of handling problem details 404 (i.e., outside diagnostic/debugging procedures involving humans). 406 Figure 3 shows an example (in CBOR diagnostic notation) of a custom 407 extension using a (made-up) URI as custom-problem-detail-entries key. 409 { 410 / title / -1: "title of the error", 411 / detail / -2: "detailed information about the error", 412 / instance / -3: "coaps://pd.example/FA317434", 413 / response-code / -4: 128, / 4.00 / 415 "tag:3gpp.org,2022-03:TS29112": { 416 / cause / 0: "machine-readable error cause", 417 / invalidParams / 1: [ 418 [ 419 / param / "first parameter name", 420 / reason / "must be a positive integer" 421 ], 422 [ 423 / param / "second parameter name" 424 ] 425 ], 426 / supportedFeatures / 2: "d34db33f" 427 } 428 } 430 Figure 3: Example Extension with URI key 432 Obviously, an SDO like 3GPP can also easily register such a custom 433 problem detail entry to receive a more efficient unsigned integer 434 key; Figure 4 shows how the same example would look like using a 435 (made-up) registered unsigned int as custom-problem-detail-entries 436 key: 438 { 439 / title / -1: "title of the error", 440 / detail / -2: "detailed information about the error", 441 / instance / -3: "coaps://pd.example/FA317434", 442 / response-code / -4: 128, / 4.00 / 444 /4711 is made-up example key that is not actually registered:/ 445 4711: { 446 / cause / 0: "machine-readable error cause", 447 / invalidParams / 1: [ 448 [ 449 / param / "first parameter name", 450 / reason / "must be a positive integer" 451 ], 452 [ 453 / param / "second parameter name" 454 ] 455 ], 456 / supportedFeatures / 2: "d34db33f" 457 } 458 } 460 Figure 4: Example Extension with unsigned int (registered) key 462 In summary, the keys for the maps used inside Custom Problem Detail 463 entries are defined specifically to the identifier of that Custom 464 Problem Detail entry, the documentation of which defines these 465 internal entries, typically chosen to address a given application 466 domain. 468 When there is a need to evolve a Custom Problem Detail entry 469 definition, the "ignore-unknown rule" discussed in the introduction 470 to Section 3 provides an easy way to include additional information. 471 The assumption is that this is done in a backward and forward 472 compatible way. Sometimes, Custom Problem Detail entries may need to 473 evolve in a way where forward compatibility by applying the "ignore- 474 unknown rule" would not be appropriate: e.g., when adding a "must- 475 understand" member, which can only be ignored at the peril of 476 misunderstanding the Concise Problem Details data item ("false 477 interoperability"). In this case, a new Custom Problem Detail key 478 can simply be registered for this case, keeping the old key backward 479 and forward compatible. 481 4. Privacy Considerations 483 Problem details may unintentionally disclose information. This can 484 lead to both privacy and security problems. See Section 5 for more 485 details that apply to both domains; particular attention needs to be 486 given to unintentionally disclosing Personally Identifiable 487 Information (PII). 489 5. Security Considerations 491 Concise Problem Details can contain URIs that are not intended to be 492 dereferenced (Section 3.2, Paragraph 5). One reason is that 493 dereferencing these can lead to information disclosure (tracking). 494 Information disclosure can also be caused by URIs in problem details 495 that _are_ intended for dereferencing, e.g., the "instance" URI. 496 Implementations need to consider which component of a client should 497 perform the dereferencing, and which servers are trusted with serving 498 them. In any case, the security considerations of Section 7 of 499 [STD66] apply. 501 The security and privacy considerations outlined in Section 5 of 502 [RFC7807] apply in full. While these are phrased in terms of 503 security considerations for new RFC 7807 problem types, they equally 504 apply to the problem detail entry definitions used here Section 3; in 505 summary: both when defining new detail entries, and when actually 506 generating a Concise Problem Details data item, care needs to be 507 taken that they do not leak sensitive information. Entities storing 508 or forwarding Concise Problem Details data items need to consider 509 whether this leads to information being transferred out of the 510 context within which access to sensitive information was acceptable. 511 See also Section 3, Paragraph 6 (the last paragraph of the 512 introduction to that section). Privacy-sensitive information in the 513 problem details SHOULD NOT be obscured in ways that might lead to 514 misclassification as non-sensitive (e.g., by base64-encoding). 516 6. IANA Considerations 518 // RFC Editor: please replace RFC XXXX with the RFC number of this 519 // RFC and remove this note. 521 6.1. Standard Problem Detail Key registry 523 This specification defines a new sub-registry for Standard Problem 524 Detail Keys in the CoRE Parameters registry [IANA.core-parameters], 525 with the policy "specification required" (Section 4.6 of [RFC8126]). 527 Each entry in the registry must include: 529 Key value: 530 a negative integer to be used as the value of the key 532 Name: 533 a name that could be used in implementations for the key 535 CDDL type: 536 type of the data associated with the key in CDDL notation 538 Brief description: 539 a brief description 541 Change Controller: 542 (see Section 2.3 of [RFC8126]) 544 Reference: 545 a reference document 547 The expert is requested to assign the shortest key values (1+0 and 548 1+1 encoding) to registrations that are likely to enjoy wide use and 549 can benefit from short encodings. 551 To be immediately useful in CDDL and programming language contexts, a 552 name consists of a lower-case ASCII letter (a-z) and zero or more 553 additional ASCII characters that are either lower-case letters, 554 digits, or a hyphen-minus, i.e., it matches [a-z][-a-z0-9]*. As with 555 the key values, names need to be unique. 557 The specification in the reference document needs to provide a 558 description of the Standard Problem Detail entry, replicating the 559 CDDL description in "CDDL type", and describing the semantics of the 560 presence of this entry and the semantics of the value given with it. 562 Initial entries in this sub-registry are as follows: 564 +=======+==============+=================+=============+===========+ 565 | Key | Name | CDDL Type | Brief | Reference | 566 | value | | | description | | 567 +=======+==============+=================+=============+===========+ 568 | -1 | title | text / tag38 | short, | RFC XXXX | 569 | | | | human- | | 570 | | | | readable | | 571 | | | | summary of | | 572 | | | | the problem | | 573 | | | | shape | | 574 +-------+--------------+-----------------+-------------+-----------+ 575 | -2 | detail | text / tag38 | human- | RFC XXXX | 576 | | | | readable | | 577 | | | | explanation | | 578 | | | | specific to | | 579 | | | | this | | 580 | | | | occurrence | | 581 | | | | of the | | 582 | | | | problem | | 583 +-------+--------------+-----------------+-------------+-----------+ 584 | -3 | instance | ~uri | URI | RFC XXXX | 585 | | | | reference | | 586 | | | | identifying | | 587 | | | | specific | | 588 | | | | occurrence | | 589 | | | | of the | | 590 | | | | problem | | 591 +-------+--------------+-----------------+-------------+-----------+ 592 | -4 | response- | uint .size 1 | CoAP | RFC XXXX | 593 | | code | | response | | 594 | | | | code | | 595 +-------+--------------+-----------------+-------------+-----------+ 596 | -5 | base-uri | ~uri | Base URI | RFC XXXX | 597 +-------+--------------+-----------------+-------------+-----------+ 598 | -6 | base-lang | tag38-ltag | Base | RFC XXXX | 599 | | | | language | | 600 | | | | tag (see | | 601 | | | | Appendix A) | | 602 +-------+--------------+-----------------+-------------+-----------+ 603 | -7 | base-rtl | tag38-direction | Base | RFC XXXX | 604 | | | | writing | | 605 | | | | direction | | 606 | | | | (see | | 607 | | | | Appendix A) | | 608 +-------+--------------+-----------------+-------------+-----------+ 609 | TBD | unprocessed- | one-or- | Option | RFC XXXX, | 610 | | coap-option | more | number(s) | Section | 611 | | | | of CoAP | 3.1.1 | 612 | | | | option(s) | | 613 | | | | that were | | 614 | | | | not | | 615 | | | | understood | | 616 +-------+--------------+-----------------+-------------+-----------+ 618 Table 1: Initial Entries in the Standard Problem Detail Key registry 620 6.2. Custom Problem Detail Key registry 622 This specification defines a new sub-registry for Custom Problem 623 Detail Keys in the CoRE Parameters registry [IANA.core-parameters], 624 with the policy "expert review" (Section 4.5 of [RFC8126]). 626 The expert is instructed to attempt making the registration 627 experience as close to first-come-first-served as reasonably 628 achievable, but checking that the reference document does provide a 629 description as set out below. (This requirement is a relaxed version 630 of "specification required" as defined in Section 4.6 of [RFC8126].) 632 Each entry in the registry must include: 634 Key value: 635 an unsigned integer to be used as the value of the key 637 Name: 638 a name that could be used in implementations for the key 640 Brief description: 641 a brief description 643 Change Controller: 644 (see Section 2.3 of [RFC8126]) 646 Reference: 647 a reference document that provides a description of the map, 648 including a CDDL description, that describes all inside keys and 649 values 651 The expert is requested to assign the shortest key values (1+0 and 652 1+1 encoding) to registrations that are likely to enjoy wide use and 653 can benefit from short encodings. 655 To be immediately useful in CDDL and programming language contexts, a 656 name consists of a lower-case ASCII letter (a-z) and zero or more 657 additional ASCII characters that are either lower-case letters, 658 digits, or a hyphen-minus, i.e., it matches [a-z][-a-z0-9]*. As with 659 the key values, names need to be unique. 661 Initial entries in this sub-registry are as follows: 663 +=======+=============+===========================+===========+ 664 | Key | Name | Brief description | Reference | 665 | value | | | | 666 +=======+=============+===========================+===========+ 667 | 7807 | tunnel-7807 | Carry RFC 7807 problem | RFC XXXX, | 668 | | | details in a Concise | Appendix | 669 | | | Problem Details data item | B | 670 +-------+-------------+---------------------------+-----------+ 672 Table 2: Initial Entries in the Custom Problem Detail Key 673 registry 675 6.3. Media Type 677 IANA is requested to add the following Media-Type to the "Media 678 Types" registry [IANA.media-types]. 680 +============================+============================+=========+ 681 |Name |Template |Reference| 682 +============================+============================+=========+ 683 |concise-problem-details+cbor|application/concise-problem-|RFC XXXX,| 684 | |details+cbor |Section | 685 | | |6.3 | 686 +----------------------------+----------------------------+---------+ 688 Table 3: New Media Type application/concise-problem-details+cbor 690 Type name: application 691 Subtype name: concise-problem-details+cbor 692 Required parameters: N/A 693 Optional parameters: N/A 694 Encoding considerations: binary (CBOR data item) 695 Security considerations: Section 5 of RFC XXXX 696 Interoperability considerations: none 697 Published specification: Section 6.3 of RFC XXXX 698 Applications that use this media type: Clients and servers in the 699 Internet of Things 700 Fragment identifier considerations: The syntax and semantics of 701 fragment identifiers is as specified for "application/cbor". (At 702 publication of RFC XXXX, there is no fragment identification 703 syntax defined for "application/cbor".) 704 Person & email address to contact for further information: CoRE WG 705 mailing list (core@ietf.org), or IETF Applications and Real-Time 706 Area (art@ietf.org) 707 Intended usage: COMMON 708 Restrictions on usage: none 709 Author/Change controller: IETF 710 Provisional registration: no 712 6.4. Content-Format 714 IANA is requested to register a Content-Format number in the "CoAP 715 Content-Formats" sub-registry, within the "Constrained RESTful 716 Environments (CoRE) Parameters" Registry [IANA.core-parameters], as 717 follows: 719 +==============================+================+======+===========+ 720 | Content-Type | Content Coding | ID | Reference | 721 +==============================+================+======+===========+ 722 | application/concise-problem- | - | TBD1 | RFC XXXX | 723 | details+cbor | | | | 724 +------------------------------+----------------+------+-----------+ 726 Table 4: New Content-Format 728 TBD1 is to be assigned from the space 256..999. 730 In the registry as defined by Section 12.3 of [RFC7252] at the time 731 of writing, the column "Content-Type" is called "Media type" and the 732 column "Content Coding" is called "Encoding". 733 // This paragraph to be removed by RFC editor. 735 6.5. CBOR Tag 38 737 In the registry "CBOR Tags" [IANA.cbor-tags], IANA has registered 738 CBOR Tag 38. IANA is requested to replace the reference for this 739 registration with Appendix A, RFC XXXX. 741 7. References 743 7.1. Normative References 745 [IANA.cbor-tags] 746 IANA, "Concise Binary Object Representation (CBOR) Tags", 747 19 September 2013, 748 . 750 [IANA.core-parameters] 751 IANA, "Constrained RESTful Environments (CoRE) 752 Parameters", 8 June 2012, 753 . 755 [IANA.media-types] 756 IANA, "Provisional Standard Media Type Registry", 20 July 757 2012, . 760 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 761 Requirement Levels", BCP 14, RFC 2119, 762 DOI 10.17487/RFC2119, March 1997, 763 . 765 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 766 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 767 2006, . 769 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 770 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 771 September 2009, . 773 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 774 Application Protocol (CoAP)", RFC 7252, 775 DOI 10.17487/RFC7252, June 2014, 776 . 778 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 779 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 780 . 782 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 783 Writing an IANA Considerations Section in RFCs", BCP 26, 784 RFC 8126, DOI 10.17487/RFC8126, June 2017, 785 . 787 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 788 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 789 May 2017, . 791 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 792 Definition Language (CDDL): A Notational Convention to 793 Express Concise Binary Object Representation (CBOR) and 794 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 795 June 2019, . 797 [RFC9165] Bormann, C., "Additional Control Operators for the Concise 798 Data Definition Language (CDDL)", RFC 9165, 799 DOI 10.17487/RFC9165, December 2021, 800 . 802 [STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 803 Resource Identifier (URI): Generic Syntax", STD 66, 804 RFC 3986, DOI 10.17487/RFC3986, January 2005, 805 . 807 [STD94] Bormann, C. and P. Hoffman, "Concise Binary Object 808 Representation (CBOR)", STD 94, RFC 8949, 809 DOI 10.17487/RFC8949, December 2020, 810 . 812 7.2. Informative References 814 [I-D.ietf-httpapi-rfc7807bis] 815 Nottingham, M., Wilde, E., and S. Dalal, "Problem Details 816 for HTTP APIs", Work in Progress, Internet-Draft, draft- 817 ietf-httpapi-rfc7807bis-03, 25 May 2022, 818 . 821 [RDF] Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 822 Concepts and Abstract Syntax", W3C Recommendation, 25 823 February 2014, 824 . 826 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 827 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 828 . 830 [RFC6082] Whistler, K., Adams, G., Duerst, M., Presuhn, R., Ed., and 831 J. Klensin, "Deprecating Unicode Language Tag Characters: 832 RFC 2482 is Historic", RFC 6082, DOI 10.17487/RFC6082, 833 November 2010, . 835 [Unicode-14.0.0] 836 The Unicode Consortium, "The Unicode Standard, Version 837 14.0.0", Mountain View: The Unicode Consortium, 838 ISBN 978-1-936213-29-0, September 2021, 839 . Note 840 that while this document references a version that was 841 recent at the time of writing, the statements made based 842 on this version are expected to remain valid for future 843 versions. 845 [Unicode-14.0.0-bidi] 846 The Unicode Consortium, "Unicode® Standard Annex #9 --- 847 Unicode Bidirectional Algorithm", 27 August 2021, 848 . Note that while this 850 document references a version that was recent at the time 851 of writing, the statements made based on this version are 852 expected to remain valid for future versions. 854 Appendix A. Language-Tagged Strings 856 This appendix serves as the archival documentation for CBOR Tag 38, a 857 tag for serializing language-tagged text strings in CBOR. The text 858 of this appendix is adapted from the specification text supplied for 859 its initial registration. It has been extended to allow 860 supplementing the language tag by a direction indication. 862 A.1. Introduction 864 In some cases it is useful to specify the natural language of a text 865 string. This specification defines a tag that does just that. One 866 technology that supports language-tagged strings is the Resource 867 Description Framework (RDF) [RDF]. 869 A.2. Detailed Semantics 871 A language-tagged string in CBOR has the tag 38 and consists of an 872 array with a length of 2 or 3. 874 The first element is a well-formed language tag under Best Current 875 Practice 47 ([RFC5646] and [RFC4647]), represented as a UTF-8 text 876 string (major type 3). 878 The second element is an arbitrary UTF-8 text string (major type 3). 879 Both the language tag and the arbitrary string can optionally be 880 annotated with CBOR tags; this is not shown in the CDDL below. 882 The optional third element, if present, represents a ternary value 883 that indicates a direction, as follows: 885 * false: left-to-right direction ("ltr"). The text is expected to 886 be displayed with left-to-right base direction if standalone, and 887 isolated with left-to-right direction (as if enclosed in LRI ... 888 PDI or equivalent, see [Unicode-14.0.0-bidi]) in the context of a 889 longer string or text. 891 * true: right-to-left direction ("rtl"). The text is expected to be 892 displayed with right-to-left base direction if standalone, and 893 isolated with right-to-left direction (as if enclosed in RLI ... 894 PDI or equivalent, see [Unicode-14.0.0-bidi]) in the context of a 895 longer string or text. 897 * null indicates that no indication is made about the direction 898 ("auto"), enabling an internationalization library to make an 899 auto-detection decision such as treating the string as if enclosed 900 in FSI ... PDI or equivalent, see [Unicode-14.0.0-bidi]. 902 If the third element is absent, directionality context may be 903 applying (e.g., base directionality information for an entire CBOR 904 message or part thereof). If there is no directionality context 905 applying, the default interpretation is the same as for null 906 ("auto"). 908 In CDDL: 910 tag38 = #6.38([tag38-ltag, text, ?tag38-direction]) 911 tag38-ltag = text .regexp "[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*" 912 tag38-direction = &(ltr: false, rtl: true, auto: null) 914 NOTE: Language tags of any combination of case are allowed. But 915 Section 2.1.1 of [RFC5646], part of Best Current Practice 47, 916 recommends a case combination for language tags that encoders that 917 support tag 38 may wish to follow when generating language tags. 919 Data items with tag 38 that do not meet the criteria above are not 920 valid (see Section 5.3.2 of [STD94]). 922 NOTE: The Unicode Standard [Unicode-14.0.0] includes a set of 923 characters designed for tagging text (including language tagging), in 924 the range U+E0000 to U+E007F. Although many applications, including 925 RDF, do not disallow these characters in text strings, the Unicode 926 Consortium has deprecated these characters and recommends annotating 927 language via a higher-level protocol instead. See the section 928 "Deprecated Tag Characters" in Section 23.9 of [Unicode-14.0.0], as 929 well as [RFC6082]. 931 A.3. Examples 933 Examples in this section are given in CBOR diagnostic notation first 934 and then as a pretty-printed hexadecimal representation of the 935 encoded item. 937 The following example shows how the English-language string "Hello" 938 is represented. 940 38(["en", "Hello"]) 942 D8 26 # tag(38) 943 82 # array(2) 944 62 # text(2) 945 656E # "en" 946 65 # text(5) 947 48656C6C6F # "Hello" 949 The following example shows how the French-language string "Bonjour" 950 is represented. 952 38(["fr", "Bonjour"]) 953 D8 26 # tag(38) 954 82 # array(2) 955 62 # text(2) 956 6672 # "fr" 957 67 # text(7) 958 426F6E6A6F7572 # "Bonjour" 960 The following example shows how the Hebrew-language string "שלום" 961 (HEBREW LETTER SHIN, HEBREW LETTER LAMED, HEBREW LETTER VAV, HEBREW 962 LETTER FINAL MEM, U+05E9 U+05DC U+05D5 U+05DD) is represented. Note 963 the rtl direction expressed by setting the third element in the array 964 to "true". 966 38(["he", "שלום", true]) 968 D8 26 # tag(38) 969 83 # array(3) 970 62 # text(2) 971 6865 # "he" 972 68 # text(8) 973 D7A9D79CD795D79D # "שלום" 974 F5 # primitive(21) 976 Appendix B. Interworking with RFC 7807 978 On certain occasions, it will be necessary to carry ("tunnel") 979 [RFC7807] problem details in a Concise Problem Details data item. 981 This appendix defines a Custom Problem Details entry for that 982 purpose. This is assigned Custom Problem Detail key 7807 in 983 Section 6.2. Its structure is: 985 tunnel-7807 = { 986 ? &(type: 0) => ~uri 987 ? &(status: 1) => 0..999 988 * text => any 989 } 991 To carry an [RFC7807] problem details JSON object in a Concise 992 Problem Details data item, first convert the JSON object to CBOR as 993 per Section 6.2 of [STD94]. Create an empty Concise Problem Details 994 data item. 996 Move the values for "title", "detail", and "instance", if present, 997 from the [RFC7807] problem details to the equivalent Standard Problem 998 Detail entries. Create a Custom Problem Details entry with key 7807. 999 Move the values for "type" and "status", if present, to the 1000 equivalent keys 0 and 1 of the Custom Problem Details entry. Move 1001 all remaining key/value pairs (additional members as per Section 3.2 1002 of [RFC7807]) in the converted [RFC7807] problem details object to 1003 the Custom Problem Details map unchanged. 1005 The inverse direction, carrying Concise Problem Details in a Problem 1006 Details JSON object requires the additional support provided by 1007 [I-D.ietf-httpapi-rfc7807bis], which is planned to create the HTTP 1008 Problem Types Registry. An HTTP Problem Type can then be registered 1009 that extracts top-level items from the Concise Problem Details data 1010 item in a similar way to the conversion described above, and which 1011 carries the rest of the Concise Problem Details data item in an 1012 additional member via base64url encoding without padding (Section 5 1013 of [RFC4648]). Details can be defined in a separate document when 1014 the work on [I-D.ietf-httpapi-rfc7807bis] is completed. 1016 Acknowledgments 1018 Mark Nottingham and Erik Wilde, authors of RFC 7807. Klaus Hartke 1019 and Jaime Jiménez, co-authors of an earlier generation of this 1020 specification. Christian Amsüss, Marco Tiloca, Ari Keränen and 1021 Michael Richardson for review and comments on this document. 1022 Francesca Palombini for her review (and support) as responsible AD, 1023 and Joel Jaeggli for his OPSDIR review, both of which brought 1024 significant additional considerations to this document. 1026 For Appendix A, John Cowan and Doug Ewell are also to be 1027 acknowledged. The content of an earlier version of this appendix was 1028 also discussed in the "apps-discuss at ietf.org" and "ltru at 1029 ietf.org" mailing lists. More recently, the authors initiated a 1030 discussion about the handling of writing direction information in 1031 conjunction with language tags. That led to discussions within the 1032 W3C Internationalization Core Working Group. The authors would like 1033 to acknowledge that cross-organization cooperation and particular 1034 contributions from John Klensin and Addison Phillips, and specific 1035 text proposals by Martin Dürst. 1037 Contributors 1039 Peter Occil 1040 Email: poccil14 at gmail dot com 1041 URI: http://peteroupc.github.io/CBOR/ 1043 Peter defined CBOR tag 38, basis of Appendix A. 1045 Christian Amsüss 1046 Email: christian@amsuess.com 1047 Christian contributed what became Section 3.1.1. 1049 Authors' Addresses 1051 Thomas Fossati 1052 arm 1053 Email: thomas.fossati@arm.com 1055 Carsten Bormann 1056 Universität Bremen TZI 1057 Postfach 330440 1058 D-28359 Bremen 1059 Germany 1060 Phone: +49-421-218-63921 1061 Email: cabo@tzi.org