idnits 2.17.1 draft-li-core-cbor-equivalents-00.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 : ---------------------------------------------------------------------------- ** There are 35 instances of too long lines in the document, the longest one being 65 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (March 9, 2015) is 3335 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: 'RFC7252' is mentioned on line 130, 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) ** Downref: Normative reference to an Experimental RFC: RFC 7390 == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-02 Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 core K. Li 3 Internet-Draft Alibaba Group 4 Intended status: Standards Track R. Sun 5 Expires: September 10, 2015 Huawei Technologies 6 A. Rahman 7 InterDigital 8 March 9, 2015 10 CBOR Equivalents of CoRE JSON Formats 11 draft-li-core-cbor-equivalents-00 13 Abstract 15 JSON (RFC7159) is a text-based data format which is popular for Web 16 based data exchanges. CBOR (RFC7049) is a binary data format which 17 has been optimized for data exchanges for the Internet of Things. 18 For many IoT scenarios, CBOR formats will be preferred since it can 19 decrease transmission payload sizes compared to other data formats. 21 This specification defines an approach for translating JSON objects, 22 which are relevant for the CoRE WG and its related specifications, 23 into CBOR format. Where applicable, mapping from other formats into 24 JSON or CBOR is also described. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on September 10, 2015. 43 Copyright Notice 45 Copyright (c) 2015 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Web Links in CBOR . . . . . . . . . . . . . . . . . . . . . . 3 64 2.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3 65 2.2. Information Model . . . . . . . . . . . . . . . . . . . . 3 66 2.3. Encoding Step . . . . . . . . . . . . . . . . . . . . . . 4 67 2.4. Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 2.4.1. Link Format to CBOR Example . . . . . . . . . . . . . 6 69 2.4.2. Link Format in JSON to CBOR Example . . . . . . . . . 7 70 3. Group Communication Management Objects in CBOR . . . . . . . 9 71 3.1. Background . . . . . . . . . . . . . . . . . . . . . . . 9 72 3.2. Information Model . . . . . . . . . . . . . . . . . . . . 9 73 3.3. Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 3.4. Group Communication Example . . . . . . . . . . . . . . . 9 75 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 76 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 77 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 78 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 79 7.1. Normative References . . . . . . . . . . . . . . . . . . 12 80 7.2. Informative References . . . . . . . . . . . . . . . . . 12 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 83 1. Introduction 85 1.1. Objectives 87 The JavaScript Object Notation (JSON) [RFC7159] is a lightweight, 88 text-based, language-independent data interchange format. JSON is 89 popular in the Web development environment as it is particularly easy 90 for humans to read and write. 92 The Concise Binary Object Representation (CBOR) [RFC7049] is a binary 93 data format which requires extremely small code size, allows very 94 compact message representation, and provides extensibility without 95 the need for version negotiation. CBOR is especially well suited for 96 IoT environments because of its efficiency. 98 When converting between JSON and CBOR, as usual, many small decisions 99 have to be made. If left without guidance, it is likely that a 100 number of slightly incompatible dialects will emerge. This 101 specification defines a common approach for translating JSON objects 102 into CBOR format which are relevant for the CoRE WG and its related 103 specifications. Where applicable, mapping from other formats (e.g. 104 CoRE Link Format) into JSON or CBOR is also described. 106 1.2. Terminology 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 110 document are to be interpreted as described in [RFC2119]. 112 CoAP: Constrained Application Protocol 114 CBOR: Concise Binary Object Representation 116 CoRE: Constrained RESTful Environments 118 IoT: Internet of Things 120 JSON: JavaScript Object Notation 122 2. Web Links in CBOR 124 2.1. Background 126 Web Linking [RFC5988] provides a way to represent links between Web 127 resources as well as the relations expressed by them and attributes 128 of such a link. In constrained networks, a collection of Web links 129 can be exchanged in the CoRE link format [RFC6690] to enable resource 130 discovery, for instance by using the CoAP protocol [RFC7252]. 131 [I-D.ietf-core-links-json] defines a common format for representing 132 Web links in JSON format. 134 2.2. Information Model 136 This section discusses the information model underlying the CORE Link 137 Format payload. 139 An application/link-format document is a collection of web links 140 ("link-value"), each of which is a collection of attributes ("link- 141 param") applied to a "URI-Reference". 143 The URI-Reference is represented as a name/value pair with the name 144 "href" and the URI-Reference as the value. 146 The link attributes are also represented as name/value pairs with 147 attribute names and attribute values. 149 The information model of the CoRE Link Format can be summarized 150 below: 152 +------------------+--------------------+ 153 | name | value | 154 +------------------+--------------------+ 155 | href | resource URI | 156 +------------------+--------------------+ 157 | attribute name 1 | attribute value 1 | 158 +------------------+--------------------+ 159 | attribute name 2 | attribute value 2 | 160 +------------------+--------------------+ 161 | ... | ... | 162 +------------------+--------------------+ 163 | attribute name n | attribute value n | 164 +------------------+--------------------+ 166 Figure 1: CoRE Link Format Information Model 168 2.3. Encoding Step 170 To reduce message size, it would be beneficial to perform an extra 171 encoding step, and encode "href" and the standardized attribute names 172 specified in [RFC5988] and [RFC6690] as integers. 174 The encoding is summarized below: 176 +----------+---------------+ 177 | name | encoded value | 178 +----------+---------------+ 179 | href | 1 | 180 +----------+---------------+ 181 | rel | 2 | 182 +----------+---------------+ 183 | anchor | 3 | 184 +----------+---------------+ 185 | rev | 4 | 186 +----------+---------------+ 187 | hreflang | 5 | 188 +----------+---------------+ 189 | media | 6 | 190 +----------+---------------+ 191 | title | 7 | 192 +----------+---------------+ 193 | type | 8 | 194 +----------+---------------+ 195 | rt | 9 | 196 +----------+---------------+ 197 | if | 10 | 198 +----------+---------------+ 199 | sz | 11 | 200 +----------+---------------+ 201 | ct | 12 | 202 +----------+---------------+ 204 Figure 2: Link Attributes Encoding 206 2.4. Mapping 208 The objective of the mapping defined in this section is to map 209 information from the JSON formats specified in [RFC6690] into CBOR 210 format. 212 We straightforwardly map: 214 o the outer collection to an array of links (Major type 4) 216 o each link to a map of pairs of data items (Major type 5) 218 In the object representing a "link-value", each target attribute or 219 other parameter ("link-param") is represented by a CBOR pair of data 220 items. 222 The URI-Reference is represented as a name/value pair with the name 223 "href" and the URI-Reference as the value. 225 2.4.1. Link Format to CBOR Example 227 This examples shows conversion from link format to CBOR format. 229 ;ct=40;title="Sensor Index", 230 ;rt="temperature-c";if="sensor", 231 ;rt="light-lux";if="sensor", 232 ;anchor="/sensors/temp" 233 ;rel="describedby", 234 ;anchor="/sensors/temp";rel="alternate" 236 Figure 3: Example from page 15 of [RFC6690] 238 becomes 240 85 # array(number of data items:5) 241 a3 # map(number of pairs of data items:3) 242 01 # unsigned integer(value:1, "href") 243 68 # text string(8 bytes) 244 2f73656e736f7273 # "/sensors" 245 0c # unsigned integer(value:12,"ct") 246 18 28 # unsigned integer(value:40) 247 07 # unsigned integer(value:7,"title") 248 6c # text string(12 bytes) 249 53656e736f7220496e646578 # "Sensor Index" 250 a3 # map(number of pairs of data items:3) 251 01 # unsigned integer(value:1,"href") 252 6d # text string(13 bytes) 253 2f73656e736f72732f74656d70 # "/sensors/temp" 254 09 # unsigned integer(value:9,"rt") 255 6d # text string(13 bytes) 256 74656d70657261747572652d63 # "temperature-c" 257 0a # unsigned integer(value:10,"if") 258 66 # text string(6 bytes) 259 73656e736f72 # "sensor" 260 a3 # map(number of pairs of data items:3) 261 01 # unsigned integer(value:1,"href") 262 6e # text string(14 bytes) 263 2f73656e736f72732f6c69676874 # "/sensors/light" 264 09 # unsigned integer(value:9,"rt") 265 69 # text string(9 bytes) 266 6c696768742d6c7578 # "light-lux" 267 0a # unsigned integer(value:10,"if") 268 66 # text string(6 bytes) 269 73656e736f72 # "sensor" 270 a3 # map(number of pairs of data items:3) 271 01 # unsigned integer(value:1,"href") 272 78 23 # text string(35 bytes) 273 687474703a2f2f7777772e6578616d706c652e636f6d2f73656e736f72732f74313233 274 # "http://www.example.com/sensors/t123" 275 03 # unsigned integer(value:3,"anchor") 276 6d # text string(13 bytes) 277 2f73656e736f72732f74656d70 # "/sensors/temp" 278 02 # unsigned integer(value:2,"rel") 279 6b # text string(11 bytes) 280 6465736372696265646279 # "describedby" 281 a3 # map(number of pairs of data items:3) 282 01 # unsigned integer(value:1,"href") 283 62 # text string(12 bytes) 284 2f74 # "/t" 285 03 # unsigned integer(value:3,"anchor") 286 6d # text string(13 bytes) 287 2f73656e736f72732f74656d70 # "/sensors/temp" 288 02 # unsigned integer(value:2,"rel") 289 69 # text string(9 bytes) 290 616c7465726e617465 # "alternate" 292 Figure 4: Web Links Encoded in CBOR 294 2.4.2. Link Format in JSON to CBOR Example 296 This examples shows conversion from link format JSON to CBOR format. 298 [{"href":"/sensors","ct":"40","title":"Sensor Index"},{"href 299 ":"/sensors/temp","rt":"temperature-c","if":"sensor"},{"href 300 ":"/sensors/light","rt":"light- 301 lux","if":"sensor"},{"href":"http://www.example.com/sensors/ 302 t123","anchor":"/sensors/ 303 temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/ 304 temp","rel":"alternate"}] 306 Figure 5: Example from section 2.1 of [draft-ietf-core-links-json] 308 becomes 310 85 # array(number of data items:5) 311 a3 # map(number of pairs of data items:3) 312 01 # unsigned integer(value:1, "href") 313 68 # text string(8 bytes) 314 2f73656e736f7273 # "/sensors" 315 0c # unsigned integer(value:12,"ct") 316 18 28 # unsigned integer(value:40) 317 07 # unsigned integer(value:7,"title") 318 6c # text string(12 bytes) 319 53656e736f7220496e646578 # "Sensor Index" 320 a3 # map(number of pairs of data items:3) 321 01 # unsigned integer(value:1,"href") 322 6d # text string(13 bytes) 323 2f73656e736f72732f74656d70 # "/sensors/temp" 324 09 # unsigned integer(value:9,"rt") 325 6d # text string(13 bytes) 326 74656d70657261747572652d63 # "temperature-c" 327 0a # unsigned integer(value:10,"if") 328 66 # text string(6 bytes) 329 73656e736f72 # "sensor" 330 a3 # map(number of pairs of data items:3) 331 01 # unsigned integer(value:1,"href") 332 6e # text string(14 bytes) 333 2f73656e736f72732f6c69676874 # "/sensors/light" 334 09 # unsigned integer(value:9,"rt") 335 69 # text string(9 bytes) 336 6c696768742d6c7578 # "light-lux" 337 0a # unsigned integer(value:10,"if") 338 66 # text string(6 bytes) 339 73656e736f72 # "sensor" 340 a3 # map(number of pairs of data items:3) 341 01 # unsigned integer(value:1,"href") 342 78 23 # text string(35 bytes) 343 687474703a2f2f7777772e6578616d706c652e636f6d2f73656e736f72732f74313233 344 # "http://www.example.com/sensors/t123" 345 03 # unsigned integer(value:3,"anchor") 346 6d # text string(13 bytes) 347 2f73656e736f72732f74656d70 # "/sensors/temp" 348 02 # unsigned integer(value:2,"rel") 349 6b # text string(11 bytes) 350 6465736372696265646279 # "describedby" 351 a3 # map(number of pairs of data items:3) 352 01 # unsigned integer(value:1,"href") 353 62 # text string(12 bytes) 354 2f74 # "/t" 355 03 # unsigned integer(value:3,"anchor") 356 6d # text string(13 bytes) 357 2f73656e736f72732f74656d70 # "/sensors/temp" 358 02 # unsigned integer(value:2,"rel") 359 69 # text string(9 bytes) 360 616c7465726e617465 # "alternate" 362 Figure 6: Web Links Encoded in CBOR 364 3. Group Communication Management Objects in CBOR 366 3.1. Background 368 The CoAP Group Communications (RFC7390) defines management objects in 369 JSON format. These objects are used to represent IP multicast group 370 information for CoAP endpoints. 372 3.2. Information Model 374 This section discusses the information model underlying the CoAP 375 Group Communication management object payload. 377 A group membership JSON object contains one or more key/value pairs, 378 and represents a single IP multicast group membership for the CoAP 379 endpoint. Each key/value pair is encoded as a member of the JSON 380 object, where the key is the member name and the value is the 381 member's value. 383 The information model of the CoAP Group Communication management 384 object can be summarized below: 386 +------------------+--------------------+ 387 | name | value | 388 +------------------+--------------------+ 389 | n | group name | 390 +------------------+--------------------+ 391 | a | IP multicast | 392 | | address | 393 +------------------+--------------------+ 395 Figure 7: CoAP Group Communication Information Model 397 3.3. Mapping 399 The objective of the mapping defined in this section is to map 400 information from the JSON formats specified in [RFC7390] into CBOR 401 format. 403 3.4. Group Communication Example 404 { "8" :{ "a": "[ff15::4200:f7fe:ed37:14ca]" }, 405 "11":{ "n": "sensors.floor1.west.bldg6.example.com", 406 "a": "[ff15::4200:f7fe:ed37:25cb]" }, 407 "12":{ "n": "All-Devices.floor1.west.bldg6.example.com", 408 "a": "[ff15::4200:f7fe:ed37:abcd]:4567" } 409 } 411 Figure 8: Example from section 2.6.2.4 of [RFC7390] 413 becomes 415 a3 # map(3) 416 61 # text(1) 417 38 # "8" 418 a1 # map(1) 419 61 # text(1) 420 61 # "a" 421 78 1b # text(27) 422 5b666631353a3a343230303a663766653a656433373a313463615d # "[ff15::4200:f7fe:ed37:14ca]" 423 62 # text(2) 424 3131 # "11" 425 a2 # map(2) 426 61 # text(1) 427 6e # "n" 428 78 25 # text(37) 429 73656e736f72732e666c6f6f72312e776573742e626c6467362e6578616d706c652e636f6d # "sensors.floor1.west.bldg6.example.com" 430 61 # text(1) 431 61 # "a" 432 78 1b # text(27) 433 5b666631353a3a343230303a663766653a656433373a323563625d # "[ff15::4200:f7fe:ed37:25cb]" 434 62 # text(2) 435 3132 # "12" 436 a2 # map(2) 437 61 # text(1) 438 6e # "n" 439 78 29 # text(41) 440 416c6c2d446576696365732e666c6f6f72312e776573742e626c6467362e6578616d706c652e636f6d # "All-Devices.floor1.west.bldg6.example.com" 441 61 # text(1) 442 61 # "a" 443 78 20 # text(32) 444 5b666631353a3a343230303a663766653a656433373a616263645d3a34353637 # "[ff15::4200:f7fe:ed37:abcd]:4567" 446 Figure 9: Group Communication Management Object Encoded in CBOR 448 4. IANA Considerations 450 This specification registers the following additional Internet Media 451 Types: 453 Type name: application 455 Subtype name: link-format+cbor 457 Required parameters: None 459 Optional parameters: None 461 Encoding considerations: Resources that use the "application/ link- 462 format+cbor" media type are required to conform to the "application/ 463 cbor" Media Type and are therefore subject to the same encoding 464 considerations specified in [RFC7159], Section 6. 466 Security considerations: As defined in this specification 468 Published specification: This specification. 470 Applications that use this media type: None currently known. 472 Additional information: 474 --Magic number(s): N/A 476 --File extension(s): N/A 478 --Macintosh file type code(s): TEXT 480 Person & email address to contact for further information: Kepeng Li 481 483 Intended usage: COMMON 485 Change controller: IESG 487 5. Security Considerations 489 The security considerations of [RFC6690] and [RFC7049] apply. 491 6. Acknowledgements 493 Special thanks to Bert Greevenbosch who was an author on the initial 494 version of this document. 496 Thanks to Carsten Bormann for helpful comments and discussions that 497 have shaped the document. 499 7. References 501 7.1. Normative References 503 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 504 Requirement Levels", BCP 14, RFC 2119, March 1997. 506 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 508 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 509 Format", RFC 6690, August 2012. 511 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 512 Representation (CBOR)", RFC 7049, October 2013. 514 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 515 Interchange Format", RFC 7159, March 2014. 517 [RFC7390] Rahman, A. and E. Dijk, "Group Communication for the 518 Constrained Application Protocol (CoAP)", RFC 7390, 519 October 2014. 521 7.2. Informative References 523 [I-D.ietf-core-links-json] 524 Bormann, C., "Representing CoRE Link Collections in JSON", 525 draft-ietf-core-links-json-02 (work in progress), July 526 2014. 528 Authors' Addresses 530 Kepeng LI 531 Alibaba Group 532 Wenyixi Road, Yuhang District 533 Hangzhou, Zhejiang 311121 534 China 536 Email: kepeng.lkp@alibaba-inc.com 537 Ruinan Sun 538 Huawei Technologies 539 Huawei Base, Bantian, Longgang District 540 Shenzhen, Guangdong 518129 541 P. R. China 543 Phone: +86-755-28970171 544 Email: sunruinan@huawei.com 546 Akbar Rahman 547 InterDigital Communications, LLC 548 1000 Sherbrooke Street West 549 Montreal, Quebec H3A 3G4 550 Canada 552 Phone: +1-514-585-0761 553 Email: akbar.rahman@interdigital.com