idnits 2.17.00 (12 Aug 2021) /tmp/idnits29642/draft-ietf-core-problem-details-03.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 7 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 document date (6 May 2022) is 8 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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: 7 November 2022 Universität Bremen TZI 6 6 May 2022 8 Concise Problem Details For CoAP APIs 9 draft-ietf-core-problem-details-03 11 Abstract 13 This document defines a "problem detail" as a way to carry machine- 14 readable details of errors in a REST response to avoid the need to 15 define new error response formats for REST APIs. The format is 16 inspired by, but intended to be more concise than, the Problem 17 Details for HTTP APIs defined in RFC 7807. 19 Discussion Venues 21 This note is to be removed before publishing as an RFC. 23 Discussion of this document takes place on the CORE Working Group 24 mailing list (core@ietf.org), which is archived at 25 https://mailarchive.ietf.org/arch/browse/core/. 27 Source for this draft and an issue tracker can be found at 28 https://github.com/core-wg/core-problem-details. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on 7 November 2022. 47 Copyright Notice 49 Copyright (c) 2022 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 54 license-info) in effect on the date of publication of this document. 55 Please review these documents carefully, as they describe your rights 56 and restrictions with respect to this document. Code Components 57 extracted from this document must include Revised BSD License text as 58 described in Section 4.e of the Trust Legal Provisions and are 59 provided without warranty as described in the Revised BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 65 2. Basic Problem Details . . . . . . . . . . . . . . . . . . . . 3 66 3. Extending Concise Problem Details . . . . . . . . . . . . . . 5 67 3.1. Standard Problem Detail Entries . . . . . . . . . . . . . 5 68 3.2. Custom Problem Detail Entries . . . . . . . . . . . . . . 6 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 71 5.1. Standard Problem Detail Key registry . . . . . . . . . . 9 72 5.2. Custom Problem Detail Key registry . . . . . . . . . . . 10 73 5.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 11 74 5.4. Content-Format . . . . . . . . . . . . . . . . . . . . . 12 75 5.5. CBOR Tag 38 . . . . . . . . . . . . . . . . . . . . . . . 12 76 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 6.1. Normative References . . . . . . . . . . . . . . . . . . 12 78 6.2. Informative References . . . . . . . . . . . . . . . . . 13 79 Appendix A. Language-Tagged Strings . . . . . . . . . . . . . . 14 80 A.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 14 81 A.2. Detailed Semantics . . . . . . . . . . . . . . . . . . . 14 82 A.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 17 83 Appendix B. Interworking with RFC 7807 . . . . . . . . . . . . . 18 84 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 18 85 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 19 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 88 1. Introduction 90 REST response status information such as CoAP response codes 91 (Section 5.9 of [RFC7252]) is sometimes not sufficient to convey 92 enough information about an error to be helpful. This specification 93 defines a simple and extensible framework to define CBOR [STD94] data 94 items to suit this purpose. It is designed to be reused by REST 95 APIs, which can identify distinct "problem types" specific to their 96 needs. Thus, API clients can be informed of both the high-level 97 error class (using the response code) and the finer-grained details 98 of the problem (using this vocabulary), as shown in Figure 1. 100 .--------. .--------. 101 | CoAP | | CoAP | 102 | Client | | Server | 103 '----+---' '---+----' 104 | | 105 | Request | 106 o----------------->| 107 | | (failure) 108 |<-----------------o 109 | Error Response | 110 | with a CBOR | 111 | data item giving | 112 | Problem Details | 113 | | 115 Figure 1: Problem Details: Example with CoAP 117 The framework presented is largely inspired by the Problem Details 118 for HTTP APIs defined in [RFC7807]. Appendix B discusses 119 applications where interworking with [RFC7807] is required. 121 1.1. Requirements Language 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 125 "OPTIONAL" in this document are to be interpreted as described in 126 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 127 capitals, as shown here. 129 2. Basic Problem Details 131 A Concise Problem Details data item is a CBOR data item with the 132 following structure (notated in CDDL [RFC8610]): 134 problem-details = non-empty<{ 135 ? &(title: -1) => oltext 136 ? &(detail: -2) => oltext 137 ? &(instance: -3) => ~uri 138 ? &(response-code: -4) => uint .size 1 139 standard-problem-detail-entries 140 custom-problem-detail-entries 141 }> 143 standard-problem-detail-entries = ( 144 * nint => any 145 ) 147 custom-problem-detail-entries = ( 148 * (uint/~uri) => { + any => any } 149 ) 151 non-empty = (M) .and ({ + any => any }) 153 oltext = text / tag38 ; see Appendix A for tag38 155 Figure 2: Problem Detail Data Item 157 A number of problem detail entries, the Standard Problem Detail 158 entries, are predefined (more predefined details can be registered, 159 see Section 3.1): 161 The title (key -1): 162 A short, human-readable summary of the problem type. It SHOULD 163 NOT change from occurrence to occurrence of the problem. 165 The detail (key -2): 166 A human-readable explanation specific to this occurrence of the 167 problem. 169 The instance (key -3): 170 A URI reference that identifies the specific occurrence of the 171 problem. It may or may not yield further information if 172 dereferenced. 174 The response-code (key -4) 175 The CoAP response code (Section 5.9 of [RFC7252]) generated by the 176 origin server for this occurrence of the problem. 178 Note that, unlike [RFC7807], Concise Problem Details data items have 179 no explicit type. 181 Both "title" and "detail" can use either an unadorned CBOR text 182 string (text) or a language-tagged text string (tag38); see 183 Appendix A for the definition of the latter. 185 The "title" string is advisory and included to give consumers a 186 shorthand for the category of the error encountered. 188 The "detail" member, if present, ought to focus on helping the client 189 correct the problem, rather than giving debugging information. 190 Consumers SHOULD NOT parse the "detail" member for information; 191 extensions (see Section 3) are more suitable and less error-prone 192 ways to obtain such information. 194 Note that the "instance" URI reference may be relative; this means 195 that it must be resolved relative to the representation's base URI, 196 as per Section 5 of [STD66]. 198 Note that the "response code" value is a numeric representation of 199 the actual code, so it does not take the usual form that resembles an 200 HTTP status code -- 4.04 Not found is represented by the number 132. 202 3. Extending Concise Problem Details 204 This specification defines a generic problem type container with only 205 a minimal set of attributes to make it usable. 207 It is expected that applications will extend the base format by 208 defining new attributes. 210 These new attributes fall into two categories: generic and 211 application specific. 213 Generic attributes will be allocated in the standard-problem-detail- 214 entries slot according to the registration procedure defined in 215 Section 3.1. 217 Application-specific attributes will be allocated in the custom- 218 problem-detail-entries slot according to the procedure described in 219 Section 3.2. 221 3.1. Standard Problem Detail Entries 223 Beyond the Standard Problem Detail keys defined in Figure 2, 224 additional Standard Problem Detail keys can be registered for use in 225 the standard-problem-detail-entries slot (see Section 5.1). 227 Standard Problem Detail keys are negative integers, so they never can 228 conflict with Custom Problem Detail keys defined for a specific 229 application domain (which are unsigned integers or URIs.) 231 In summary, the keys for Standard Problem Detail entries are in a 232 global namespace that is not specific to a particular application 233 domain. 235 Consumers of a Concise Problem Details instance MUST ignore any 236 Standard Problem Detail entries that they do not recognize; this 237 allows problem details to evolve. 239 3.2. Custom Problem Detail Entries 241 Applications may extend the Problem Details data item with additional 242 entries to convey additional, application-specific information. 244 Such new entries are allocated in the custom-problem-detail-entries 245 slot, and carry a nested map specific to that application. The map 246 key can either be an (absolute!) URI (controlled by the entity 247 defining this extension), or an unsigned integer. Only the latter 248 needs to be registered (Section 5.2). 250 Within the nested map any number of attributes can be given for a 251 single extension. The semantics of each custom attribute MUST be 252 described in the documentation for the extension; for extension that 253 are registered (i.e., are identified by an unsigned int) that 254 documentation goes along with the registration. 256 The unsigned integer form allows a more compact representation, in 257 exchange, authors are expected to comply with the required 258 registration and documentation process. In comparison, the URI form 259 is less space-efficient but requires no registration. It is 260 therefore useful for experimenting during the development cycle and 261 for applications deployed in environments where producers and 262 consumers of Concise Problem Details are more tightly integrated. 263 (The URI form thus covers the potential need we might otherwise have 264 for a "private use" range for the unsigned integers.) 266 Note that the URI given for the extension is for identification 267 purposes only and, even if dereferenceable in principle, MUST NOT be 268 dereferenced in the normal course of handling problem details (i.e., 269 outside diagnostic/debugging procedures involving humans). 271 An example of a custom extension using a URI as custom-problem- 272 detail-entries key is shown in Figure 3. 274 { 275 / title / -1: "title of the error", 276 / detail / -2: "detailed information about the error", 277 / instance / -3: "coaps://pd.example/FA317434", 278 / response-code / -4: 128, / 4.00 / 280 "tag:3gpp.org,2022-03:TS29112": { 281 / cause / 0: "machine readable error cause", 282 / invalidParams / 1: [ 283 [ 284 / param / "first parameter name", 285 / reason / "must be a positive integer" 286 ], 287 [ 288 / param / "second parameter name" 289 ] 290 ], 291 / supportedFeatures / 2: "d34db33f" 292 } 293 } 295 Figure 3: Example Extension with URI key 297 Obviously, an SDO like 3GPP can also easily register such a custom 298 problem detail entry to receive a more efficient unsigned integer 299 key; the same example but using a registered unsigned int as custom- 300 problem-detail-entries key is shown in Figure 4. 302 { 303 / title / -1: "title of the error", 304 / detail / -2: "detailed information about the error", 305 / instance / -3: "coaps://pd.example/FA317434", 306 / response-code / -4: 128, / 4.00 / 308 /example value 4711 not actually registered like this:/ 309 4711: { 310 / cause / 0: "machine readable error cause", 311 / invalidParams / 1: [ 312 [ 313 / param / "first parameter name", 314 / reason / "must be a positive integer" 315 ], 316 [ 317 / param / "second parameter name" 318 ] 319 ], 320 / supportedFeatures / 2: "d34db33f" 321 } 322 } 324 Figure 4: Example Extension with unsigned int (registered) key 326 In summary, the keys for the maps used inside Custom Problem Detail 327 entries are defined specifically to the identifier of that Custom 328 Problem Detail entry, the documentation of which defines these 329 internal entries, typically chosen to address a given application 330 domain. Consumers of a Concise Problem Details instance MUST ignore 331 any Custom Problem Detail entries, or keys inside the Custom Problem 332 Detail entries, that they do not recognize; this allows Custom 333 Problem Detail entries to evolve and include additional information 334 in the future. 336 4. Security Considerations 338 The security and privacy considerations outlined in Section 5 of 339 [RFC7807] apply in full. 341 5. IANA Considerations 343 // RFC Editor: please replace RFC XXXX with this RFC number and 344 // remove this note. 346 5.1. Standard Problem Detail Key registry 348 This specification defines a new sub-registry for Standard Problem 349 Detail Keys in the CoRE Parameters registry [IANA.core-parameters], 350 with the policy "specification required" [RFC8126]. 352 Each entry in the registry must include: 354 Key value: 355 a negative integer to be used as the value of the key 357 Name: 358 a name that could be used in implementations for the key 360 CDDL type: 361 type of the data associated with the key in CDDL notation 363 Brief description: 364 a brief description 366 reference: 367 a reference document 369 Initial entries in this sub-registry are as follows: 371 +=======+===============+=======+======================+===========+ 372 | Key | Name | CDDL | Brief description | Reference | 373 | value | | Type | | | 374 +=======+===============+=======+======================+===========+ 375 | -1 | title | text | short, human- | RFCXXXX | 376 | | | | readable summary of | | 377 | | | | the problem type | | 378 +-------+---------------+-------+----------------------+-----------+ 379 | -2 | detail | text | human-readable | RFCXXXX | 380 | | | | explanation specific | | 381 | | | | to this occurrence | | 382 | | | | of the problem | | 383 +-------+---------------+-------+----------------------+-----------+ 384 | -3 | instance | ~uri | URI reference | RFCXXXX | 385 | | | | identifying specific | | 386 | | | | occurrence of the | | 387 | | | | problem | | 388 +-------+---------------+-------+----------------------+-----------+ 389 | -4 | response-code | uint | CoAP response code | RFCXXXX | 390 | | | .size | | | 391 | | | 1 | | | 392 +-------+---------------+-------+----------------------+-----------+ 394 Table 1: Initial Entries in Standard Problem Detail Key registry 396 5.2. Custom Problem Detail Key registry 398 This specification defines a new sub-registry for Custom Problem 399 Detail Keys in the CoRE Parameters registry [IANA.core-parameters], 400 with the policy "first come first served" [RFC8126]. 402 Each entry in the registry must include: 404 Key value: 405 an unsigned integer to be used as the value of the key 407 Name: 408 a name that could be used in implementations for the key 410 Brief description: 411 a brief description 413 Reference: 414 a reference document that provides a description of the map, 415 including a CDDL description, that describes all inside keys and 416 values 418 Initial entries in this sub-registry are as follows: 420 +=======+=============+===========================+===========+ 421 | Key | Name | Brief description | Reference | 422 | value | | | | 423 +=======+=============+===========================+===========+ 424 | 7807 | tunnel-7807 | Carry RFC 7807 problem | RFCXXXX | 425 | | | details in a Concise | | 426 | | | Problem Details data item | | 427 +-------+-------------+---------------------------+-----------+ 429 Table 2: Initial Entries in Custom Problem Detail Key registry 431 5.3. Media Type 433 IANA is requested to add the following Media-Type to the "Media 434 Types" registry [IANA.media-types]. 436 +============================+============================+=========+ 437 |Name |Template |Reference| 438 +============================+============================+=========+ 439 |concise-problem-details+cbor|application/concise-problem-|RFCXXXX, | 440 | |details+cbor |Section | 441 | | |5.3 | 442 +----------------------------+----------------------------+---------+ 444 Table 3: New Media Type application/concise-problem-details+cbor 446 Type name: application 447 Subtype name: concise-problem-details+cbor 448 Required parameters: none 449 Optional parameters: none 450 Encoding considerations: binary (CBOR data item) 451 Security considerations: Section 4 of RFC XXXX 452 Interoperability considerations: none 453 Published specification: Section 5.3 of RFC XXXX 454 Applications that use this media type: Clients and servers in the 455 Internet of Things 456 Fragment identifier considerations: The syntax and semantics of 457 fragment identifiers is as specified for "application/cbor". (At 458 publication of RFC XXXX, there is no fragment identification 459 syntax defined for "application/cbor".) 460 Person & email address to contact for further information: CoRE WG 461 mailing list (core@ietf.org), or IETF Applications and Real-Time 462 Area (art@ietf.org) 463 Intended usage: COMMON 464 Restrictions on usage: none 465 Author/Change controller: IETF 466 Provisional registration: no 468 5.4. Content-Format 470 IANA is requested to register a Content-Format number in the "CoAP 471 Content-Formats" sub-registry, within the "Constrained RESTful 472 Environments (CoRE) Parameters" Registry [IANA.core-parameters], as 473 follows: 475 +==============================+================+======+===========+ 476 | Content-Type | Content Coding | ID | Reference | 477 +==============================+================+======+===========+ 478 | application/concise-problem- | - | TBD1 | RFC XXXX | 479 | details+cbor | | | | 480 +------------------------------+----------------+------+-----------+ 482 Table 4: New Content-Format 484 TBD1 is to be assigned from the space 256..999. 486 In the registry as defined by Section 12.3 of [RFC7252] at the time 487 of writing, the column "Content-Type" is called "Media type" and the 488 column "Content Coding" is called "Encoding". 489 // This paragraph to be removed by RFC editor. 491 5.5. CBOR Tag 38 493 In the registry "CBOR Tags" [IANA.cbor-tags], IANA has registered 494 CBOR Tag 38. IANA is requested to replace the reference for this 495 registration with Appendix A, RFC XXXX. 497 6. References 499 6.1. Normative References 501 [IANA.cbor-tags] 502 IANA, "Concise Binary Object Representation (CBOR) Tags", 503 . 505 [IANA.core-parameters] 506 IANA, "Constrained RESTful Environments (CoRE) 507 Parameters", 508 . 510 [IANA.media-types] 511 IANA, "Media Types", 512 . 514 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 515 Requirement Levels", BCP 14, RFC 2119, 516 DOI 10.17487/RFC2119, March 1997, 517 . 519 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 520 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 521 2006, . 523 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 524 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 525 September 2009, . 527 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 528 Application Protocol (CoAP)", RFC 7252, 529 DOI 10.17487/RFC7252, June 2014, 530 . 532 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 533 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 534 . 536 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 537 Writing an IANA Considerations Section in RFCs", BCP 26, 538 RFC 8126, DOI 10.17487/RFC8126, June 2017, 539 . 541 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 542 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 543 May 2017, . 545 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 546 Definition Language (CDDL): A Notational Convention to 547 Express Concise Binary Object Representation (CBOR) and 548 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 549 June 2019, . 551 [STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 552 Resource Identifier (URI): Generic Syntax", STD 66, 553 RFC 3986, DOI 10.17487/RFC3986, January 2005, 554 . 556 [STD94] Bormann, C. and P. Hoffman, "Concise Binary Object 557 Representation (CBOR)", STD 94, RFC 8949, 558 DOI 10.17487/RFC8949, December 2020, 559 . 561 6.2. Informative References 563 [I-D.ietf-httpapi-rfc7807bis] 564 Nottingham, M., Wilde, E., and S. Dalal, "Problem Details 565 for HTTP APIs", Work in Progress, Internet-Draft, draft- 566 ietf-httpapi-rfc7807bis-02, 16 April 2022, 567 . 570 [RDF] Cyganiak, R., Wood, D., and M. Lanthaler, "RDF 1.1 571 Concepts and Abstract Syntax", W3C Recommendation, 25 572 February 2014, 573 . 575 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 576 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 577 . 579 [Unicode-14.0.0] 580 The Unicode Consortium, "The Unicode Standard, Version 581 14.0.0", Mountain View: The Unicode Consortium, 582 ISBN 978-1-936213-29-0, September 2021, 583 . Note 584 that while this document references a version that was 585 recent at the time of writing, the statements made based 586 on this version are expected to remain valid for future 587 versions. 589 Appendix A. Language-Tagged Strings 591 This appendix serves as the archival documentation for CBOR Tag 38, a 592 tag for serializing language-tagged text strings in CBOR. The text 593 of this appendix is adapted from the specification text supplied for 594 its initial registration. It has been extended to allow 595 supplementing the language tag by a direction indication. 597 A.1. Introduction 599 In some cases it is useful to specify the natural language of a text 600 string. This specification defines a tag that does just that. One 601 technology that supports language-tagged strings is the Resource 602 Description Framework (RDF) [RDF]. 604 A.2. Detailed Semantics 606 A language-tagged string in CBOR has the tag 38 and consists of an 607 array with a length of 2 or 3. 609 The first element is a well-formed language tag under Best Current 610 Practice 47 ([RFC5646] and [RFC4647]), represented as a UTF-8 text 611 string (major type 3). 613 The second element is an arbitrary UTF-8 text string (major type 3). 614 Both the language tag and the arbitrary string can optionally be 615 annotated with CBOR tags; this is not shown in the CDDL below. 617 The optional third element, if present, is a Boolean value that 618 indicates a direction: false for "ltr" direction, true for "rtl" 619 direction. If the third element is absent, no indication is made 620 about the direction. 622 In CDDL: 624 tag38 = #6.38([tag38-ltag, text, ?tag38-direction]) 625 tag38-ltag = text .abnf ("Language-Tag" .det RFC5646) 626 tag38-direction = &(ltr: false, rtl: true) 628 RFC5646 = ' 629 Language-Tag = langtag ; normal language tags 630 / privateuse ; private use tag 631 / legacy ; legacy tags 633 langtag = language 634 ["-" script] 635 ["-" region] 636 *("-" variant) 637 *("-" extension) 638 ["-" privateuse] 640 language = 2*3ALPHA ; shortest ISO 639 code 641 ["-" extlang] ; sometimes followed by 642 ; extended language subtags 643 / 4ALPHA ; or reserved for future use 644 / 5*8ALPHA ; or registered language subtag 646 extlang = 3ALPHA ; selected ISO 639 codes 647 *2("-" 3ALPHA) ; permanently reserved 649 script = 4ALPHA ; ISO 15924 code 651 region = 2ALPHA ; ISO 3166-1 code 652 / 3DIGIT ; UN M.49 code 654 variant = 5*8alphanum ; registered variants 655 / (DIGIT 3alphanum) 657 extension = singleton 1*("-" (2*8alphanum)) 659 ; Single alphanumerics 660 ; "x" reserved for private use 661 singleton = DIGIT ; 0 - 9 662 / %x41-57 ; A - W 663 / %x59-5A ; Y - Z 664 / %x61-77 ; a - w 665 / %x79-7A ; y - z 667 privateuse = "x" 1*("-" (1*8alphanum)) 669 legacy = irregular / regular ; different word in RFC 671 irregular = "en-GB-oed" / "i-ami" / "i-bnn" / "i-default" / 672 "i-enochian" / "i-hak" / "i-klingon" / "i-lux" / 673 "i-mingo" / "i-navajo" / "i-pwn" / "i-tao" / "i-tay" / 674 "i-tsu" / "sgn-BE-FR" / "sgn-BE-NL" / "sgn-CH-DE" 676 regular = "art-lojban" / "cel-gaulish" / "no-bok" / "no-nyn" / 677 "zh-guoyu" / "zh-hakka" / "zh-min" / "zh-min-nan" / 678 "zh-xiang" 680 alphanum = (ALPHA / DIGIT) ; letters and numbers 682 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z 683 DIGIT = %x30-39 ; 0-9 684 ' 686 NOTE: Language tags of any combination of case are allowed. But 687 section 2.1.1 of [RFC5646], part of Best Current Practice 47, 688 recommends a case combination for language tags, that encoders that 689 support tag 38 may wish to follow when generating language tags. 691 Data items with tag 38 that do not meet the criteria above are 692 invalid (see Section 5.3.2 of [STD94]). 694 NOTE: The Unicode Standard [Unicode-14.0.0] includes a set of 695 characters designed for tagging text (including language tagging), in 696 the range U+E0000 to U+E007F. Although many applications, including 697 RDF, do not disallow these characters in text strings, the Unicode 698 Consortium has deprecated these characters and recommends annotating 699 language via a higher-level protocol instead. See the section 700 "Deprecated Tag Characters" in Section 23.9 of [Unicode-14.0.0]. 702 A.3. Examples 704 Examples in this section are given in CBOR diagnostic mode, and then 705 as a pretty-printed hexadecimal representation of the encoded item. 707 The following example shows how the English-language string "Hello" 708 is represented. 710 38(["en", "Hello"]) 712 D8 26 # tag(38) 713 82 # array(2) 714 62 # text(2) 715 656E # "en" 716 65 # text(5) 717 48656C6C6F # "Hello" 719 The following example shows how the French-language string "Bonjour" 720 is represented. 722 38(["fr", "Bonjour"]) 724 D8 26 # tag(38) 725 82 # array(2) 726 62 # text(2) 727 6672 # "fr" 728 67 # text(7) 729 426F6E6A6F7572 # "Bonjour" 731 The following example shows how the Hebrew-language string "שלום" 732 (HEBREW LETTER SHIN, HEBREW LETTER LAMED, HEBREW LETTER VAV, HEBREW 733 LETTER FINAL MEM, U+05E9 U+05DC U+05D5 U+05DD) is represented. Note 734 the rtl direction expressed by setting the third element in the array 735 to "true". 737 38(["he", "שלום", true]) 739 D8 26 # tag(38) 740 83 # array(3) 741 62 # text(2) 742 6865 # "he" 743 68 # text(8) 744 D7A9D79CD795D79D # "שלום" 745 F5 # primitive(21) 747 Appendix B. Interworking with RFC 7807 749 On certain occasions, it will be necessary to carry ("tunnel") 750 [RFC7807] problem details in a Concise Problem Details item. 752 This appendix defines a Custom Problem Details entry for that 753 purpose. This is assigned Custom Problem Detail key 7807 in 754 Section 5.2. Its structure is: 756 tunnel-7807 = { 757 ? &(type: 0) => ~uri 758 ? &(status: 1) => 0..999 759 * text => any 760 } 762 To carry an [RFC7807] problem details JSON object in a Concise 763 Problem Details item, first convert the JSON object to CBOR as per 764 Section 6.2 of [STD94]. Create an empty Concise Problem Details data 765 item. 767 Move the values for "title", "detail", and "instance", if present, 768 from the [RFC7807] problem details to the equivalent Standard Problem 769 Detail entries. Create a Custom Problem Detail entry with key 7807. 770 Move the values for "type" and "status", if present, to the 771 equivalent keys 0 and 1 of the Custom Problem Detail entry. Move all 772 remaining key/value pairs (additional members as per Section 3.2 of 773 [RFC7807]) in the converted [RFC7807] problem details object to the 774 Custom Problem Details map unchanged. 776 The inverse direction, carrying Concise Problem Details in a Problem 777 Details JSON object requires the additional support provided by 778 [I-D.ietf-httpapi-rfc7807bis], which is planned to create the HTTP 779 Problem Types Registry. A Problem Type can then be registered that 780 extracts top-level items from the Concise Problem Details item in a 781 similar way to the conversion described above, and which carries the 782 rest of the Concise Problem Details item in an additional member via 783 base64url encoding without padding (Section 5 of [RFC4648]). Details 784 can be defined in a separate document when the work on 785 [I-D.ietf-httpapi-rfc7807bis] is completed. 787 Acknowledgments 789 Mark Nottingham and Erik Wilde, authors of RFC 7807. Klaus Hartke 790 and Jaime Jiménez, co-authors of an earlier generation of this 791 specification. Christian Amsüss and Marco Tiloca for review and 792 comments on this document. 794 For Appendix A, John Cowan and Doug Ewell are also to be 795 acknowledged. The content of an earlier version of this appendix was 796 also discussed in the "apps-discuss at ietf.org" and "ltru at 797 ietf.org" mailing lists. 799 Contributors 801 Peter Occil 802 Email: poccil14 at gmail dot com 803 URI: http://peteroupc.github.io/CBOR/ 805 Peter defined CBOR tag 38, basis of Appendix A. 807 Authors' Addresses 809 Thomas Fossati 810 arm 811 Email: thomas.fossati@arm.com 813 Carsten Bormann 814 Universität Bremen TZI 815 Postfach 330440 816 D-28359 Bremen 817 Germany 818 Phone: +49-421-218-63921 819 Email: cabo@tzi.org