core K. Li Internet-Draft Alibaba Group Intended status: Standards Track R. Sun Expires: September 10, 2015 Huawei Technologies A. Rahman InterDigital March 9, 2015 CBOR Equivalents of CoRE JSON Formats draft-li-core-cbor-equivalents-00 Abstract JSON (RFC7159) is a text-based data format which is popular for Web based data exchanges. CBOR (RFC7049) is a binary data format which has been optimized for data exchanges for the Internet of Things. For many IoT scenarios, CBOR formats will be preferred since it can decrease transmission payload sizes compared to other data formats. This specification defines an approach for translating JSON objects, which are relevant for the CoRE WG and its related specifications, into CBOR format. Where applicable, mapping from other formats into JSON or CBOR is also described. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on September 10, 2015. Copyright Notice Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. Li, et al. Expires September 10, 2015 [Page 1] Internet-Draft CBOR Equivalents March 2015 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 2 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Web Links in CBOR . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Information Model . . . . . . . . . . . . . . . . . . . . 3 2.3. Encoding Step . . . . . . . . . . . . . . . . . . . . . . 4 2.4. Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.4.1. Link Format to CBOR Example . . . . . . . . . . . . . 6 2.4.2. Link Format in JSON to CBOR Example . . . . . . . . . 7 3. Group Communication Management Objects in CBOR . . . . . . . 9 3.1. Background . . . . . . . . . . . . . . . . . . . . . . . 9 3.2. Information Model . . . . . . . . . . . . . . . . . . . . 9 3.3. Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.4. Group Communication Example . . . . . . . . . . . . . . . 9 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 7.1. Normative References . . . . . . . . . . . . . . . . . . 12 7.2. Informative References . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 1. Introduction 1.1. Objectives The JavaScript Object Notation (JSON) [RFC7159] is a lightweight, text-based, language-independent data interchange format. JSON is popular in the Web development environment as it is particularly easy for humans to read and write. The Concise Binary Object Representation (CBOR) [RFC7049] is a binary data format which requires extremely small code size, allows very compact message representation, and provides extensibility without Li, et al. Expires September 10, 2015 [Page 2] Internet-Draft CBOR Equivalents March 2015 the need for version negotiation. CBOR is especially well suited for IoT environments because of its efficiency. When converting between JSON and CBOR, as usual, many small decisions have to be made. If left without guidance, it is likely that a number of slightly incompatible dialects will emerge. This specification defines a common approach for translating JSON objects into CBOR format which are relevant for the CoRE WG and its related specifications. Where applicable, mapping from other formats (e.g. CoRE Link Format) into JSON or CBOR is also described. 1.2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. CoAP: Constrained Application Protocol CBOR: Concise Binary Object Representation CoRE: Constrained RESTful Environments IoT: Internet of Things JSON: JavaScript Object Notation 2. Web Links in CBOR 2.1. Background Web Linking [RFC5988] provides a way to represent links between Web resources as well as the relations expressed by them and attributes of such a link. In constrained networks, a collection of Web links can be exchanged in the CoRE link format [RFC6690] to enable resource discovery, for instance by using the CoAP protocol [RFC7252]. [I-D.ietf-core-links-json] defines a common format for representing Web links in JSON format. 2.2. Information Model This section discusses the information model underlying the CORE Link Format payload. An application/link-format document is a collection of web links ("link-value"), each of which is a collection of attributes ("link- param") applied to a "URI-Reference". Li, et al. Expires September 10, 2015 [Page 3] Internet-Draft CBOR Equivalents March 2015 The URI-Reference is represented as a name/value pair with the name "href" and the URI-Reference as the value. The link attributes are also represented as name/value pairs with attribute names and attribute values. The information model of the CoRE Link Format can be summarized below: +------------------+--------------------+ | name | value | +------------------+--------------------+ | href | resource URI | +------------------+--------------------+ | attribute name 1 | attribute value 1 | +------------------+--------------------+ | attribute name 2 | attribute value 2 | +------------------+--------------------+ | ... | ... | +------------------+--------------------+ | attribute name n | attribute value n | +------------------+--------------------+ Figure 1: CoRE Link Format Information Model 2.3. Encoding Step To reduce message size, it would be beneficial to perform an extra encoding step, and encode "href" and the standardized attribute names specified in [RFC5988] and [RFC6690] as integers. The encoding is summarized below: Li, et al. Expires September 10, 2015 [Page 4] Internet-Draft CBOR Equivalents March 2015 +----------+---------------+ | name | encoded value | +----------+---------------+ | href | 1 | +----------+---------------+ | rel | 2 | +----------+---------------+ | anchor | 3 | +----------+---------------+ | rev | 4 | +----------+---------------+ | hreflang | 5 | +----------+---------------+ | media | 6 | +----------+---------------+ | title | 7 | +----------+---------------+ | type | 8 | +----------+---------------+ | rt | 9 | +----------+---------------+ | if | 10 | +----------+---------------+ | sz | 11 | +----------+---------------+ | ct | 12 | +----------+---------------+ Figure 2: Link Attributes Encoding 2.4. Mapping The objective of the mapping defined in this section is to map information from the JSON formats specified in [RFC6690] into CBOR format. We straightforwardly map: o the outer collection to an array of links (Major type 4) o each link to a map of pairs of data items (Major type 5) In the object representing a "link-value", each target attribute or other parameter ("link-param") is represented by a CBOR pair of data items. The URI-Reference is represented as a name/value pair with the name "href" and the URI-Reference as the value. Li, et al. Expires September 10, 2015 [Page 5] Internet-Draft CBOR Equivalents March 2015 2.4.1. Link Format to CBOR Example This examples shows conversion from link format to CBOR format. ;ct=40;title="Sensor Index", ;rt="temperature-c";if="sensor", ;rt="light-lux";if="sensor", ;anchor="/sensors/temp" ;rel="describedby", ;anchor="/sensors/temp";rel="alternate" Figure 3: Example from page 15 of [RFC6690] becomes 85 # array(number of data items:5) a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1, "href") 68 # text string(8 bytes) 2f73656e736f7273 # "/sensors" 0c # unsigned integer(value:12,"ct") 18 28 # unsigned integer(value:40) 07 # unsigned integer(value:7,"title") 6c # text string(12 bytes) 53656e736f7220496e646578 # "Sensor Index" a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1,"href") 6d # text string(13 bytes) 2f73656e736f72732f74656d70 # "/sensors/temp" 09 # unsigned integer(value:9,"rt") 6d # text string(13 bytes) 74656d70657261747572652d63 # "temperature-c" 0a # unsigned integer(value:10,"if") 66 # text string(6 bytes) 73656e736f72 # "sensor" a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1,"href") 6e # text string(14 bytes) 2f73656e736f72732f6c69676874 # "/sensors/light" 09 # unsigned integer(value:9,"rt") 69 # text string(9 bytes) 6c696768742d6c7578 # "light-lux" 0a # unsigned integer(value:10,"if") 66 # text string(6 bytes) 73656e736f72 # "sensor" a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1,"href") Li, et al. Expires September 10, 2015 [Page 6] Internet-Draft CBOR Equivalents March 2015 78 23 # text string(35 bytes) 687474703a2f2f7777772e6578616d706c652e636f6d2f73656e736f72732f74313233 # "http://www.example.com/sensors/t123" 03 # unsigned integer(value:3,"anchor") 6d # text string(13 bytes) 2f73656e736f72732f74656d70 # "/sensors/temp" 02 # unsigned integer(value:2,"rel") 6b # text string(11 bytes) 6465736372696265646279 # "describedby" a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1,"href") 62 # text string(12 bytes) 2f74 # "/t" 03 # unsigned integer(value:3,"anchor") 6d # text string(13 bytes) 2f73656e736f72732f74656d70 # "/sensors/temp" 02 # unsigned integer(value:2,"rel") 69 # text string(9 bytes) 616c7465726e617465 # "alternate" Figure 4: Web Links Encoded in CBOR 2.4.2. Link Format in JSON to CBOR Example This examples shows conversion from link format JSON to CBOR format. [{"href":"/sensors","ct":"40","title":"Sensor Index"},{"href ":"/sensors/temp","rt":"temperature-c","if":"sensor"},{"href ":"/sensors/light","rt":"light- lux","if":"sensor"},{"href":"http://www.example.com/sensors/ t123","anchor":"/sensors/ temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/ temp","rel":"alternate"}] Figure 5: Example from section 2.1 of [draft-ietf-core-links-json] becomes 85 # array(number of data items:5) a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1, "href") 68 # text string(8 bytes) 2f73656e736f7273 # "/sensors" 0c # unsigned integer(value:12,"ct") 18 28 # unsigned integer(value:40) 07 # unsigned integer(value:7,"title") Li, et al. Expires September 10, 2015 [Page 7] Internet-Draft CBOR Equivalents March 2015 6c # text string(12 bytes) 53656e736f7220496e646578 # "Sensor Index" a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1,"href") 6d # text string(13 bytes) 2f73656e736f72732f74656d70 # "/sensors/temp" 09 # unsigned integer(value:9,"rt") 6d # text string(13 bytes) 74656d70657261747572652d63 # "temperature-c" 0a # unsigned integer(value:10,"if") 66 # text string(6 bytes) 73656e736f72 # "sensor" a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1,"href") 6e # text string(14 bytes) 2f73656e736f72732f6c69676874 # "/sensors/light" 09 # unsigned integer(value:9,"rt") 69 # text string(9 bytes) 6c696768742d6c7578 # "light-lux" 0a # unsigned integer(value:10,"if") 66 # text string(6 bytes) 73656e736f72 # "sensor" a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1,"href") 78 23 # text string(35 bytes) 687474703a2f2f7777772e6578616d706c652e636f6d2f73656e736f72732f74313233 # "http://www.example.com/sensors/t123" 03 # unsigned integer(value:3,"anchor") 6d # text string(13 bytes) 2f73656e736f72732f74656d70 # "/sensors/temp" 02 # unsigned integer(value:2,"rel") 6b # text string(11 bytes) 6465736372696265646279 # "describedby" a3 # map(number of pairs of data items:3) 01 # unsigned integer(value:1,"href") 62 # text string(12 bytes) 2f74 # "/t" 03 # unsigned integer(value:3,"anchor") 6d # text string(13 bytes) 2f73656e736f72732f74656d70 # "/sensors/temp" 02 # unsigned integer(value:2,"rel") 69 # text string(9 bytes) 616c7465726e617465 # "alternate" Figure 6: Web Links Encoded in CBOR Li, et al. Expires September 10, 2015 [Page 8] Internet-Draft CBOR Equivalents March 2015 3. Group Communication Management Objects in CBOR 3.1. Background The CoAP Group Communications (RFC7390) defines management objects in JSON format. These objects are used to represent IP multicast group information for CoAP endpoints. 3.2. Information Model This section discusses the information model underlying the CoAP Group Communication management object payload. A group membership JSON object contains one or more key/value pairs, and represents a single IP multicast group membership for the CoAP endpoint. Each key/value pair is encoded as a member of the JSON object, where the key is the member name and the value is the member's value. The information model of the CoAP Group Communication management object can be summarized below: +------------------+--------------------+ | name | value | +------------------+--------------------+ | n | group name | +------------------+--------------------+ | a | IP multicast | | | address | +------------------+--------------------+ Figure 7: CoAP Group Communication Information Model 3.3. Mapping The objective of the mapping defined in this section is to map information from the JSON formats specified in [RFC7390] into CBOR format. 3.4. Group Communication Example Li, et al. Expires September 10, 2015 [Page 9] Internet-Draft CBOR Equivalents March 2015 { "8" :{ "a": "[ff15::4200:f7fe:ed37:14ca]" }, "11":{ "n": "sensors.floor1.west.bldg6.example.com", "a": "[ff15::4200:f7fe:ed37:25cb]" }, "12":{ "n": "All-Devices.floor1.west.bldg6.example.com", "a": "[ff15::4200:f7fe:ed37:abcd]:4567" } } Figure 8: Example from section 2.6.2.4 of [RFC7390] becomes a3 # map(3) 61 # text(1) 38 # "8" a1 # map(1) 61 # text(1) 61 # "a" 78 1b # text(27) 5b666631353a3a343230303a663766653a656433373a313463615d # "[ff15::4200:f7fe:ed37:14ca]" 62 # text(2) 3131 # "11" a2 # map(2) 61 # text(1) 6e # "n" 78 25 # text(37) 73656e736f72732e666c6f6f72312e776573742e626c6467362e6578616d706c652e636f6d # "sensors.floor1.west.bldg6.example.com" 61 # text(1) 61 # "a" 78 1b # text(27) 5b666631353a3a343230303a663766653a656433373a323563625d # "[ff15::4200:f7fe:ed37:25cb]" 62 # text(2) 3132 # "12" a2 # map(2) 61 # text(1) 6e # "n" 78 29 # text(41) 416c6c2d446576696365732e666c6f6f72312e776573742e626c6467362e6578616d706c652e636f6d # "All-Devices.floor1.west.bldg6.example.com" 61 # text(1) 61 # "a" 78 20 # text(32) 5b666631353a3a343230303a663766653a656433373a616263645d3a34353637 # "[ff15::4200:f7fe:ed37:abcd]:4567" Figure 9: Group Communication Management Object Encoded in CBOR Li, et al. Expires September 10, 2015 [Page 10] Internet-Draft CBOR Equivalents March 2015 4. IANA Considerations This specification registers the following additional Internet Media Types: Type name: application Subtype name: link-format+cbor Required parameters: None Optional parameters: None Encoding considerations: Resources that use the "application/ link- format+cbor" media type are required to conform to the "application/ cbor" Media Type and are therefore subject to the same encoding considerations specified in [RFC7159], Section 6. Security considerations: As defined in this specification Published specification: This specification. Applications that use this media type: None currently known. Additional information: --Magic number(s): N/A --File extension(s): N/A --Macintosh file type code(s): TEXT Person & email address to contact for further information: Kepeng Li Intended usage: COMMON Change controller: IESG 5. Security Considerations The security considerations of [RFC6690] and [RFC7049] apply. 6. Acknowledgements Special thanks to Bert Greevenbosch who was an author on the initial version of this document. Li, et al. Expires September 10, 2015 [Page 11] Internet-Draft CBOR Equivalents March 2015 Thanks to Carsten Bormann for helpful comments and discussions that have shaped the document. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, August 2012. [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, October 2013. [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014. [RFC7390] Rahman, A. and E. Dijk, "Group Communication for the Constrained Application Protocol (CoAP)", RFC 7390, October 2014. 7.2. Informative References [I-D.ietf-core-links-json] Bormann, C., "Representing CoRE Link Collections in JSON", draft-ietf-core-links-json-02 (work in progress), July 2014. Authors' Addresses Kepeng LI Alibaba Group Wenyixi Road, Yuhang District Hangzhou, Zhejiang 311121 China Email: kepeng.lkp@alibaba-inc.com Li, et al. Expires September 10, 2015 [Page 12] Internet-Draft CBOR Equivalents March 2015 Ruinan Sun Huawei Technologies Huawei Base, Bantian, Longgang District Shenzhen, Guangdong 518129 P. R. China Phone: +86-755-28970171 Email: sunruinan@huawei.com Akbar Rahman InterDigital Communications, LLC 1000 Sherbrooke Street West Montreal, Quebec H3A 3G4 Canada Phone: +1-514-585-0761 Email: akbar.rahman@interdigital.com Li, et al. Expires September 10, 2015 [Page 13]