[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-li-core-cbor-equivalents) 00 01 02 03 04 05 06 07 08 09

CoRE Working Group                                            C. Bormann
Internet-Draft                                   Universitaet Bremen TZI
Intended status: Standards Track                           July 04, 2014
Expires: January 5, 2015


               Representing CoRE Link Collections in JSON
                     draft-ietf-core-links-json-02

Abstract

   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).  Outside of
   constrained environments, it may be useful to represent these
   collections of Web links in JSON format (RFC7159).

   This specification defines a common format for representing Web links
   in JSON format.

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 January 5, 2015.

Copyright Notice

   Copyright (c) 2014 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   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



Bormann                  Expires January 5, 2015                [Page 1]


Internet-Draft                Links-in-JSON                    July 2014


   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  . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Web Links in JSON . . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   5.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   6
   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
     6.1.  Normative References  . . . . . . . . . . . . . . . . . .   6
     6.2.  Informative References  . . . . . . . . . . . . . . . . .   6
   Appendix A.  Implementation . . . . . . . . . . . . . . . . . . .   6
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7

1.  Introduction

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

   Outside of constrained environments, it may also be useful to
   represent the same collections of Web links in the widely used JSON
   format [RFC7159].  When converting between these two formats, as
   usual, there are many little decisions that 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 format for representing CoRE Web
   Linking in JSON format.

   Note that there is a separate question on how to represent Web links
   out of JSON documents, as discussed e.g. in [MNOT11].  While there
   are good reasons to stay as compatible as possible to developments in
   this area, the present specification is solving a different problem.








Bormann                  Expires January 5, 2015                [Page 2]


Internet-Draft                Links-in-JSON                    July 2014


1.1.  Objectives

   This specification has been designed based on the following
   objectives:

   o  Canonical mapping

      *  lossless round-tripping with [RFC6690]

      *  but not trying for bit-preserving (DER-style) round-tripping

   o  The simplest thing that could possibly work

      *  Do not cater for RFC 5988 complications caused by HTTP header
         character set issues [RFC2047]

   o  Consider other work that has links in JSON, e.g.: JSON-LD, JSON-
      Reference [I-D.pbryan-zyp-json-ref]

      *  Do not introduce unmotivated differences

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] when they
   appear in ALL CAPS.  These words may also appear in this document in
   lower case as plain English words, absent their normative meanings.

2.  Web Links in JSON

   The objective of the JSON mapping defined in this document is to
   contain information of the formats specified in [RFC5988] and
   [RFC6690].  This specification therefore uses the names of the ABNF
   productions used in those documents.

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

   We straightforwardly map:

   o  the outer collection to an array of links

   o  each link to a JSON object.

   In the object representing a "link-value", each target attribute or
   other parameter ("link-param") is represented by a JSON name/value



Bormann                  Expires January 5, 2015                [Page 3]


Internet-Draft                Links-in-JSON                    July 2014


   pair (member).  The name is a string representation of the parameter
   or attribute name (as in "parmname"), the value is a string
   representation of the parameter or attribute value ("ptoken" or
   "quoted-string").  "quoted-string" productions are parsed (i.e, the
   backslash constructions evaluated) as defined in [RFC6690] and its
   referenced documents, before placing them in JSON strings (where they
   may gain back additional decorations such as backslashes as defined
   in [RFC7159]).

   If a Link attribute ("parmname") is present more than once in a
   "link-value", its values are then represented as a JSON array of JSON
   string values; this array becomes the value of the JSON name/value
   pair where the attribute name is the JSON name.  Attributes occurring
   just once MUST NOT be represented as JSON arrays but MUST be directly
   represented as JSON strings.  (Note that the most recent version of
   link-format has cut down on the use of repeated parameter names; they
   are still allowed by [RFC5988] though.  No attempt has been made to
   decode the possibly space-separated values for rt=, if=, and rel=
   into JSON arrays.)

   The URI-Reference is represented as a name/value pair with the name
   "href" and the URI-Reference as the value.  (Rationale: This usage is
   consistent with the use of "href" as a query parameter for link-
   format query filtering and with link-format reserving the link
   parameter "href" specifically for this use [RFC6690]).

   (TBD: Should we do something special with the "hosts" relation?
   Should we include an anchor where the link-format does not explicitly
   set one?)

2.1.  Examples

   </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 1: Example from page 15 of [RFC6690]

   becomes

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



Bormann                  Expires January 5, 2015                [Page 4]


Internet-Draft                Links-in-JSON                    July 2014


   temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/
   temp","rel":"alternate"}] "

   (More examples to be added.)

3.  IANA Considerations

   This specification registers the following additional Internet Media
   Types:

     Type name: application

     Subtype name: link-format+json

     Required parameters: None

     Optional parameters: None

     Encoding considerations: Resources that use the "application/
     link-format+json" media type are required to conform to the
     "application/json" Media Type and are therefore subject to the
     same encoding considerations specified in Section 6 {{RFC7159}}.

     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:
     Carsten Bormann <cabo@tzi.org>

     Intended usage: COMMON

     Change controller: IESG








Bormann                  Expires January 5, 2015                [Page 5]


Internet-Draft                Links-in-JSON                    July 2014


4.  Security Considerations

   The security considerations of [RFC6690] apply.

   (TBD.)

5.  Acknowledgements

   (TBD.)

6.  References

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

   [RFC7159]  Bray, T., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, March 2014.

6.2.  Informative References

   [I-D.pbryan-zyp-json-ref]
              Bryan, P. and K. Zyp, "JSON Reference", draft-pbryan-zyp-
              json-ref-03 (work in progress), September 2012.

   [MNOT11]   Nottingham, M., "Linking in JSON", November 2011,
              <http://www.mnot.net/blog/2011/11/25/linking_in_json>.

   [RFC2047]  Moore, K., "MIME (Multipurpose Internet Mail Extensions)
              Part Three: Message Header Extensions for Non-ASCII Text",
              RFC 2047, November 1996.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252, June 2014.

Appendix A.  Implementation

   This appendix provides a simple reference implementation of the
   mapping between CoRE link format and Links-in-JSON.






Bormann                  Expires January 5, 2015                [Page 6]


Internet-Draft                Links-in-JSON                    July 2014


   (TBD - the reference implementation was used to create the above
   examples, but I still have to clean it up for readability and paste
   it in at 69 columns max.)

Author's Address

   Carsten Bormann
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63921
   Email: cabo@tzi.org





































Bormann                  Expires January 5, 2015                [Page 7]


Html markup produced by rfcmarkup 1.122, available from https://tools.ietf.org/tools/rfcmarkup/