idnits 2.17.1 draft-ietf-core-links-json-09.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 (July 03, 2017) is 2451 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 585, but not defined ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-10 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-10 == Outdated reference: A later version (-08) exists of draft-nottingham-rfc5988bis-06 Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 2 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: January 4, 2018 InterDigital 6 C. Bormann, Ed. 7 Universitaet Bremen TZI 8 July 03, 2017 10 Representing Constrained RESTful Environments (CoRE) Link Format in JSON 11 and CBOR 12 draft-ietf-core-links-json-09 14 Abstract 16 JavaScript Object Notation, JSON (RFC7159) 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 (RFC5988) 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 (RFC6690). 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 http://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 January 4, 2018. 50 Copyright Notice 52 Copyright (c) 2017 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 (http://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 . . . . . . . . . . . . . . . . . . . . 5 73 2.3. Additional Encoding Step for CBOR . . . . . . . . . . . . 6 74 2.4. Converting JSON or CBOR to Link-Format . . . . . . . . . 8 75 2.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . . . 14 85 Appendix A. Reference implementation . . . . . . . . . . . . . . 15 86 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 18 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 89 1. Introduction 91 Web Linking [RFC5988] 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) [RFC7159] 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") 130 * but not attempting to ensure that a sequence of conversions 131 from one of the formats through one or both of the others and 132 back to the original would result in a bit-wise identical 133 representation 135 o The simplest thing that could possibly work 137 * Do not cater for RFC 5988 complications caused by HTTP header 138 character set issues [RFC2047] 140 While the formats defined in this document are based on the above 141 objectives, they are general enough that they can be used for other 142 applications of links in the Web. The same basic formats can be used 143 for Web links that do not default to the "hosts" relation type (as is 144 defined in RFC 6690) and that allow percent encoding and general IRI 145 syntax in the current URI field. Also, better support for 146 internationalized link attributes such as title* could add support 147 for language tags (while staying limited to UTF-8 as the character 148 set). This could be done in conjunction with a parallel effort, 149 [I-D.nottingham-rfc5988bis], which started after the present work 150 stabilized. 152 1.2. Terminology 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 156 "OPTIONAL" in this document are to be interpreted as described in 157 [RFC2119] when they appear in ALL CAPS. These words may also appear 158 in this document in lower case as plain English words, absent their 159 normative meanings. 161 The term "byte" is used in its now customary sense as a synonym for 162 "octet". 164 CoAP: Constrained Application Protocol [RFC7252] 166 CBOR: Concise Binary Object Representation [RFC7049] 168 CoRE: Constrained RESTful Environments, the field of work underlying 169 [RFC6690], [RFC7049], [RFC7252], [RFC7641], [RFC7959], and [RFC8075] 171 IoT: Internet of Things 173 JSON: JavaScript Object Notation [RFC7159] 175 The objective of the JSON and CBOR mappings defined in this document 176 is to contain information of the formats specified in [RFC5988] and 177 [RFC6690]. This specification therefore uses the names of the ABNF 178 productions used in those documents. 180 2. Web Links in JSON and CBOR 182 2.1. Background 184 Web Linking [RFC5988] provides a way to represent links between Web 185 resources as well as the relations expressed by them and attributes 186 of such a link. In constrained networks, a collection of Web links 187 can be exchanged in the CoRE link format [RFC6690] to enable resource 188 discovery, for instance by using the CoAP protocol [RFC7252] and in 189 conjunction with the CoRE resource directory 190 [I-D.ietf-core-resource-directory]. 192 2.2. Information Model 194 This section discusses the information model underlying the CORE Link 195 Format payload. 197 An "application/link-format" document is a collection of Web links 198 ("link-value"), each of which is a collection of attributes ("link- 199 param") applied to a "URI-Reference". 201 We straightforwardly map: 203 o the collection of Web links to a JSON or CBOR array of links; 205 o each link to a JSON object or CBOR map, mapping attribute names to 206 attribute values. 208 In the object representing a "link-value", each target attribute or 209 other parameter ("link-param") is represented by a JSON name/value 210 pair (member). The name is a string representation of the parameter 211 or attribute name (as in "parmname"). The value can be a string, a 212 boolean, or an array of strings or booleans, as described below. 214 If the attribute value ("ptoken" or "quoted-string") is present, and 215 a Link attribute with this name ("parmname") is present just once in 216 the "link-value", the value is a string representation of the 217 parameter or attribute value ("ptoken" or "quoted-string"). "quoted- 218 string" productions are parsed (i.e, the outer quotes removed and the 219 backslash constructions evaluated) as defined in [RFC6690] and its 220 referenced documents, before placing them in JSON strings (in the 221 representation of which they may gain back additional decorations 222 such as backslashes as defined in [RFC7159]). 224 If no attribute value ("ptoken" or "quoted-string") is present, the 225 presence of the attribute name is indicated by using the Boolean 226 value "true" as the value. 228 If a Link attribute ("parmname") is present more than once in a 229 "link-value", its values are then represented as a JSON array of JSON 230 string values or "true"; this array becomes the value of the JSON 231 name/value pair where the attribute name is the JSON name. 232 Attributes occurring just once MUST NOT be represented as JSON arrays 233 but MUST be directly represented as JSON strings or "true". (Note 234 that [RFC6690] has cut down on the use of repeated parameter names; 235 they are still allowed by [RFC5988] though. No attempt has been made 236 to decode the possibly space-separated values for rt=, if=, and rel= 237 into JSON arrays.) Recipients MUST NOT accept documents that violate 238 this requirement. 240 The URI-Reference is represented as a name/value pair with the name 241 "href" and the URI-Reference as the value. (Rationale: This usage is 242 consistent with the use of "href" as a query parameter for link- 243 format query filtering and with link-format reserving the link 244 parameter "href" specifically for this use [RFC6690]). 246 As a non-normative summary, the resulting structure can be 247 represented in CBOR Data Definition Language (CDDL) 248 [I-D.greevenbosch-appsawg-cbor-cddl] as: 250 links = [* link] 251 link = { 252 href: tstr ; resource URI 253 * tstr => value 254 } 255 value = tstr ; text value -- the normal case 256 / true ; no value given, just the name 257 / [2* tstr/true ] ; repeats for two or more 259 Figure 1: CoRE Link Format Data Model 261 2.3. Additional Encoding Step for CBOR 263 The above specification for JSON might have been used as is for the 264 CBOR encoding as well. However, to further reduce message sizes, an 265 extra encoding step is performed: "href" and some commonly occurring 266 attribute names are encoded as small integers. 268 The substitution is defined in Table 1: 270 +----------+---------------+-------------------------+ 271 | name | encoded value | origin | 272 +----------+---------------+-------------------------+ 273 | href | 1 | [RFC6690], [RFCthis] | 274 | rel | 2 | [RFC5988] Section 5.3 | 275 | anchor | 3 | [RFC5988] Section 5.2 | 276 | rev | 4 | [RFC5988] Section 5.3 | 277 | hreflang | 5 | [RFC5988] Section 5.4 | 278 | media | 6 | [RFC5988] Section 5.4 | 279 | title | 7 | [RFC5988] Section 5.4 | 280 | type | 8 | [RFC5988] Section 5.4 | 281 | rt | 9 | [RFC6690] Section 3.1 | 282 | if | 10 | [RFC6690] Section 3.2 | 283 | sz | 11 | [RFC6690] Section 3.3 | 284 | ct | 12 | [RFC7252] Section 7.2.1 | 285 | obs | 13 | [RFC7641] Section 6 | 286 +----------+---------------+-------------------------+ 288 Table 1: Integer Encoding of common attribute names 290 This list of substitutions is fixed by the present specification; no 291 future expansion of the list is foreseen. "href" as well as all 292 attribute names in this list MUST be represented by their integer 293 substitutions and MUST NOT use the attribute name in text form. 294 Recipients MUST NOT accept documents that violate this requirement. 296 This leads to the following CDDL representation for the CBOR 297 encoding: 299 links = [* link] 300 link = { 301 href => tstr ; resource URI 302 * label => value 303 } 304 href = 1 305 label = tstr / &( 306 rel: 2, anchor: 3, rev: 4, 307 hreflang: 5, media: 6, title: 7, 308 type: 8, rt: 9, if: 10, 309 sz: 11, ct: 12, obs: 13, 310 ) 311 value = tstr ; text value -- the normal case 312 / true ; no value given, just the name 313 / [2* tstr/true ] ; repeats for two or more 315 Figure 2: CoRE Link Format Data Model (CBOR) 317 2.4. Converting JSON or CBOR to Link-Format 319 When a JSON or CBOR representation needs to be converted back to 320 link-format, the above process is performed in inverse. Since link- 321 format allows serializing link parameter values both in unqouted form 322 ("ptoken") or in quoted form ("quoted-string"), a decision has to be 323 made for each value. Where the syntax of "ptoken" does not allow the 324 value to be represented, the quoted form clearly needs to be used. 325 However, when both forms are possible, the decision is arbitrary. A 326 work-in-progress revision of [RFC5988], [I-D.nottingham-rfc5988bis], 327 clarifies that this is indeed intended to be the case. However, 328 existing specifications of link attributes, including those in 329 [RFC5988] and [RFC6690], sometimes have made this decision in a 330 specific way by only including one or the other alternative in the 331 ABNF given for a link parameter. This requires a converter to know 332 about all these cases, including those that have not been defined yet 333 at the time of writing the converter. This problem becomes even 334 harder by the fact that there is no central registry of link- 335 attribute names. 337 Obviously, the conversion back to link-format needs to result in a 338 valid link-format document. The reference implementation in 339 Appendix A has addressed this problem with the following two rules: 341 o Where a "ptoken" representation is possible, that is used instead 342 of "quoted-string". This rule covers most of the special cases 343 listed above. 345 o As a special exception to the above rule, the four link attributes 346 "anchor", "title", "rt", and "if" are always expressed as "quoted- 347 string". This rule covers these specific four cases. 349 This set of rules is based on the hope that future definitions of 350 link attributes will no longer hardcode one or the other 351 serialization. 353 2.5. Examples 355 The examples in this section are based on an example on page 15 of 356 [RFC6690] (Figure 3). 358 ;ct=40;title="Sensor Index", 359 ;rt="temperature-c";if="sensor", 360 ;rt="light-lux";if="sensor", 361 ;anchor="/sensors/temp" 362 ;rel="describedby", 363 ;anchor="/sensors/temp";rel="alternate" 365 Figure 3: Example from page 15 of [RFC6690] 367 2.5.1. Link Format to JSON Example 369 The link-format document in Figure 3 becomes (321 bytes, line breaks 370 shown are not part of the minimally-sized JSON document): 372 "[{"href":"/sensors","ct":"40","title":"Sensor 373 Index"},{"href":"/sensors/temp","rt":"temperature- 374 c","if":"sensor"},{"href":"/sensors/light","rt":"light- 375 lux","if":"sensor"},{"href":"http://www.example.com/sensors/ 376 t123","anchor":"/sensors/ 377 temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/ 378 temp","rel":"alternate"}] " 380 To demonstrate the handling of value-less and array-valued 381 attributes, we extend the link-format example by examples of these 382 (Figure 4; the "obs" attribute is defined in Section 6 of [RFC7641], 383 while the "foo" attribute is for exposition only): 385 ;ct=40;title="Sensor Index", 386 ;rt="temperature-c";if="sensor";obs, 387 ;rt="light-lux";if="sensor", 388 ;anchor="/sensors/temp" 389 ;rel="describedby";foo="bar";foo=3;ct=4711, 390 ;anchor="/sensors/temp";rel="alternate" 392 Figure 4: Example derived from page 15 of [RFC6690] 394 The link-format document in Figure 4 becomes the JSON document in 395 Figure 5 (some spacing and indentation added): 397 [{"href":"/sensors","ct":"40","title":"Sensor Index"}, 398 {"href":"/sensors/temp","rt":"temperature-c","if":"sensor", 399 "obs":true}, 400 {"href":"/sensors/light","rt":"light-lux","if":"sensor"}, 401 {"href":"http://www.example.com/sensors/t123", 402 "anchor":"/sensors/temp","rel":"describedby", 403 "foo":["bar","3"],"ct":"4711"}, 404 {"href":"/t","anchor":"/sensors/temp","rel":"alternate"}] 406 Figure 5: Example derived from page 15 of [RFC6690] 408 Note that the conversion is unable to convert the string-valued "ct" 409 attribute to a number, which would be the natural type for a Content- 410 Format value; similarly, both "foo" values are treated as strings 411 independently of whether they are quoted or numeric in syntax. 413 2.5.2. Link Format to CBOR Example 415 This examples shows conversion from link format to CBOR format. 417 The link-format document in Figure 3 becomes (in CBOR diagnostic 418 format): 420 [{1: "/sensors", 12: "40", 7: "Sensor Index"}, 421 {1: "/sensors/temp", 9: "temperature-c", 10: "sensor"}, 422 {1: "/sensors/light", 9: "light-lux", 10: "sensor"}, 423 {1: "http://www.example.com/sensors/t123", 3: "/sensors/temp", 424 2: "describedby"}, 425 {1: "/t", 3: "/sensors/temp", 2: "alternate"}] 427 or, in hexadecimal (203 bytes): 429 85 # array(number of data items:5) 430 a3 # map(# data item pairs:3) 431 01 # unsigned integer(value:1,"href") 432 68 # text string(8 bytes) 433 2f73656e736f7273 # "/sensors" 434 0c # unsigned integer(value:12,"ct") 435 62 # text(2) 436 3430 # "40" 437 07 # unsigned integer(value:7,"title") 438 6c # text string(12 bytes) 439 53656e736f7220496e646578 # "Sensor Index" 440 a3 # map(# data item pairs:3) 441 01 # unsigned integer(value:1,"href") 442 6d # text string(13 bytes) 443 2f73656e736f72732f74 444 656d70 # "/sensors/temp" 446 09 # unsigned integer(value:9,"rt") 447 6d # text string(13 bytes) 448 74656d70657261747572 449 652d63 # "temperature-c" 450 0a # unsigned integer(value:10,"if") 451 66 # text string(6 bytes) 452 73656e736f72 # "sensor" 453 a3 # map(# data item pairs:3) 454 01 # unsigned integer(value:1,"href") 455 6e # text string(14 bytes) 456 2f73656e736f72732f6c 457 69676874 # "/sensors/light" 458 09 # unsigned integer(value:9,"rt") 459 69 # text string(9 bytes) 460 6c696768742d6c7578 # "light-lux" 461 0a # unsigned integer(value:10,"if") 462 66 # text string(6 bytes) 463 73656e736f72 # "sensor" 464 a3 # map(# data item pairs:3) 465 01 # unsigned integer(value:1,"href") 466 78 23 # text string(35 bytes) 467 687474703a2f2f777777 468 2e6578616d706c652e63 469 6f6d2f73656e736f7273 470 2f74313233 # "http://www.example.com/sensors/t123" 471 03 # unsigned integer(value:3,"anchor") 472 6d # text string(13 bytes) 473 2f73656e736f72732f74 474 656d70 # "/sensors/temp" 475 02 # unsigned integer(value:2,"rel") 476 6b # text string(11 bytes) 477 6465736372696265646279 # "describedby" 478 a3 # map(# data item pairs:3) 479 01 # unsigned integer(value:1,"href") 480 62 # text string(2 bytes) 481 2f74 # "/t" 482 03 # unsigned integer(value:3,"anchor") 483 6d # text string(13 bytes) 484 2f73656e736f72732f74 485 656d70 # "/sensors/temp" 486 02 # unsigned integer(value:2,"rel") 487 69 # text string(9 bytes) 488 616c7465726e617465 # "alternate" 490 Figure 6: Web Links Encoded in CBOR 492 3. IANA Considerations 494 3.1. Media types 496 This specification registers the following additional Internet Media 497 Types: 499 Type name: application 501 Subtype name: link-format+json 503 Required parameters: None 505 Optional parameters: None 507 Encoding considerations: Resources that use the "application/link- 508 format+json" media type are required to conform to the 509 "application/json" Media Type and are therefore subject to the 510 same encoding considerations specified in [RFC7159], Section 11. 512 Security considerations: See Section 4 of [RFCthis]. 514 Published specification: [RFCthis]. 516 Applications that use this media type: Applications that interchange 517 collections of Web links based on CoRE link format [RFC6690] in 518 JSON. 520 Additional information: 522 Magic number(s): N/A 524 File extension(s): N/A 526 Macintosh file type code(s): TEXT 528 Person & email address to contact for further information: 529 Carsten Bormann 531 Intended usage: COMMON 533 Change controller: IESG 535 and 537 Type name: application 539 Subtype name: link-format+cbor 540 Required parameters: None 542 Optional parameters: None 544 Encoding considerations: Resources that use the "application/link- 545 format+cbor" media type are required to conform to the 546 "application/cbor" Media Type and are therefore subject to the 547 same encoding considerations specified in [RFC7049], Section 7. 549 Security considerations: See Section 4 of [RFCthis]. 551 Published specification: [RFCthis]. 553 Applications that use this media type: Applications that interchange 554 collections of Web links based on CoRE link format [RFC6690] in 555 CBOR. 557 Additional information: 559 Magic number(s): N/A 561 File extension(s): N/A 563 Macintosh file type code(s): CBOR 565 Person & email address to contact for further information: 566 Kepeng Li 568 Intended usage: COMMON 570 Change controller: IESG 572 3.2. CoAP Content-Format Registration 574 IANA is requested to assign CoAP Content-Format IDs for the above 575 media types in the "CoAP Content-Formats" sub-registry, within the 576 "CoRE Parameters" registry [RFC7252]. The ID for "application/link- 577 format+cbor" is assigned from the "Expert Review" (0-255) range, 578 while the ID for "application/link-format+json" is assigned from the 579 "IETF review" range. The assigned IDs are show in Table 2. 581 +------------------------------+--------+--------+-----------+ 582 | Media type | Coding | ID | Reference | 583 +------------------------------+--------+--------+-----------+ 584 | application/link-format+cbor | - | TBD64 | [RFCthis] | 585 | application/link-format+json | - | TBD504 | [RFCthis] | 586 +------------------------------+--------+--------+-----------+ 588 Table 2: CoAP Content-Format IDs 590 4. Security Considerations 592 The security considerations relevant to the data model of [RFC6690], 593 as well as those of [RFC7049] and [RFC7159] apply. 595 5. References 597 5.1. Normative References 599 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 600 Requirement Levels", BCP 14, RFC 2119, 601 DOI 10.17487/RFC2119, March 1997, 602 . 604 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 605 DOI 10.17487/RFC5988, October 2010, 606 . 608 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 609 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 610 . 612 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 613 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 614 October 2013, . 616 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 617 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 618 2014, . 620 5.2. Informative References 622 [I-D.greevenbosch-appsawg-cbor-cddl] 623 Birkholz, H., Vigano, C., and C. Bormann, "CBOR data 624 definition language (CDDL): a notational convention to 625 express CBOR data structures", draft-greevenbosch-appsawg- 626 cbor-cddl-10 (work in progress), March 2017. 628 [I-D.ietf-core-resource-directory] 629 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 630 Resource Directory", draft-ietf-core-resource-directory-10 631 (work in progress), March 2017. 633 [I-D.nottingham-rfc5988bis] 634 Nottingham, M., "Web Linking", draft-nottingham- 635 rfc5988bis-06 (work in progress), June 2017. 637 [MNOT11] Nottingham, M., "Linking in JSON", November 2011, 638 . 640 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 641 Part Three: Message Header Extensions for Non-ASCII Text", 642 RFC 2047, DOI 10.17487/RFC2047, November 1996, 643 . 645 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 646 Application Protocol (CoAP)", RFC 7252, 647 DOI 10.17487/RFC7252, June 2014, 648 . 650 [RFC7641] Hartke, K., "Observing Resources in the Constrained 651 Application Protocol (CoAP)", RFC 7641, 652 DOI 10.17487/RFC7641, September 2015, 653 . 655 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 656 the Constrained Application Protocol (CoAP)", RFC 7959, 657 DOI 10.17487/RFC7959, August 2016, 658 . 660 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 661 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 662 the Constrained Application Protocol (CoAP)", RFC 8075, 663 DOI 10.17487/RFC8075, February 2017, 664 . 666 [RUBY] "Information technology -- Programming languages -- Ruby", 667 ISO/IEC 30170:2012, April 2012. 669 Appendix A. Reference implementation 671 A reference implementation of a converter from [RFC6690] link-format 672 to JSON and CBOR (and back to link-format) in the programming 673 language Ruby [RUBY] is reproduced below. For pretty-printing the 674 binary CBOR, this uses the "cbor-diag" gem (Ruby library), which may 675 need to be installed by "gem install cbor-diag". 677 # 678 require 'strscan' 679 require 'json' 680 require 'cbor-pretty' 682 class String 683 def as_utf8 684 force_encoding(Encoding::UTF_8) 685 end 686 end 688 module CoRE 689 module Links 690 def self.map_to_true(a) 691 Hash[a.map{ |t| [t, true]}] 692 end 694 PTOKENCHAR = %r"[\[\]\w!#-+\--/:<-?^-`{-~@]" 695 QUOSTRCHAR = %r{(?:[^"\\]|\\.)} # to be used inside " 696 ATTRCHAR = %r"[\w!#$&+.^`|~-]" 697 MUSTBEQUOTED = map_to_true(%w{anchor title rt if}) 698 ANCHORNAME = "href" 699 SCANATTR = 700 %r{(#{ATTRCHAR}+)(?:=(?:(#{PTOKENCHAR}+)|"(#{QUOSTRCHAR}*)"))?} # " 702 RAWMAPPINGS = <<-DATA 703 href: 1, rel: 2, anchor: 3, 704 rev: 4, hreflang: 5, media: 6, 705 title: 7, type: 8, rt: 9, 706 if: 10, sz: 11, ct: 12, 707 obs: 13, 708 DATA 710 MAPPINGS = Hash.new {|h, k| k} 712 RAWMAPPINGS.scan(/([-\w]+)\s*:\s*([-\w]+),/) do |n, v| 713 MAPPINGS[n] = Integer(v) 714 end 716 def self.parse(*args) 717 WLNK.parse(*args) 718 end 720 class WLNK 721 attr_accessor :resources 722 def initialize(r = []) # make sure the keys are strings 723 @resources = r.to_ary # make sure it's an Array 724 end 725 def self.parse(s, robust = true) 726 wl = WLNK.new 727 ss = StringScanner.new(s.as_utf8) 728 ss.skip(/\s+/) if robust 729 while ss.scan(%r{<([^>]+)>}) 730 res = { ANCHORNAME => ss[1].as_utf8 } 731 ss.skip(/\s*/) if robust 732 while ss.skip(/;/) 733 ss.skip(/\s*/) if robust 734 unless ss.scan(SCANATTR) 735 raise ArgumentError, "must have attribute behind ';' 736 at: #{ss.peek(20).inspect} (byte #{ss.pos})" 737 end 738 key = ss[1].as_utf8 739 value = ss[2] || 740 (ss[3] ? ss[3].gsub(/\\(.)/) { $1 } : true) 741 if res[key] 742 res[key] = Array(res[key]) << value 743 else 744 res[key] = value 745 end 746 ss.skip(/\s*/) if robust 747 end 748 wl.resources << res 749 break unless ss.skip(/,/) 750 ss.skip(/\s*/) if robust 751 end 752 ss.skip(/\s*/) if robust 753 raise ArgumentError, "link-format unparseable at: 754 #{ss.peek(20).inspect} (byte #{ss.pos})" unless ss.eos? 755 wl 756 end 757 def to_json 758 JSON.pretty_generate(@resources) 759 end 760 def to_cbor 761 CBOR.encode(@resources.map {|r| 762 Hash[r.map { |k, v| [MAPPINGS[k], v] }]}) 763 end 764 def to_wlnk 765 resources.map do |res| 766 res = res.dup 767 u = res.delete(ANCHORNAME) 768 ["<#{u}>", *res.map { |k, v| wlnk_item(k, v) }].join(';') 769 end.join(",") 770 end 771 private 772 def wlnk_item(k, v) 773 case v 774 when String 775 if MUSTBEQUOTED[k] || v !~ /\A#{PTOKENCHAR}+\z/ 776 "#{k}=\"#{v.gsub(/[\\"]/) { |x| "\\#{x}"}}\"" 777 else 778 "#{k}=#{v}" 779 end 780 when Array 781 v.map{ |v1| wlnk_item(k, v1) }.join(';') 782 when true 783 "#{k}" 784 else 785 fail "Don't know how to represent #{{k=>v}.inspect}" 786 end 787 end 788 end 789 end 790 end 792 lf = CoRE::Links.parse(ARGF.read) 794 puts lf.to_json # JSON 795 puts CBOR.pretty(lf.to_cbor) # CBOR "pretty" binary form 796 puts lf.to_wlnk # RFC 6690 link-format 797 # 799 Acknowledgements 801 Special thanks to Bert Greevenbosch who was an author on the initial 802 version of a contributing document as well as the original author on 803 the CDDL notation. 805 Hannes Tschofenig made many helpful suggestions for improving this 806 document. 808 Authors' Addresses 810 Kepeng LI 811 Alibaba Group 812 Wenyixi Road, Yuhang District 813 Hangzhou, Zhejiang 311121 814 China 816 Email: kepeng.lkp@alibaba-inc.com 818 Akbar Rahman 819 InterDigital Communications, LLC 820 1000 Sherbrooke Street West 821 Montreal, Quebec H3A 3G4 822 Canada 824 Phone: +1-514-585-0761 825 Email: akbar.rahman@interdigital.com 827 Carsten Bormann (editor) 828 Universitaet Bremen TZI 829 Postfach 330440 830 Bremen D-28359 831 Germany 833 Phone: +49-421-218-63921 834 Email: cabo@tzi.org