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.

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 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.

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 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].

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".

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.

   +------------------+--------------------+
   | 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:

   +----------+---------------+
   | 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.

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")
      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")
      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

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

 
		 		 
       { "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

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.

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", Internet-Draft draft-ietf-core-links-json-00, June 2013.

Authors' Addresses

Kepeng LI Alibaba Group Wenyixi Road, Yuhang District Hangzhou, Zhejiang 311121 China EMail: kepeng.lkp@alibaba-inc.com

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

Abstract

Status of This Memo

Copyright Notice

Table of Contents

1. Introduction

1.1. Objectives

1.2. Terminology

2. Web Links in CBOR

2.1. Background

2.2. Information Model

2.3. Encoding Step

2.4. Mapping

2.4.1. Link Format to CBOR Example

2.4.2. Link Format in JSON to CBOR Example

3. Group Communication Management Objects in CBOR

3.1. Background

3.2. Information Model

3.3. Mapping

3.4. Group Communication Example

4. IANA Considerations

5. Security Considerations

6. Acknowledgements

7. References

7.1. Normative References

7.2. Informative References

Authors' Addresses