idnits 2.17.1 draft-ietf-core-links-json-07.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 (March 13, 2017) is 2600 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 251, 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-09 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-10 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: September 14, 2017 InterDigital 6 C. Bormann, Ed. 7 Universitaet Bremen TZI 8 March 13, 2017 10 Representing CoRE Formats in JSON and CBOR 11 draft-ietf-core-links-json-07 13 Abstract 15 JavaScript Object Notation, JSON (RFC7159) is a text-based data 16 format which is popular for Web based data exchange. Concise Binary 17 Object Representation, CBOR (RFC7049) is a binary data format which 18 has been optimized for data exchange for the Internet of Things 19 (IoT). For many IoT scenarios, CBOR formats will be preferred since 20 it can help decrease transmission payload sizes as well as 21 implementation code sizes compared to other data formats. 23 Web Linking (RFC5988) provides a way to represent links between Web 24 resources as well as the relations expressed by them and attributes 25 of such a link. In constrained networks, a collection of Web links 26 can be exchanged in the CoRE link format (RFC6690). Outside of 27 constrained environments, it may be useful to represent these 28 collections of Web links in JSON, and similarly, inside constrained 29 environments, in CBOR. This specification defines a common format 30 for this. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on September 14, 2017. 49 Copyright Notice 51 Copyright (c) 2017 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 67 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 69 2. Web Links in JSON and CBOR . . . . . . . . . . . . . . . . . 4 70 2.1. Background . . . . . . . . . . . . . . . . . . . . . . . 4 71 2.2. Information Model . . . . . . . . . . . . . . . . . . . . 4 72 2.3. Additional Encoding Step for CBOR . . . . . . . . . . . . 6 73 2.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7 74 2.4.1. Link Format to JSON Example . . . . . . . . . . . . . 7 75 2.4.2. Link Format to CBOR Example . . . . . . . . . . . . . 8 76 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 77 3.1. Media types . . . . . . . . . . . . . . . . . . . . . . . 10 78 3.2. CoAP Content-Format Registration . . . . . . . . . . . . 12 79 4. Security Considerations . . . . . . . . . . . . . . . . . . . 13 80 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 81 5.1. Normative References . . . . . . . . . . . . . . . . . . 13 82 5.2. Informative References . . . . . . . . . . . . . . . . . 13 83 Appendix A. Reference implementation . . . . . . . . . . . . . . 14 84 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 17 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 87 1. Introduction 89 Web Linking [RFC5988] provides a way to represent links between Web 90 resources as well as the relations expressed by them and attributes 91 of such a link. In constrained networks, a collection of Web links 92 can be exchanged in the CoRE link format [RFC6690] to enable resource 93 discovery, for instance by using the CoAP protocol [RFC7252]. 95 The JavaScript Object Notation (JSON) [RFC7159] is a lightweight, 96 text-based, language-independent data interchange format. JSON is 97 popular in the Web development environment as it is easy for humans 98 to read and write. 100 The Concise Binary Object Representation (CBOR) [RFC7049] is a binary 101 data format which requires extremely small code size, allows very 102 compact message representation, and provides extensibility without 103 the need for version negotiation. CBOR is especially well suited for 104 IoT environments because of these efficiencies. 106 When converting between a bespoke syntax such as that defined by 107 [RFC6690] and JSON or CBOR, many small decisions have to be made. If 108 left without guidance, it is likely that a number of slightly 109 incompatible dialects will emerge. This specification defines a 110 common approach for translating between the CoRE-specific bespoke 111 formats, JSON and CBOR formats. Where applicable, mapping from other 112 formats (e.g. CoRE Link Format) into JSON or CBOR is also described. 114 This specification defines a common format for representing CoRE Web 115 Linking in JSON and CBOR. 117 Note that there is a separate question on how to represent Web links 118 pointing out of JSON documents, as discussed e.g. in [MNOT11]. While 119 there are good reasons to stay as compatible as possible to 120 developments in this area, the present specification is solving a 121 different problem. 123 1.1. Objectives 125 This specification has been designed based on the following 126 objectives: 128 o Canonical mapping 130 * lossless round-tripping with [RFC6690] and between JSON and 131 CBOR 133 * but not trying for bit-preserving (DER-style) round-tripping 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 outer collection to an 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 is a string 200 representation of the parameter or attribute value ("ptoken" or 201 "quoted-string"). "quoted-string" productions are parsed (i.e, the 202 outer quotes removed and the backslash constructions evaluated) as 203 defined in [RFC6690] and its referenced documents, before placing 204 them in JSON strings (in the representation of which they may gain 205 back additional decorations such as backslashes as defined in 206 [RFC7159]). 208 If no attribute value ("ptoken" or "quoted-string") is present, the 209 presence of the attribute name is indicated by using the Boolean 210 value "true" as the value. 212 If a Link attribute ("parmname") is present more than once in a 213 "link-value", its values are then represented as a JSON array of JSON 214 string values; this array becomes the value of the JSON name/value 215 pair where the attribute name is the JSON name. Attributes occurring 216 just once MUST NOT be represented as JSON arrays but MUST be directly 217 represented as JSON strings. (Note that [RFC6690] has cut down on 218 the use of repeated parameter names; they are still allowed by 219 [RFC5988] though. No attempt has been made to decode the possibly 220 space-separated values for rt=, if=, and rel= into JSON arrays.) 222 The URI-Reference is represented as a name/value pair with the name 223 "href" and the URI-Reference as the value. (Rationale: This usage is 224 consistent with the use of "href" as a query parameter for link- 225 format query filtering and with link-format reserving the link 226 parameter "href" specifically for this use [RFC6690]). 228 The resulting structure can be represented in CDDL 229 [I-D.greevenbosch-appsawg-cbor-cddl] as: 231 links = [* link] 232 link = { 233 href: tstr ; resource URI 234 * tstr => tstr / true 235 } 237 Figure 1: CoRE Link Format Data Model 239 2.3. Additional Encoding Step for CBOR 241 The above specification for JSON could be used as is for the CBOR 242 encoding as well. However, to further reduce message sizes, an extra 243 encoding step is performed: "href" and some commonly occurring 244 attribute names are encoded as small integers. 246 The substitution is summarized below: 248 +----------+---------------+-------------------------+ 249 | name | encoded value | reference | 250 +----------+---------------+-------------------------+ 251 | href | 1 | [RFC6690], [RFCthis] | 252 | rel | 2 | [RFC5988] Section 5.3 | 253 | anchor | 3 | [RFC5988] Section 5.2 | 254 | rev | 4 | [RFC5988] Section 5.3 | 255 | hreflang | 5 | [RFC5988] Section 5.4 | 256 | media | 6 | [RFC5988] Section 5.4 | 257 | title | 7 | [RFC5988] Section 5.4 | 258 | type | 8 | [RFC5988] Section 5.4 | 259 | rt | 9 | [RFC6690] Section 3.1 | 260 | if | 10 | [RFC6690] Section 3.2 | 261 | sz | 11 | [RFC6690] Section 3.3 | 262 | ct | 12 | [RFC7252] Section 7.2.1 | 263 | obs | 13 | [RFC7641] Section 6 | 264 +----------+---------------+-------------------------+ 266 Table 1: Integer Encoding of common attribute names 268 (Comment to be deleted before submitting this document to the IESG: 269 This list should, again, be checked against relevant references at 270 WGLC time.) 272 This list of substitutions is fixed by the present specification; no 273 future expansion of the list is foreseen. "href" as well as all 274 attribute names in this list MUST be represented by their integer 275 substitutions and MUST NOT use the attribute name in text form. 277 This leads to the following CDDL representation for the CBOR 278 encoding: 280 links = [* link] 281 link = { 282 href => tstr ; resource URI 283 * label => tstr / true 284 } 285 href = 1 286 label = tstr / &( 287 rel: 2, anchor: 3, rev: 4, 288 hreflang: 5, media: 6, title: 7, 289 type: 8, rt: 9, if: 10, 290 sz: 11, ct: 12, obs: 13, 291 ) 293 Figure 2: CoRE Link Format Data Model (CBOR) 295 2.4. Examples 297 The examples in this section are based on an example on page 15 of 298 [RFC6690] (Figure 3). 300 ;ct=40;title="Sensor Index", 301 ;rt="temperature-c";if="sensor", 302 ;rt="light-lux";if="sensor", 303 ;anchor="/sensors/temp" 304 ;rel="describedby", 305 ;anchor="/sensors/temp";rel="alternate" 307 Figure 3: Example from page 15 of [RFC6690] 309 2.4.1. Link Format to JSON Example 311 The link-format document in Figure 3 becomes (321 bytes, line breaks 312 shown are not part of the minimally-sized JSON document): 314 "[{"href":"/sensors","ct":"40","title":"Sensor 315 Index"},{"href":"/sensors/temp","rt":"temperature- 316 c","if":"sensor"},{"href":"/sensors/light","rt":"light- 317 lux","if":"sensor"},{"href":"http://www.example.com/sensors/ 318 t123","anchor":"/sensors/ 319 temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/ 320 temp","rel":"alternate"}] " 322 To demonstrate the handling of value-less and array-valued 323 attributes, we extend the link-format example by examples of these 324 (Figure 4; the "obs" attribute is defined in Section 6 of [RFC7641], 325 while the "foo" attribute is for exposition only): 327 ;ct=40;title="Sensor Index", 328 ;rt="temperature-c";if="sensor";obs, 329 ;rt="light-lux";if="sensor", 330 ;anchor="/sensors/temp" 331 ;rel="describedby";foo="bar";foo=3;ct=4711, 332 ;anchor="/sensors/temp";rel="alternate" 334 Figure 4: Example derived from page 15 of [RFC6690] 336 The link-format document in Figure 4 becomes the JSON document in 337 Figure 5 (some spacing and indentation added): 339 [{"href":"/sensors","ct":"40","title":"Sensor Index"}, 340 {"href":"/sensors/temp","rt":"temperature-c","if":"sensor", 341 "obs":true}, 342 {"href":"/sensors/light","rt":"light-lux","if":"sensor"}, 343 {"href":"http://www.example.com/sensors/t123", 344 "anchor":"/sensors/temp","rel":"describedby", 345 "foo":["bar","3"],"ct":"4711"}, 346 {"href":"/t","anchor":"/sensors/temp","rel":"alternate"}] 348 Figure 5: Example derived from page 15 of [RFC6690] 350 Note that the conversion is unable to convert the string-valued "ct" 351 attribute to a number, which would be the natural type for a Content- 352 Format value; similarly, both "foo" values are treated as strings 353 independently of whether they are quoted or numeric in syntax. 355 2.4.2. Link Format to CBOR Example 357 This examples shows conversion from link format to CBOR format. 359 The link-format document in Figure 3 becomes (in CBOR diagnostic 360 format): 362 [{1: "/sensors", 12: "40", 7: "Sensor Index"}, 363 {1: "/sensors/temp", 9: "temperature-c", 10: "sensor"}, 364 {1: "/sensors/light", 9: "light-lux", 10: "sensor"}, 365 {1: "http://www.example.com/sensors/t123", 3: "/sensors/temp", 366 2: "describedby"}, 367 {1: "/t", 3: "/sensors/temp", 2: "alternate"}] 369 or, in hexadecimal (203 bytes): 371 85 # array(number of data items:5) 372 a3 # map(# data item pairs:3) 373 01 # unsigned integer(value:1,"href") 374 68 # text string(8 bytes) 375 2f73656e736f7273 # "/sensors" 376 0c # unsigned integer(value:12,"ct") 377 62 # text(2) 378 3430 # "40" 379 07 # unsigned integer(value:7,"title") 380 6c # text string(12 bytes) 381 53656e736f7220496e646578 # "Sensor Index" 382 a3 # map(# data item pairs:3) 383 01 # unsigned integer(value:1,"href") 384 6d # text string(13 bytes) 385 2f73656e736f72732f74 386 656d70 # "/sensors/temp" 387 09 # unsigned integer(value:9,"rt") 388 6d # text string(13 bytes) 389 74656d70657261747572 390 652d63 # "temperature-c" 391 0a # unsigned integer(value:10,"if") 392 66 # text string(6 bytes) 393 73656e736f72 # "sensor" 394 a3 # map(# data item pairs:3) 395 01 # unsigned integer(value:1,"href") 396 6e # text string(14 bytes) 397 2f73656e736f72732f6c 398 69676874 # "/sensors/light" 399 09 # unsigned integer(value:9,"rt") 400 69 # text string(9 bytes) 401 6c696768742d6c7578 # "light-lux" 402 0a # unsigned integer(value:10,"if") 403 66 # text string(6 bytes) 404 73656e736f72 # "sensor" 405 a3 # map(# data item pairs:3) 406 01 # unsigned integer(value:1,"href") 407 78 23 # text string(35 bytes) 408 687474703a2f2f777777 409 2e6578616d706c652e63 410 6f6d2f73656e736f7273 411 2f74313233 # "http://www.example.com/sensors/t123" 412 03 # unsigned integer(value:3,"anchor") 413 6d # text string(13 bytes) 414 2f73656e736f72732f74 415 656d70 # "/sensors/temp" 416 02 # unsigned integer(value:2,"rel") 417 6b # text string(11 bytes) 418 6465736372696265646279 # "describedby" 419 a3 # map(# data item pairs:3) 420 01 # unsigned integer(value:1,"href") 421 62 # text string(12 bytes) 422 2f74 # "/t" 424 03 # unsigned integer(value:3,"anchor") 425 6d # text string(13 bytes) 426 2f73656e736f72732f74 427 656d70 # "/sensors/temp" 428 02 # unsigned integer(value:2,"rel") 429 69 # text string(9 bytes) 430 616c7465726e617465 # "alternate" 432 Figure 6: Web Links Encoded in CBOR 434 3. IANA Considerations 436 3.1. Media types 438 This specification registers the following additional Internet Media 439 Types: 441 Type name: application 443 Subtype name: link-format+json 445 Required parameters: None 447 Optional parameters: None 449 Encoding considerations: Resources that use the "application/ 450 link-format+json" media type are required to conform to the 451 "application/json" Media Type and are therefore subject to the 452 same encoding considerations specified in [RFC7159], Section 11. 454 Security considerations: As defined in this specification 456 Published specification: This specification. 458 Applications that use this media type: None currently known. 460 Additional information: 462 Magic number(s): N/A 464 File extension(s): N/A 466 Macintosh file type code(s): TEXT 468 Person & email address to contact for further information: 469 Carsten Bormann 471 Intended usage: COMMON 473 Change controller: IESG 475 and 476 Type name: application 478 Subtype name: link-format+cbor 480 Required parameters: None 482 Optional parameters: None 484 Encoding considerations: Resources that use the "application/ 485 link-format+cbor" media type are required to conform to the 486 "application/cbor" Media Type and are therefore subject to the 487 same encoding considerations specified in [RFC7049], Section 7. 489 Security considerations: As defined in this specification 491 Published specification: This specification. 493 Applications that use this media type: None currently known. 495 Additional information: 497 Magic number(s): N/A 499 File extension(s): N/A 501 Macintosh file type code(s): CBOR 503 Person & email address to contact for further information: 504 Kepeng Li 506 Intended usage: COMMON 508 Change controller: IESG 510 3.2. CoAP Content-Format Registration 512 IANA is requested to assign CoAP Content-Format IDs for the above 513 media types in the "CoAP Content-Formats" sub-registry, within the 514 "CoRE Parameters" registry [RFC7252]. All IDs are assigned from the 515 "Expert Review" (0-255) range. The assigned IDs are show in Table 2. 517 +------------------------------+-------+ 518 | Media type | ID | 519 +------------------------------+-------+ 520 | application/link-format+cbor | TBD64 | 521 | application/link-format+cbor | TBD54 | 522 +------------------------------+-------+ 524 Table 2: CoAP Content-Format IDs 526 4. Security Considerations 528 The security considerations relevant to the data model of [RFC6690], 529 as well as those of [RFC7049] and [RFC7159] apply. 531 5. References 533 5.1. Normative References 535 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 536 Requirement Levels", BCP 14, RFC 2119, 537 DOI 10.17487/RFC2119, March 1997, 538 . 540 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 541 DOI 10.17487/RFC5988, October 2010, 542 . 544 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 545 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 546 . 548 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 549 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 550 October 2013, . 552 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 553 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 554 2014, . 556 5.2. Informative References 558 [I-D.greevenbosch-appsawg-cbor-cddl] 559 Vigano, C. and H. Birkholz, "CBOR data definition language 560 (CDDL): a notational convention to express CBOR data 561 structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work 562 in progress), September 2016. 564 [I-D.ietf-core-resource-directory] 565 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 566 Resource Directory", draft-ietf-core-resource-directory-10 567 (work in progress), March 2017. 569 [MNOT11] Nottingham, M., "Linking in JSON", November 2011, 570 . 572 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 573 Part Three: Message Header Extensions for Non-ASCII Text", 574 RFC 2047, DOI 10.17487/RFC2047, November 1996, 575 . 577 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 578 Application Protocol (CoAP)", RFC 7252, 579 DOI 10.17487/RFC7252, June 2014, 580 . 582 [RFC7641] Hartke, K., "Observing Resources in the Constrained 583 Application Protocol (CoAP)", RFC 7641, 584 DOI 10.17487/RFC7641, September 2015, 585 . 587 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 588 the Constrained Application Protocol (CoAP)", RFC 7959, 589 DOI 10.17487/RFC7959, August 2016, 590 . 592 [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and 593 E. Dijk, "Guidelines for Mapping Implementations: HTTP to 594 the Constrained Application Protocol (CoAP)", RFC 8075, 595 DOI 10.17487/RFC8075, February 2017, 596 . 598 [RUBY] "Information technology -- Programming languages -- Ruby", 599 ISO/IEC 30170:2012, April 2012. 601 Appendix A. Reference implementation 603 A reference implementation of a converter from [RFC6690] link-format 604 to JSON and CBOR (and back to link-format) in the programming 605 language Ruby [RUBY] is reproduced below. 607 # 608 require 'strscan' 609 require 'json' 610 require 'cbor-pretty' 611 class String 612 def as_utf8 613 force_encoding(Encoding::UTF_8) 614 end 615 end 617 module CoRE 618 module Links 619 def self.map_to_true(a) 620 Hash[a.map{ |t| [t, true]}] 621 end 623 PTOKENCHAR = %r"[\[\]\w!#-+\--/:<-?^-`{-~@]" 624 QUOSTRCHAR = %r{(?:[^"\\]|\\.)} # to be used inside " 625 ATTRCHAR = %r"[\w!#$&+.^`|~-]" 626 MUSTBEQUOTED = map_to_true(%w{anchor title rt if}) 627 ANCHORNAME = "href" 628 SCANATTR = 629 %r{(#{ATTRCHAR}+)(?:=(?:(#{PTOKENCHAR}+)|"(#{QUOSTRCHAR}*)"))?} # " 631 RAWMAPPINGS = <<-DATA 632 href: 1, rel: 2, anchor: 3, 633 rev: 4, hreflang: 5, media: 6, 634 title: 7, type: 8, rt: 9, 635 if: 10, sz: 11, ct: 12, 636 obs: 13, 637 DATA 639 MAPPINGS = Hash.new {|h, k| k} 641 RAWMAPPINGS.scan(/([-\w]+)\s*:\s*([-\w]+),/) do |n, v| 642 MAPPINGS[n] = Integer(v) 643 end 645 def self.parse(*args) 646 WLNK.parse(*args) 647 end 649 class WLNK 650 attr_accessor :resources 651 def initialize(r = []) # make sure the keys are strings 652 @resources = r.to_ary # make sure it's an Array 653 end 654 def self.parse(s, robust = true) 655 wl = WLNK.new 656 ss = StringScanner.new(s.as_utf8) 657 ss.skip(/\s+/) if robust 658 while ss.scan(%r{<([^>]+)>}) 659 res = { ANCHORNAME => ss[1].as_utf8 } 660 ss.skip(/\s*/) if robust 661 while ss.skip(/;/) 662 ss.skip(/\s*/) if robust 663 unless ss.scan(SCANATTR) 664 raise ArgumentError, "must have attribute behind ';' 665 at: #{ss.peek(20).inspect} (byte #{ss.pos})" 666 end 667 key = ss[1].as_utf8 668 value = ss[2] || 669 (ss[3] ? ss[3].gsub(/\\(.)/) { $1 } : true) 670 if res[key] 671 res[key] = Array(res[key]) << value 672 else 673 res[key] = value 674 end 675 ss.skip(/\s*/) if robust 676 end 677 wl.resources << res 678 break unless ss.skip(/,/) 679 ss.skip(/\s*/) if robust 680 end 681 ss.skip(/\s*/) if robust 682 raise ArgumentError, "link-format unparseable at: 683 #{ss.peek(20).inspect} (byte #{ss.pos})" unless ss.eos? 684 wl 685 end 686 def to_json 687 JSON.pretty_generate(@resources) 688 end 689 def to_cbor 690 CBOR.encode(@resources.map {|r| 691 Hash[r.map { |k, v| [MAPPINGS[k], v] }]}) 692 end 693 def to_wlnk 694 resources.map do |res| 695 res = res.dup 696 u = res.delete(ANCHORNAME) 697 ["<#{u}>", *res.map do |k, v| 698 if String === v 699 if MUSTBEQUOTED[k] || v !~ /\A#{PTOKENCHAR}+\z/ 700 "#{k}=\"#{v.gsub(/[\\"]/) { |x| "\\#{x}"}}\"" 701 else 702 "#{k}=#{v}" 703 end 704 else 705 "#{k}" 706 end 708 end].join(';') 709 end.join(",") 710 end 711 end 712 end 713 end 715 lf = CoRE::Links.parse(ARGF.read) 717 puts lf.to_json # JSON 718 puts CBOR.pretty(lf.to_cbor) # CBOR "pretty" binary form 719 puts lf.to_wlnk # RFC 6690 link-format 720 # 722 Acknowledgements 724 Special thanks to Bert Greevenbosch who was an author on the initial 725 version of a contributing document as well as the original author on 726 the CDDL notation. 728 Hannes Tschofenig made many helpful suggestions for improving this 729 document. 731 Authors' Addresses 733 Kepeng LI 734 Alibaba Group 735 Wenyixi Road, Yuhang District 736 Hangzhou, Zhejiang 311121 737 China 739 Email: kepeng.lkp@alibaba-inc.com 741 Akbar Rahman 742 InterDigital Communications, LLC 743 1000 Sherbrooke Street West 744 Montreal, Quebec H3A 3G4 745 Canada 747 Phone: +1-514-585-0761 748 Email: akbar.rahman@interdigital.com 750 Carsten Bormann (editor) 751 Universitaet Bremen TZI 752 Postfach 330440 753 Bremen D-28359 754 Germany 756 Phone: +49-421-218-63921 757 Email: cabo@tzi.org