idnits 2.17.1 draft-ietf-core-links-json-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 26, 2018) is 2250 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) == Missing Reference: 'RFCthis' is mentioned on line 599, but not defined ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-01 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-12 -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) 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 K. Li 3 Internet-Draft Alibaba Group 4 Intended status: Standards Track A. Rahman 5 Expires: August 30, 2018 InterDigital 6 C. Bormann, Ed. 7 Universitaet Bremen TZI 8 February 26, 2018 10 Representing Constrained RESTful Environments (CoRE) Link Format in JSON 11 and CBOR 12 draft-ietf-core-links-json-10 14 Abstract 16 JavaScript Object Notation, JSON (RFC 8259) is a text-based data 17 format which is popular for Web based data exchange. Concise Binary 18 Object Representation, CBOR (RFC7049) is a binary data format which 19 has been optimized for data exchange for the Internet of Things 20 (IoT). For many IoT scenarios, CBOR formats will be preferred since 21 it can help decrease transmission payload sizes as well as 22 implementation code sizes compared to other data formats. 24 Web Linking (RFC 8288) provides a way to represent links between Web 25 resources as well as the relations expressed by them and attributes 26 of such a link. In constrained networks, a collection of Web links 27 can be exchanged in the CoRE link format (RFC 6690). Outside of 28 constrained environments, it may be useful to represent these 29 collections of Web links in JSON, and similarly, inside constrained 30 environments, in CBOR. This specification defines a common format 31 for this. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at https://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on August 30, 2018. 50 Copyright Notice 52 Copyright (c) 2018 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 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 3 69 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 70 2. Web Links in JSON and CBOR . . . . . . . . . . . . . . . . . 4 71 2.1. Background . . . . . . . . . . . . . . . . . . . . . . . 4 72 2.2. Information Model . . . . . . . . . . . . . . . . . . . . 4 73 2.3. Additional Encoding Step for CBOR . . . . . . . . . . . . 6 74 2.4. Converting JSON or CBOR to Link-Format . . . . . . . . . 8 75 2.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 9 76 2.5.1. Link Format to JSON Example . . . . . . . . . . . . . 9 77 2.5.2. Link Format to CBOR Example . . . . . . . . . . . . . 10 78 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 79 3.1. Media types . . . . . . . . . . . . . . . . . . . . . . . 12 80 3.2. CoAP Content-Format Registration . . . . . . . . . . . . 13 81 4. Security Considerations . . . . . . . . . . . . . . . . . . . 14 82 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 83 5.1. Normative References . . . . . . . . . . . . . . . . . . 14 84 5.2. Informative References . . . . . . . . . . . . . . . . . 15 85 Appendix A. Reference implementation . . . . . . . . . . . . . . 16 86 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 19 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 89 1. Introduction 91 Web Linking [RFC8288] provides a way to represent links between Web 92 resources as well as the relations expressed by them and attributes 93 of such a link. In constrained networks, a collection of Web links 94 can be exchanged in the CoRE link format [RFC6690] to enable resource 95 discovery, for instance by using the CoAP protocol [RFC7252]. 97 The JavaScript Object Notation (JSON) [RFC8259] is a lightweight, 98 text-based, language-independent data interchange format. JSON is 99 popular in the Web development environment as it is easy for humans 100 to read and write. 102 The Concise Binary Object Representation (CBOR) [RFC7049] is a binary 103 data format which requires extremely small code size, allows very 104 compact message representation, and provides extensibility without 105 the need for version negotiation. CBOR is especially well suited for 106 IoT environments because of these efficiencies. 108 When converting between a bespoke syntax such as that defined by 109 [RFC6690] and JSON or CBOR, many small decisions have to be made. If 110 left without guidance, it is likely that a number of slightly 111 incompatible dialects will emerge. This specification defines a 112 common format for representing CoRE Web Linking in JSON and CBOR. 114 Note that there is a separate question on how to represent Web links 115 pointing out of JSON documents, as discussed for example in [MNOT11]. 116 While there are good reasons to stay as compatible as possible to 117 developments in this area, the present specification is solving a 118 different problem. 120 1.1. Objectives 122 This specification has been designed based on the following 123 objectives: 125 o Canonical mapping 127 * lossless conversion in both directions between any pair of 128 [RFC6690], JSON, and CBOR ("round-tripping"), unless prevented 129 by a limitation of [RFC6690] 131 * but not attempting to ensure that a sequence of conversions 132 from one of the formats through one or both of the others and 133 back to the original would result in a bit-wise identical 134 representation 136 o The simplest thing that could possibly work. 138 While the formats defined in this document are based on the above 139 objectives, they are general enough that they can be used for other 140 applications of links in the Web. The same basic formats can be used 141 for Web links that do not default to the "hosts" relation type (as is 142 defined in [RFC6690]) and that allow percent encoding and general IRI 143 syntax in what is an URI-Reference field in [RFC6690]. Also, 144 specific support has been added for internationalized link attributes 145 such as "title*", including their language tags (while staying 146 limited to UTF-8 as the character set). 148 1.2. Terminology 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 152 "OPTIONAL" in this document are to be interpreted as described in 153 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 154 capitals, as shown here. 156 The term "byte" is used in its now customary sense as a synonym for 157 "octet". 159 CoAP: Constrained Application Protocol [RFC7252] 161 CBOR: Concise Binary Object Representation [RFC7049] 163 CoRE: Constrained RESTful Environments, the field of work underlying 164 [RFC6690], [RFC7049], [RFC7252], [RFC7641], [RFC7959], [RFC8075], and 165 [RFC8323] 167 IoT: Internet of Things 169 JSON: JavaScript Object Notation [RFC8259] 171 The objective of the JSON and CBOR mappings defined in this document 172 is to contain information of the formats specified in [RFC8288] and 173 [RFC6690]. This specification therefore uses the names of the ABNF 174 productions used in those documents. 176 2. Web Links in JSON and CBOR 178 2.1. Background 180 Web Linking [RFC8288] provides a way to represent links between Web 181 resources as well as the relations expressed by them and attributes 182 of such a link. In constrained networks, a collection of Web links 183 can be exchanged in the CoRE link format [RFC6690] to enable resource 184 discovery, for instance by using the CoAP protocol [RFC7252] and in 185 conjunction with the CoRE resource directory 186 [I-D.ietf-core-resource-directory]. 188 2.2. Information Model 190 This section discusses the information model underlying the CORE Link 191 Format payload. 193 An "application/link-format" document is a collection of Web links 194 ("link-value"), each of which is a collection of attributes ("link- 195 param") applied to a "URI-Reference". 197 We straightforwardly map: 199 o the collection of Web links to a JSON or CBOR array of links; 201 o each link to a JSON object or CBOR map, mapping attribute names to 202 attribute values. 204 In the object representing a "link-value", each target attribute or 205 other parameter ("link-param") is represented by a JSON name/value 206 pair (member). The name is a string representation of the parameter 207 or attribute name (as in "parmname"). The value can be a string, a 208 language-tagged string, a boolean, or an array of these, as described 209 below. 211 If the attribute value ("ptoken" or "quoted-string") is present, and 212 a Link attribute with this name ("parmname") is present just once in 213 the "link-value", the value is a string representation of the 214 parameter or attribute value ("ptoken" or "quoted-string"). "quoted- 215 string" productions are parsed (i.e, the outer quotes removed and the 216 backslash constructions evaluated) as defined in [RFC6690] and its 217 referenced documents, before placing them in JSON strings (in the 218 representation of which they may gain back additional decorations 219 such as backslashes as defined in [RFC8259]). 221 Attribute values represented as per [RFC8187], e.g. for the "title*" 222 attribute, are converted in a language-tagged string; the attribute 223 name is then represented without the "*" character. A language- 224 tagged string is represented as a CBOR map (JSON object) that carries 225 the language tag as the key for a single member and the attribute 226 value in UTF-8 form as its value. 228 If no attribute value ("ptoken" or "quoted-string") is present, the 229 presence of the attribute name is indicated by using the Boolean 230 value "true" as the value. 232 If a Link attribute ("parmname") is present more than once in a 233 "link-value", its values are then represented as a JSON array of JSON 234 string values or "true"; this array becomes the value of the JSON 235 name/value pair where the attribute name is the JSON name. 236 Attributes occurring just once MUST NOT be represented as JSON arrays 237 but MUST be directly represented as JSON strings or "true". (Note 238 that [RFC6690] has cut down on the use of repeated parameter names; 239 they are still allowed by [RFC8288] though. No attempt has been made 240 to decode the possibly space-separated values for rt=, if=, and rel= 241 into JSON arrays.) Recipients MUST NOT accept documents that violate 242 this requirement. 244 The URI-Reference is represented as a name/value pair with the name 245 "href" and the URI-Reference as the value, with the latter converted 246 to an IRI-Reference as per Section 3.2 of [RFC3987] (Rationale: The 247 usage of "href" is consistent with the use of "href" as a query 248 parameter for link-format query filtering and with link-format 249 reserving the link parameter "href" specifically for this use 250 [RFC6690]. The usage of an IRI-Reference is consistent with the 251 mandate in [RFC6690] that percent-encoding be processed. Note that 252 the format is able to represent IRIs the URIs for which cannot be 253 represented in [RFC6690] as not all percent-encoded constructions are 254 amenable to the pre-processing required by [RFC6690].) 256 As a convenient reference, the resulting structure can be described 257 in CBOR Data Definition Language (CDDL) [I-D.ietf-cbor-cddl] as in 258 Figure 1 (informative). 260 links = [* link] 261 link = { 262 href: tstr ; resource URI 263 * tstr => value 264 } 265 value1 = tstr ; text value -- the normal case 266 / { tstr => tstr } ; language tag and value 267 / true ; no value given, just the name 268 value = value1 269 / [2* value1 ] ; repeats for two or more 271 Figure 1: CoRE Link Format Data Model (JSON) 273 2.3. Additional Encoding Step for CBOR 275 The above specification for JSON might have been used as is for the 276 CBOR encoding as well. However, to further reduce message sizes, an 277 extra encoding step is performed: "href" and some commonly occurring 278 attribute names are encoded as small integers. 280 The substitution is defined in Table 1: 282 +----------+---------------+-------------------------+ 283 | name | encoded value | origin | 284 +----------+---------------+-------------------------+ 285 | href | 1 | [RFC6690], [RFCthis] | 286 | rel | 2 | [RFC5988] Section 5.3 | 287 | anchor | 3 | [RFC5988] Section 5.2 | 288 | rev | 4 | [RFC5988] Section 5.3 | 289 | hreflang | 5 | [RFC5988] Section 5.4 | 290 | media | 6 | [RFC5988] Section 5.4 | 291 | title | 7 | [RFC5988] Section 5.4 | 292 | type | 8 | [RFC5988] Section 5.4 | 293 | rt | 9 | [RFC6690] Section 3.1 | 294 | if | 10 | [RFC6690] Section 3.2 | 295 | sz | 11 | [RFC6690] Section 3.3 | 296 | ct | 12 | [RFC7252] Section 7.2.1 | 297 | obs | 13 | [RFC7641] Section 6 | 298 +----------+---------------+-------------------------+ 300 Table 1: Integer Encoding of common attribute names 302 This list of substitutions is fixed by the present specification; no 303 future expansion of the list is foreseen. "href" as well as all 304 attribute names in this list MUST be represented by their integer 305 substitutions and MUST NOT use the attribute name in text form. 306 Recipients MUST NOT accept documents that violate this requirement. 308 As a convenient reference, the resulting structure can be described 309 in CBOR Data Definition Language (CDDL) [I-D.ietf-cbor-cddl] as in 310 Figure 2 (informative). 312 links = [* link] 313 link = { 314 href => tstr ; resource URI 315 * label => value 316 } 317 href = 1 318 label = tstr / &( 319 rel: 2, anchor: 3, rev: 4, 320 hreflang: 5, media: 6, title: 7, 321 type: 8, rt: 9, if: 10, 322 sz: 11, ct: 12, obs: 13, 323 ) 324 value1 = tstr ; text value -- the normal case 325 / { tstr => tstr } ; language tag and value 326 / true ; no value given, just the name 327 value = value1 328 / [2* value1 ] ; repeats for two or more 330 Figure 2: CoRE Link Format Data Model (CBOR) 332 2.4. Converting JSON or CBOR to Link-Format 334 When a JSON or CBOR representation needs to be converted back to 335 link-format, the above process is performed in inverse. Since link- 336 format allows serializing link parameter values both in unqouted form 337 ("ptoken") or in quoted form ("quoted-string"), a decision has to be 338 made for each value. Where the syntax of "ptoken" does not allow the 339 value to be represented, the quoted form clearly needs to be used. 340 However, when both forms are possible, the decision is arbitrary. 341 The recently republished Web Linking specification, [RFC8288], 342 clarifies that this is indeed intended to be the case. However, 343 previous specifications of link attributes, including those in 344 [RFC5988] and [RFC6690], sometimes have made this decision in a 345 specific way by only including one or the other alternative in the 346 ABNF given for a link parameter. This requires a converter to know 347 about all these cases, including those that have not been defined yet 348 at the time of writing the converter. This problem becomes even 349 harder by the fact that there is no central registry of link- 350 attribute names. 352 Obviously, the conversion back to link-format needs to result in a 353 valid link-format document. The reference implementation in 354 Appendix A has addressed this problem with the following two rules: 356 o Where a "ptoken" representation is possible, that is used instead 357 of "quoted-string". This rule covers most of the special cases 358 listed above. 360 o As a special exception to the above rule, the four link attributes 361 "anchor", "title", "rt", and "if" are always expressed as "quoted- 362 string". This rule covers these specific four cases. 364 This set of rules is based on the hope that future definitions of 365 link attributes will no longer hardcode one or the other 366 serialization. 368 2.5. Examples 370 The examples in this section are based on an example on page 15 of 371 [RFC6690] (Figure 3). 373 ;ct=40;title="Sensor Index", 374 ;rt="temperature-c";if="sensor", 375 ;rt="light-lux";if="sensor", 376 ;anchor="/sensors/temp" 377 ;rel="describedby", 378 ;anchor="/sensors/temp";rel="alternate" 380 Figure 3: Example from page 15 of [RFC6690] 382 2.5.1. Link Format to JSON Example 384 The link-format document in Figure 3 becomes (321 bytes, line breaks 385 shown are not part of the minimally-sized JSON document): 387 "[{"href":"/sensors","ct":"40","title":"Sensor 388 Index"},{"href":"/sensors/temp","rt":"temperature- 389 c","if":"sensor"},{"href":"/sensors/light","rt":"light- 390 lux","if":"sensor"},{"href":"http://www.example.com/sensors/ 391 t123","anchor":"/sensors/ 392 temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/ 393 temp","rel":"alternate"}] " 395 To demonstrate the handling of value-less and array-valued 396 attributes, we extend the link-format example by examples of these 397 (Figure 4; the "obs" attribute is defined in Section 6 of [RFC7641], 398 while the "foo" attribute is for exposition only): 400 ;ct=40;title="Sensor Index", 401 ;rt="temperature-c";if="sensor";obs, 402 ;rt="light-lux";if="sensor", 403 ;anchor="/sensors/temp" 404 ;rel="describedby";foo="bar";foo=3;ct=4711, 405 ;anchor="/sensors/temp";rel="alternate" 407 Figure 4: Example derived from page 15 of [RFC6690] 409 The link-format document in Figure 4 becomes the JSON document in 410 Figure 5 (some spacing and indentation added): 412 [{"href":"/sensors","ct":"40","title":"Sensor Index"}, 413 {"href":"/sensors/temp","rt":"temperature-c","if":"sensor", 414 "obs":true}, 415 {"href":"/sensors/light","rt":"light-lux","if":"sensor"}, 416 {"href":"http://www.example.com/sensors/t123", 417 "anchor":"/sensors/temp","rel":"describedby", 418 "foo":["bar","3"],"ct":"4711"}, 419 {"href":"/t","anchor":"/sensors/temp","rel":"alternate"}] 421 Figure 5: Example derived from page 15 of [RFC6690] 423 Note that the conversion is unable to convert the string-valued "ct" 424 attribute to a number, which would be the natural type for a Content- 425 Format value; similarly, both "foo" values are treated as strings 426 independently of whether they are quoted or numeric in syntax. 428 2.5.2. Link Format to CBOR Example 430 This examples shows conversion from link format to CBOR format. 432 The link-format document in Figure 3 becomes (in CBOR diagnostic 433 format): 435 [{1: "/sensors", 12: "40", 7: "Sensor Index"}, 436 {1: "/sensors/temp", 9: "temperature-c", 10: "sensor"}, 437 {1: "/sensors/light", 9: "light-lux", 10: "sensor"}, 438 {1: "http://www.example.com/sensors/t123", 3: "/sensors/temp", 439 2: "describedby"}, 440 {1: "/t", 3: "/sensors/temp", 2: "alternate"}] 442 or, in hexadecimal (203 bytes): 444 85 # array(number of data items:5) 445 a3 # map(# data item pairs:3) 446 01 # unsigned integer(value:1,"href") 447 68 # text string(8 bytes) 448 2f73656e736f7273 # "/sensors" 449 0c # unsigned integer(value:12,"ct") 450 62 # text(2) 451 3430 # "40" 452 07 # unsigned integer(value:7,"title") 453 6c # text string(12 bytes) 454 53656e736f7220496e646578 # "Sensor Index" 455 a3 # map(# data item pairs:3) 456 01 # unsigned integer(value:1,"href") 457 6d # text string(13 bytes) 458 2f73656e736f72732f74 459 656d70 # "/sensors/temp" 460 09 # unsigned integer(value:9,"rt") 461 6d # text string(13 bytes) 462 74656d70657261747572 463 652d63 # "temperature-c" 464 0a # unsigned integer(value:10,"if") 465 66 # text string(6 bytes) 466 73656e736f72 # "sensor" 467 a3 # map(# data item pairs:3) 468 01 # unsigned integer(value:1,"href") 469 6e # text string(14 bytes) 470 2f73656e736f72732f6c 471 69676874 # "/sensors/light" 472 09 # unsigned integer(value:9,"rt") 473 69 # text string(9 bytes) 474 6c696768742d6c7578 # "light-lux" 475 0a # unsigned integer(value:10,"if") 476 66 # text string(6 bytes) 477 73656e736f72 # "sensor" 478 a3 # map(# data item pairs:3) 479 01 # unsigned integer(value:1,"href") 480 78 23 # text string(35 bytes) 481 687474703a2f2f777777 482 2e6578616d706c652e63 483 6f6d2f73656e736f7273 484 2f74313233 # "http://www.example.com/sensors/t123" 485 03 # unsigned integer(value:3,"anchor") 486 6d # text string(13 bytes) 487 2f73656e736f72732f74 488 656d70 # "/sensors/temp" 489 02 # unsigned integer(value:2,"rel") 490 6b # text string(11 bytes) 491 6465736372696265646279 # "describedby" 492 a3 # map(# data item pairs:3) 493 01 # unsigned integer(value:1,"href") 494 62 # text string(2 bytes) 495 2f74 # "/t" 496 03 # unsigned integer(value:3,"anchor") 497 6d # text string(13 bytes) 498 2f73656e736f72732f74 499 656d70 # "/sensors/temp" 500 02 # unsigned integer(value:2,"rel") 501 69 # text string(9 bytes) 502 616c7465726e617465 # "alternate" 504 Figure 6: Web Links Encoded in CBOR 506 3. IANA Considerations 508 3.1. Media types 510 This specification registers the following additional Internet Media 511 Types: 513 Type name: application 515 Subtype name: link-format+json 517 Required parameters: None 519 Optional parameters: None 521 Encoding considerations: Resources that use the "application/link- 522 format+json" media type are required to conform to the 523 "application/json" Media Type and are therefore subject to the 524 same encoding considerations specified in [RFC8259], Section 11. 526 Security considerations: See Section 4 of [RFCthis]. 528 Published specification: [RFCthis]. 530 Applications that use this media type: Applications that interchange 531 collections of Web links based on CoRE link format [RFC6690] in 532 JSON. 534 Additional information: 536 Magic number(s): N/A 538 File extension(s): N/A 540 Macintosh file type code(s): TEXT 542 Person & email address to contact for further information: 543 Carsten Bormann 545 Intended usage: COMMON 547 Change controller: IESG 549 and 551 Type name: application 553 Subtype name: link-format+cbor 554 Required parameters: None 556 Optional parameters: None 558 Encoding considerations: Resources that use the "application/link- 559 format+cbor" media type are required to conform to the 560 "application/cbor" Media Type and are therefore subject to the 561 same encoding considerations specified in [RFC7049], Section 7. 563 Security considerations: See Section 4 of [RFCthis]. 565 Published specification: [RFCthis]. 567 Applications that use this media type: Applications that interchange 568 collections of Web links based on CoRE link format [RFC6690] in 569 CBOR. 571 Additional information: 573 Magic number(s): N/A 575 File extension(s): N/A 577 Macintosh file type code(s): CBOR 579 Person & email address to contact for further information: 580 Kepeng Li 582 Intended usage: COMMON 584 Change controller: IESG 586 3.2. CoAP Content-Format Registration 588 IANA is requested to assign CoAP Content-Format IDs for the above 589 media types in the "CoAP Content-Formats" sub-registry, within the 590 "CoRE Parameters" registry [RFC7252]. The ID for "application/link- 591 format+cbor" is assigned from the "Expert Review" (0-255) range, 592 while the ID for "application/link-format+json" is assigned from the 593 "IETF review" range. The assigned IDs are show in Table 2. 595 +------------------------------+--------+--------+-----------+ 596 | Media type | Coding | ID | Reference | 597 +------------------------------+--------+--------+-----------+ 598 | application/link-format+cbor | - | TBD64 | [RFCthis] | 599 | application/link-format+json | - | TBD504 | [RFCthis] | 600 +------------------------------+--------+--------+-----------+ 602 Table 2: CoAP Content-Format IDs 604 4. Security Considerations 606 The security considerations relevant to the data model of [RFC6690], 607 as well as those of [RFC7049] and [RFC8259] apply. 609 5. References 611 5.1. Normative References 613 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 614 Requirement Levels", BCP 14, RFC 2119, 615 DOI 10.17487/RFC2119, March 1997, 616 . 618 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 619 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 620 January 2005, . 622 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 623 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 624 . 626 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 627 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 628 October 2013, . 630 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 631 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 632 May 2017, . 634 [RFC8187] Reschke, J., "Indicating Character Encoding and Language 635 for HTTP Header Field Parameters", RFC 8187, 636 DOI 10.17487/RFC8187, September 2017, 637 . 639 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 640 Interchange Format", STD 90, RFC 8259, 641 DOI 10.17487/RFC8259, December 2017, 642 . 644 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 645 DOI 10.17487/RFC8288, October 2017, 646 . 648 5.2. Informative References 650 [I-D.ietf-cbor-cddl] 651 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 652 definition language (CDDL): a notational convention to 653 express CBOR data structures", draft-ietf-cbor-cddl-01 654 (work in progress), January 2018. 656 [I-D.ietf-core-resource-directory] 657 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 658 Amsuess, "CoRE Resource Directory", draft-ietf-core- 659 resource-directory-12 (work in progress), October 2017. 661 [MNOT11] Nottingham, M., "Linking in JSON", November 2011, 662 . 664 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 665 DOI 10.17487/RFC5988, October 2010, 666 . 668 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 669 Application Protocol (CoAP)", RFC 7252, 670 DOI 10.17487/RFC7252, June 2014, 671 . 673 [RFC7641] Hartke, K., "Observing Resources in the Constrained 674 Application Protocol (CoAP)", RFC 7641, 675 DOI 10.17487/RFC7641, September 2015, 676 . 678 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 679 the Constrained Application Protocol (CoAP)", RFC 7959, 680 DOI 10.17487/RFC7959, August 2016, 681 . 683 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 684 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 685 the Constrained Application Protocol (CoAP)", RFC 8075, 686 DOI 10.17487/RFC8075, February 2017, 687 . 689 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 690 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 691 Application Protocol) over TCP, TLS, and WebSockets", 692 RFC 8323, DOI 10.17487/RFC8323, February 2018, 693 . 695 [RUBY] "Information technology -- Programming languages -- Ruby", 696 ISO/IEC 30170:2012, April 2012. 698 Appendix A. Reference implementation 700 A reference implementation of a converter from [RFC6690] link-format 701 to JSON and CBOR (and back to link-format) in the programming 702 language Ruby [RUBY] is reproduced below. (Note that this 703 implementation does not handle [RFC8187]-encoded attributes.) For 704 pretty-printing the binary CBOR, this uses the "cbor-diag" gem (Ruby 705 library), which may need to be installed by "gem install cbor-diag". 707 # 708 require 'strscan' 709 require 'json' 710 require 'cbor-pretty' 712 class String 713 def as_utf8 714 force_encoding(Encoding::UTF_8) 715 end 716 end 718 module CoRE 719 module Links 720 def self.map_to_true(a) 721 Hash[a.map{ |t| [t, true]}] 722 end 724 PTOKENCHAR = %r"[\[\]\w!#-+\--/:<-?^-`{-~@]" 725 QUOSTRCHAR = %r{(?:[^"\\]|\\.)} # to be used inside " 726 ATTRCHAR = %r"[\w!#$&+.^`|~-]" 727 MUSTBEQUOTED = map_to_true(%w{anchor title rt if}) 728 ANCHORNAME = "href" 729 SCANATTR = 730 %r{(#{ATTRCHAR}+)(?:=(?:(#{PTOKENCHAR}+)|"(#{QUOSTRCHAR}*)"))?} # " 732 RAWMAPPINGS = <<-DATA 733 href: 1, rel: 2, anchor: 3, 734 rev: 4, hreflang: 5, media: 6, 735 title: 7, type: 8, rt: 9, 736 if: 10, sz: 11, ct: 12, 737 obs: 13, 738 DATA 740 MAPPINGS = Hash.new {|h, k| k} 742 RAWMAPPINGS.scan(/([-\w]+)\s*:\s*([-\w]+),/) do |n, v| 743 MAPPINGS[n] = Integer(v) 744 end 746 def self.parse(*args) 747 WLNK.parse(*args) 748 end 750 class WLNK 751 attr_accessor :resources 752 def initialize(r = []) # make sure the keys are strings 753 @resources = r.to_ary # make sure it's an Array 754 end 755 def self.parse(s, robust = true) 756 wl = WLNK.new 757 ss = StringScanner.new(s.as_utf8) 758 ss.skip(/\s+/) if robust 759 while ss.scan(%r{<([^>]+)>}) 760 res = { ANCHORNAME => ss[1].as_utf8 } 761 ss.skip(/\s*/) if robust 762 while ss.skip(/;/) 763 ss.skip(/\s*/) if robust 764 unless ss.scan(SCANATTR) 765 raise ArgumentError, "must have attribute behind ';' 766 at: #{ss.peek(20).inspect} (byte #{ss.pos})" 767 end 768 key = ss[1].as_utf8 769 value = ss[2] || 770 (ss[3] ? ss[3].gsub(/\\(.)/) { $1 } : true) 771 if res[key] 772 res[key] = Array(res[key]) << value 773 else 774 res[key] = value 775 end 776 ss.skip(/\s*/) if robust 777 end 778 wl.resources << res 779 break unless ss.skip(/,/) 780 ss.skip(/\s*/) if robust 781 end 782 ss.skip(/\s*/) if robust 783 raise ArgumentError, "link-format unparseable at: 784 #{ss.peek(20).inspect} (byte #{ss.pos})" unless ss.eos? 786 wl 787 end 788 def to_json 789 JSON.pretty_generate(@resources) 790 end 791 def to_cbor 792 CBOR.encode(@resources.map {|r| 793 Hash[r.map { |k, v| [MAPPINGS[k], v] }]}) 794 end 795 def to_wlnk 796 resources.map do |res| 797 res = res.dup 798 u = res.delete(ANCHORNAME) 799 ["<#{u}>", *res.map { |k, v| wlnk_item(k, v) }].join(';') 800 end.join(",") 801 end 802 private 803 def wlnk_item(k, v) 804 case v 805 when String 806 if MUSTBEQUOTED[k] || v !~ /\A#{PTOKENCHAR}+\z/ 807 "#{k}=\"#{v.gsub(/[\\"]/) { |x| "\\#{x}"}}\"" 808 else 809 "#{k}=#{v}" 810 end 811 when Array 812 v.map{ |v1| wlnk_item(k, v1) }.join(';') 813 when true 814 "#{k}" 815 else 816 fail "Don't know how to represent #{{k=>v}.inspect}" 817 end 818 end 819 end 820 end 821 end 823 lf = CoRE::Links.parse(ARGF.read) 825 puts lf.to_json # JSON 826 puts CBOR.pretty(lf.to_cbor) # CBOR "pretty" binary form 827 puts lf.to_wlnk # RFC 6690 link-format 828 # 830 Acknowledgements 832 Special thanks to Bert Greevenbosch who was an author on the initial 833 version of a contributing document as well as the original author on 834 the CDDL notation. 836 Hannes Tschofenig made many helpful suggestions for improving this 837 document. 839 Authors' Addresses 841 Kepeng LI 842 Alibaba Group 843 Wenyixi Road, Yuhang District 844 Hangzhou, Zhejiang 311121 845 China 847 Email: kepeng.lkp@alibaba-inc.com 849 Akbar Rahman 850 InterDigital Communications, LLC 851 1000 Sherbrooke Street West 852 Montreal, Quebec H3A 3G4 853 Canada 855 Phone: +1-514-585-0761 856 Email: akbar.rahman@interdigital.com 858 Carsten Bormann (editor) 859 Universitaet Bremen TZI 860 Postfach 330440 861 Bremen D-28359 862 Germany 864 Phone: +49-421-218-63921 865 Email: cabo@tzi.org