Internet DRAFT - draft-li-core-cbor-equivalents
draft-li-core-cbor-equivalents
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.
</sensors>;ct=40;title="Sensor Index",
</sensors/temp>;rt="temperature-c";if="sensor",
</sensors/light>;rt="light-lux";if="sensor",
<http://www.example.com/sensors/t123>;anchor="/sensors/temp"
;rel="describedby",
</t>;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
<kepeng.lkp@alibaba-inc.com>
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]
