idnits 2.17.1 draft-ietf-core-links-json-08.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (April 27, 2017) is 2555 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 539, 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-05 Summary: 3 errors (**), 0 flaws (~~), 6 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: October 29, 2017 InterDigital 6 C. Bormann, Ed. 7 Universitaet Bremen TZI 8 April 27, 2017 10 Representing Constrained RESTful Environments (CoRE) Link Format in JSON 11 and CBOR 12 draft-ietf-core-links-json-08 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 October 29, 2017. 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 . . . . . . . . . . . . . . . . . . . . . . . 3 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 . . . . . . . . . 7 75 2.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 76 2.5.1. Link Format to JSON Example . . . . . . . . . . . . . 8 77 2.5.2. Link Format to CBOR Example . . . . . . . . . . . . . 9 78 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 79 3.1. Media types . . . . . . . . . . . . . . . . . . . . . . . 11 80 3.2. CoAP Content-Format Registration . . . . . . . . . . . . 12 81 4. Security Considerations . . . . . . . . . . . . . . . . . . . 13 82 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 83 5.1. Normative References . . . . . . . . . . . . . . . . . . 13 84 5.2. Informative References . . . . . . . . . . . . . . . . . 13 85 Appendix A. Reference implementation . . . . . . . . . . . . . . 14 86 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 17 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 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 1.2. Terminology 142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 143 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 144 "OPTIONAL" in this document are to be interpreted as described in 146 [RFC2119] when they appear in ALL CAPS. These words may also appear 147 in this document in lower case as plain English words, absent their 148 normative meanings. 150 The term "byte" is used in its now customary sense as a synonym for 151 "octet". 153 CoAP: Constrained Application Protocol [RFC7252] 155 CBOR: Concise Binary Object Representation [RFC7049] 157 CoRE: Constrained RESTful Environments, the field of work underlying 158 [RFC6690], [RFC7049], [RFC7252], [RFC7641], [RFC7959], and [RFC8075] 160 IoT: Internet of Things 162 JSON: JavaScript Object Notation [RFC7159] 164 The objective of the JSON and CBOR mappings defined in this document 165 is to contain information of the formats specified in [RFC5988] and 166 [RFC6690]. This specification therefore uses the names of the ABNF 167 productions used in those documents. 169 2. Web Links in JSON and CBOR 171 2.1. Background 173 Web Linking [RFC5988] provides a way to represent links between Web 174 resources as well as the relations expressed by them and attributes 175 of such a link. In constrained networks, a collection of Web links 176 can be exchanged in the CoRE link format [RFC6690] to enable resource 177 discovery, for instance by using the CoAP protocol [RFC7252] and in 178 conjunction with the CoRE resource directory 179 [I-D.ietf-core-resource-directory]. 181 2.2. Information Model 183 This section discusses the information model underlying the CORE Link 184 Format payload. 186 An application/link-format document is a collection of Web links 187 ("link-value"), each of which is a collection of attributes ("link- 188 param") applied to a "URI-Reference". 190 We straightforwardly map: 192 o the collection of Web links to a JSON or CBOR array of links; 193 o each link to a JSON object or CBOR map, mapping attribute names to 194 attribute values. 196 In the object representing a "link-value", each target attribute or 197 other parameter ("link-param") is represented by a JSON name/value 198 pair (member). The name is a string representation of the parameter 199 or attribute name (as in "parmname"). The value can be a string, a 200 boolean, or an array of strings or booleans, as described below. 202 If the attribute value ("ptoken" or "quoted-string") is present, and 203 a Link attribute with this name ("parmname") is present just once in 204 the "link-value", the value is a string representation of the 205 parameter or attribute value ("ptoken" or "quoted-string"). "quoted- 206 string" productions are parsed (i.e, the outer quotes removed and the 207 backslash constructions evaluated) as defined in [RFC6690] and its 208 referenced documents, before placing them in JSON strings (in the 209 representation of which they may gain back additional decorations 210 such as backslashes as defined in [RFC7159]). 212 If no attribute value ("ptoken" or "quoted-string") is present, the 213 presence of the attribute name is indicated by using the Boolean 214 value "true" as the value. 216 If a Link attribute ("parmname") is present more than once in a 217 "link-value", its values are then represented as a JSON array of JSON 218 string values or "true"; this array becomes the value of the JSON 219 name/value pair where the attribute name is the JSON name. 220 Attributes occurring just once MUST NOT be represented as JSON arrays 221 but MUST be directly represented as JSON strings or "true". (Note 222 that [RFC6690] has cut down on the use of repeated parameter names; 223 they are still allowed by [RFC5988] though. No attempt has been made 224 to decode the possibly space-separated values for rt=, if=, and rel= 225 into JSON arrays.) 227 The URI-Reference is represented as a name/value pair with the name 228 "href" and the URI-Reference as the value. (Rationale: This usage is 229 consistent with the use of "href" as a query parameter for link- 230 format query filtering and with link-format reserving the link 231 parameter "href" specifically for this use [RFC6690]). 233 As a non-normative summary, the resulting structure can be 234 represented in CBOR Data Definition Language (CDDL) 235 [I-D.greevenbosch-appsawg-cbor-cddl] as: 237 links = [* link] 238 link = { 239 href: tstr ; resource URI 240 * tstr => value 241 } 242 value = tstr ; text value -- the normal case 243 / true ; no value given, just the name 244 / [2* tstr/true ] ; repeats for two or more 246 Figure 1: CoRE Link Format Data Model 248 2.3. Additional Encoding Step for CBOR 250 The above specification for JSON might have been used as is for the 251 CBOR encoding as well. However, to further reduce message sizes, an 252 extra encoding step is performed: "href" and some commonly occurring 253 attribute names are encoded as small integers. 255 The substitution is defined in Table 1: 257 +----------+---------------+-------------------------+ 258 | name | encoded value | origin | 259 +----------+---------------+-------------------------+ 260 | href | 1 | [RFC6690], [RFCthis] | 261 | rel | 2 | [RFC5988] Section 5.3 | 262 | anchor | 3 | [RFC5988] Section 5.2 | 263 | rev | 4 | [RFC5988] Section 5.3 | 264 | hreflang | 5 | [RFC5988] Section 5.4 | 265 | media | 6 | [RFC5988] Section 5.4 | 266 | title | 7 | [RFC5988] Section 5.4 | 267 | type | 8 | [RFC5988] Section 5.4 | 268 | rt | 9 | [RFC6690] Section 3.1 | 269 | if | 10 | [RFC6690] Section 3.2 | 270 | sz | 11 | [RFC6690] Section 3.3 | 271 | ct | 12 | [RFC7252] Section 7.2.1 | 272 | obs | 13 | [RFC7641] Section 6 | 273 +----------+---------------+-------------------------+ 275 Table 1: Integer Encoding of common attribute names 277 This list of substitutions is fixed by the present specification; no 278 future expansion of the list is foreseen. "href" as well as all 279 attribute names in this list MUST be represented by their integer 280 substitutions and MUST NOT use the attribute name in text form. 282 *Adam's Issue number 2: What should an implementation do that 283 receives a link-format that doesn't heed the above MUST? Is there an 284 onus to check it?* 285 This leads to the following CDDL representation for the CBOR 286 encoding: 288 links = [* link] 289 link = { 290 href => tstr ; resource URI 291 * label => value 292 } 293 href = 1 294 label = tstr / &( 295 rel: 2, anchor: 3, rev: 4, 296 hreflang: 5, media: 6, title: 7, 297 type: 8, rt: 9, if: 10, 298 sz: 11, ct: 12, obs: 13, 299 ) 300 value = tstr ; text value -- the normal case 301 / true ; no value given, just the name 302 / [2* tstr/true ] ; repeats for two or more 304 Figure 2: CoRE Link Format Data Model (CBOR) 306 2.4. Converting JSON or CBOR to Link-Format 308 When a JSON or CBOR representation needs to be converted back to 309 link-format, the above process is performed in inverse. Since link- 310 format allows serializing link parameter values both in unqouted form 311 ("ptoken") or in quoted form ("quoted-string"), a decision has to be 312 made for each value. Where the syntax of "ptoken" does not allow the 313 value to be represented, the quoted form clearly needs to be used. 314 However, when both forms are possible, the decision is arbitrary. A 315 work-in-progress revision of [RFC5988], [I-D.nottingham-rfc5988bis], 316 clarifies that this is indeed intended to be the case. However, 317 existing specifications of link attributes, including those in 318 [RFC5988] and [RFC6690], sometimes have made this decision in a 319 specific way by only including one or the other alternative in the 320 ABNF given for a link parameter. This requires a converter to know 321 about all these cases, including those that have not been defined yet 322 at the time of writing the converter. This problem becomes even 323 harder by the fact that there is no central registry of link- 324 attribute names. 326 Obviously, the conversion back to link-format needs to result in a 327 valid link-format document. The reference implementation in 328 Appendix A has addressed this problem with the following two rules: 330 o Where a "ptoken" representation is possible, that is used instead 331 of "quoted-string". This rule covers most of the special cases 332 listed above. 334 o As a special exception to the above rule, the four link attributes 335 "anchor", "title", "rt", and "if" are always expressed as "quoted- 336 string". This rule covers these specific four cases. 338 This set of rules is based on the hope that future definitions of 339 link attributes will no longer hardcode one or the other 340 serialization. 342 2.5. Examples 344 The examples in this section are based on an example on page 15 of 345 [RFC6690] (Figure 3). 347 ;ct=40;title="Sensor Index", 348 ;rt="temperature-c";if="sensor", 349 ;rt="light-lux";if="sensor", 350 ;anchor="/sensors/temp" 351 ;rel="describedby", 352 ;anchor="/sensors/temp";rel="alternate" 354 Figure 3: Example from page 15 of [RFC6690] 356 2.5.1. Link Format to JSON Example 358 The link-format document in Figure 3 becomes (321 bytes, line breaks 359 shown are not part of the minimally-sized JSON document): 361 "[{"href":"/sensors","ct":"40","title":"Sensor 362 Index"},{"href":"/sensors/temp","rt":"temperature- 363 c","if":"sensor"},{"href":"/sensors/light","rt":"light- 364 lux","if":"sensor"},{"href":"http://www.example.com/sensors/ 365 t123","anchor":"/sensors/ 366 temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/ 367 temp","rel":"alternate"}] " 369 To demonstrate the handling of value-less and array-valued 370 attributes, we extend the link-format example by examples of these 371 (Figure 4; the "obs" attribute is defined in Section 6 of [RFC7641], 372 while the "foo" attribute is for exposition only): 374 ;ct=40;title="Sensor Index", 375 ;rt="temperature-c";if="sensor";obs, 376 ;rt="light-lux";if="sensor", 377 ;anchor="/sensors/temp" 378 ;rel="describedby";foo="bar";foo=3;ct=4711, 379 ;anchor="/sensors/temp";rel="alternate" 381 Figure 4: Example derived from page 15 of [RFC6690] 383 The link-format document in Figure 4 becomes the JSON document in 384 Figure 5 (some spacing and indentation added): 386 [{"href":"/sensors","ct":"40","title":"Sensor Index"}, 387 {"href":"/sensors/temp","rt":"temperature-c","if":"sensor", 388 "obs":true}, 389 {"href":"/sensors/light","rt":"light-lux","if":"sensor"}, 390 {"href":"http://www.example.com/sensors/t123", 391 "anchor":"/sensors/temp","rel":"describedby", 392 "foo":["bar","3"],"ct":"4711"}, 393 {"href":"/t","anchor":"/sensors/temp","rel":"alternate"}] 395 Figure 5: Example derived from page 15 of [RFC6690] 397 Note that the conversion is unable to convert the string-valued "ct" 398 attribute to a number, which would be the natural type for a Content- 399 Format value; similarly, both "foo" values are treated as strings 400 independently of whether they are quoted or numeric in syntax. 402 2.5.2. Link Format to CBOR Example 404 This examples shows conversion from link format to CBOR format. 406 The link-format document in Figure 3 becomes (in CBOR diagnostic 407 format): 409 [{1: "/sensors", 12: "40", 7: "Sensor Index"}, 410 {1: "/sensors/temp", 9: "temperature-c", 10: "sensor"}, 411 {1: "/sensors/light", 9: "light-lux", 10: "sensor"}, 412 {1: "http://www.example.com/sensors/t123", 3: "/sensors/temp", 413 2: "describedby"}, 414 {1: "/t", 3: "/sensors/temp", 2: "alternate"}] 416 or, in hexadecimal (203 bytes): 418 85 # array(number of data items:5) 419 a3 # map(# data item pairs:3) 420 01 # unsigned integer(value:1,"href") 421 68 # text string(8 bytes) 422 2f73656e736f7273 # "/sensors" 423 0c # unsigned integer(value:12,"ct") 424 62 # text(2) 425 3430 # "40" 426 07 # unsigned integer(value:7,"title") 427 6c # text string(12 bytes) 428 53656e736f7220496e646578 # "Sensor Index" 429 a3 # map(# data item pairs:3) 430 01 # unsigned integer(value:1,"href") 431 6d # text string(13 bytes) 432 2f73656e736f72732f74 433 656d70 # "/sensors/temp" 434 09 # unsigned integer(value:9,"rt") 435 6d # text string(13 bytes) 436 74656d70657261747572 437 652d63 # "temperature-c" 438 0a # unsigned integer(value:10,"if") 439 66 # text string(6 bytes) 440 73656e736f72 # "sensor" 441 a3 # map(# data item pairs:3) 442 01 # unsigned integer(value:1,"href") 443 6e # text string(14 bytes) 444 2f73656e736f72732f6c 445 69676874 # "/sensors/light" 446 09 # unsigned integer(value:9,"rt") 447 69 # text string(9 bytes) 448 6c696768742d6c7578 # "light-lux" 449 0a # unsigned integer(value:10,"if") 450 66 # text string(6 bytes) 451 73656e736f72 # "sensor" 452 a3 # map(# data item pairs:3) 453 01 # unsigned integer(value:1,"href") 454 78 23 # text string(35 bytes) 455 687474703a2f2f777777 456 2e6578616d706c652e63 457 6f6d2f73656e736f7273 458 2f74313233 # "http://www.example.com/sensors/t123" 459 03 # unsigned integer(value:3,"anchor") 460 6d # text string(13 bytes) 461 2f73656e736f72732f74 462 656d70 # "/sensors/temp" 463 02 # unsigned integer(value:2,"rel") 464 6b # text string(11 bytes) 465 6465736372696265646279 # "describedby" 466 a3 # map(# data item pairs:3) 467 01 # unsigned integer(value:1,"href") 468 62 # text string(12 bytes) 469 2f74 # "/t" 470 03 # unsigned integer(value:3,"anchor") 471 6d # text string(13 bytes) 472 2f73656e736f72732f74 473 656d70 # "/sensors/temp" 474 02 # unsigned integer(value:2,"rel") 475 69 # text string(9 bytes) 476 616c7465726e617465 # "alternate" 478 Figure 6: Web Links Encoded in CBOR 480 3. IANA Considerations 482 3.1. Media types 484 This specification registers the following additional Internet Media 485 Types: 487 Type name: application 489 Subtype name: link-format+json 491 Required parameters: None 493 Optional parameters: None 495 Encoding considerations: Resources that use the "application/link- 496 format+json" media type are required to conform to the 497 "application/json" Media Type and are therefore subject to the 498 same encoding considerations specified in [RFC7159], Section 11. 500 Security considerations: See Section 4 of [RFCthis]. 502 Published specification: [RFCthis]. 504 Applications that use this media type: Applications that interchange 505 collections of Web links based on CoRE link format [RFC6690] in 506 JSON. 508 Additional information: 510 Magic number(s): N/A 512 File extension(s): N/A 514 Macintosh file type code(s): TEXT 516 Person & email address to contact for further information: 517 Carsten Bormann 519 Intended usage: COMMON 521 Change controller: IESG 523 and 525 Type name: application 527 Subtype name: link-format+cbor 528 Required parameters: None 530 Optional parameters: None 532 Encoding considerations: Resources that use the "application/link- 533 format+cbor" media type are required to conform to the 534 "application/cbor" Media Type and are therefore subject to the 535 same encoding considerations specified in [RFC7049], Section 7. 537 Security considerations: See Section 4 of [RFCthis]. 539 Published specification: [RFCthis]. 541 Applications that use this media type: Applications that interchange 542 collections of Web links based on CoRE link format [RFC6690] in 543 CBOR. 545 Additional information: 547 Magic number(s): N/A 549 File extension(s): N/A 551 Macintosh file type code(s): CBOR 553 Person & email address to contact for further information: 554 Kepeng Li 556 Intended usage: COMMON 558 Change controller: IESG 560 3.2. CoAP Content-Format Registration 562 IANA is requested to assign CoAP Content-Format IDs for the above 563 media types in the "CoAP Content-Formats" sub-registry, within the 564 "CoRE Parameters" registry [RFC7252]. All IDs are assigned from the 565 "Expert Review" (0-255) range. The assigned IDs are show in Table 2. 567 +------------------------------+-------+ 568 | Media type | ID | 569 +------------------------------+-------+ 570 | application/link-format+cbor | TBD64 | 571 | application/link-format+json | TBD54 | 572 +------------------------------+-------+ 574 Table 2: CoAP Content-Format IDs 576 4. Security Considerations 578 The security considerations relevant to the data model of [RFC6690], 579 as well as those of [RFC7049] and [RFC7159] apply. 581 5. References 583 5.1. Normative References 585 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 586 Requirement Levels", BCP 14, RFC 2119, 587 DOI 10.17487/RFC2119, March 1997, 588 . 590 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 591 DOI 10.17487/RFC5988, October 2010, 592 . 594 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 595 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 596 . 598 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 599 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 600 October 2013, . 602 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 603 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 604 2014, . 606 5.2. Informative References 608 [I-D.greevenbosch-appsawg-cbor-cddl] 609 Birkholz, H., Vigano, C., and C. Bormann, "CBOR data 610 definition language (CDDL): a notational convention to 611 express CBOR data structures", draft-greevenbosch-appsawg- 612 cbor-cddl-10 (work in progress), March 2017. 614 [I-D.ietf-core-resource-directory] 615 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 616 Resource Directory", draft-ietf-core-resource-directory-10 617 (work in progress), March 2017. 619 [I-D.nottingham-rfc5988bis] 620 Nottingham, M., "Web Linking", draft-nottingham- 621 rfc5988bis-05 (work in progress), April 2017. 623 [MNOT11] Nottingham, M., "Linking in JSON", November 2011, 624 . 626 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 627 Part Three: Message Header Extensions for Non-ASCII Text", 628 RFC 2047, DOI 10.17487/RFC2047, November 1996, 629 . 631 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 632 Application Protocol (CoAP)", RFC 7252, 633 DOI 10.17487/RFC7252, June 2014, 634 . 636 [RFC7641] Hartke, K., "Observing Resources in the Constrained 637 Application Protocol (CoAP)", RFC 7641, 638 DOI 10.17487/RFC7641, September 2015, 639 . 641 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 642 the Constrained Application Protocol (CoAP)", RFC 7959, 643 DOI 10.17487/RFC7959, August 2016, 644 . 646 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 647 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 648 the Constrained Application Protocol (CoAP)", RFC 8075, 649 DOI 10.17487/RFC8075, February 2017, 650 . 652 [RUBY] "Information technology -- Programming languages -- Ruby", 653 ISO/IEC 30170:2012, April 2012. 655 Appendix A. Reference implementation 657 A reference implementation of a converter from [RFC6690] link-format 658 to JSON and CBOR (and back to link-format) in the programming 659 language Ruby [RUBY] is reproduced below. 661 # 662 require 'strscan' 663 require 'json' 664 require 'cbor-pretty' 666 class String 667 def as_utf8 668 force_encoding(Encoding::UTF_8) 669 end 670 end 671 module CoRE 672 module Links 673 def self.map_to_true(a) 674 Hash[a.map{ |t| [t, true]}] 675 end 677 PTOKENCHAR = %r"[\[\]\w!#-+\--/:<-?^-`{-~@]" 678 QUOSTRCHAR = %r{(?:[^"\\]|\\.)} # to be used inside " 679 ATTRCHAR = %r"[\w!#$&+.^`|~-]" 680 MUSTBEQUOTED = map_to_true(%w{anchor title rt if}) 681 ANCHORNAME = "href" 682 SCANATTR = 683 %r{(#{ATTRCHAR}+)(?:=(?:(#{PTOKENCHAR}+)|"(#{QUOSTRCHAR}*)"))?} # " 685 RAWMAPPINGS = <<-DATA 686 href: 1, rel: 2, anchor: 3, 687 rev: 4, hreflang: 5, media: 6, 688 title: 7, type: 8, rt: 9, 689 if: 10, sz: 11, ct: 12, 690 obs: 13, 691 DATA 693 MAPPINGS = Hash.new {|h, k| k} 695 RAWMAPPINGS.scan(/([-\w]+)\s*:\s*([-\w]+),/) do |n, v| 696 MAPPINGS[n] = Integer(v) 697 end 699 def self.parse(*args) 700 WLNK.parse(*args) 701 end 703 class WLNK 704 attr_accessor :resources 705 def initialize(r = []) # make sure the keys are strings 706 @resources = r.to_ary # make sure it's an Array 707 end 708 def self.parse(s, robust = true) 709 wl = WLNK.new 710 ss = StringScanner.new(s.as_utf8) 711 ss.skip(/\s+/) if robust 712 while ss.scan(%r{<([^>]+)>}) 713 res = { ANCHORNAME => ss[1].as_utf8 } 714 ss.skip(/\s*/) if robust 715 while ss.skip(/;/) 716 ss.skip(/\s*/) if robust 717 unless ss.scan(SCANATTR) 718 raise ArgumentError, "must have attribute behind ';' 719 at: #{ss.peek(20).inspect} (byte #{ss.pos})" 720 end 721 key = ss[1].as_utf8 722 value = ss[2] || 723 (ss[3] ? ss[3].gsub(/\\(.)/) { $1 } : true) 724 if res[key] 725 res[key] = Array(res[key]) << value 726 else 727 res[key] = value 728 end 729 ss.skip(/\s*/) if robust 730 end 731 wl.resources << res 732 break unless ss.skip(/,/) 733 ss.skip(/\s*/) if robust 734 end 735 ss.skip(/\s*/) if robust 736 raise ArgumentError, "link-format unparseable at: 737 #{ss.peek(20).inspect} (byte #{ss.pos})" unless ss.eos? 738 wl 739 end 740 def to_json 741 JSON.pretty_generate(@resources) 742 end 743 def to_cbor 744 CBOR.encode(@resources.map {|r| 745 Hash[r.map { |k, v| [MAPPINGS[k], v] }]}) 746 end 747 def to_wlnk 748 resources.map do |res| 749 res = res.dup 750 u = res.delete(ANCHORNAME) 751 ["<#{u}>", *res.map do |k, v| 752 if String === v 753 if MUSTBEQUOTED[k] || v !~ /\A#{PTOKENCHAR}+\z/ 754 "#{k}=\"#{v.gsub(/[\\"]/) { |x| "\\#{x}"}}\"" 755 else 756 "#{k}=#{v}" 757 end 758 else 759 "#{k}" 760 end 761 end].join(';') 762 end.join(",") 763 end 764 end 765 end 766 end 767 lf = CoRE::Links.parse(ARGF.read) 769 puts lf.to_json # JSON 770 puts CBOR.pretty(lf.to_cbor) # CBOR "pretty" binary form 771 puts lf.to_wlnk # RFC 6690 link-format 772 # 774 Acknowledgements 776 Special thanks to Bert Greevenbosch who was an author on the initial 777 version of a contributing document as well as the original author on 778 the CDDL notation. 780 Hannes Tschofenig made many helpful suggestions for improving this 781 document. 783 Authors' Addresses 785 Kepeng LI 786 Alibaba Group 787 Wenyixi Road, Yuhang District 788 Hangzhou, Zhejiang 311121 789 China 791 Email: kepeng.lkp@alibaba-inc.com 793 Akbar Rahman 794 InterDigital Communications, LLC 795 1000 Sherbrooke Street West 796 Montreal, Quebec H3A 3G4 797 Canada 799 Phone: +1-514-585-0761 800 Email: akbar.rahman@interdigital.com 802 Carsten Bormann (editor) 803 Universitaet Bremen TZI 804 Postfach 330440 805 Bremen D-28359 806 Germany 808 Phone: +49-421-218-63921 809 Email: cabo@tzi.org