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]