CoRE Working Group C. Bormann Internet-Draft Universitaet Bremen TZI Intended status: Standards Track February 14, 2012 Expires: August 17, 2012 Representing CoRE Link Collections in JSON draft-bormann-core-links-json-00 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 (I-D.ietf-core-link-format). Outside of constrained environments, it may be useful to represent these collections of Web links in JSON format (RFC4627). 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 August 17, 2012. Copyright Notice Copyright (c) 2012 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 August 17, 2012 [Page 1] Internet-Draft Links-in-JSON February 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Web Links in JSON . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Normative References . . . . . . . . . . . . . . . . . . . 10 6.2. Informative References . . . . . . . . . . . . . . . . . . 10 Appendix A. Implementation . . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 Bormann Expires August 17, 2012 [Page 2] Internet-Draft Links-in-JSON February 2012 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 [I-D.ietf-core-link-format] to enable resource discovery. Outside of constrained environments, it may also be useful to represent the same collections of Web links in the widely used JSON format [RFC4627]. 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. 1.1. Objectives (TBD: Convert the shopping list into plaintext) o Canonical mapping * lossless round-tripping * 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 RFC 2119, BCP 14 Bormann Expires August 17, 2012 [Page 3] Internet-Draft Links-in-JSON February 2012 [RFC2119]. Bormann Expires August 17, 2012 [Page 4] Internet-Draft Links-in-JSON February 2012 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 [I-D.ietf-core-link-format]. 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 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 [I-D.ietf-core-link-format] and its referenced documents, before placing them in JSON strings (where they may gain back additional decorations such as backslashes as defined in [RFC4627]). 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. The URI-Reference is represented as a name/value pair with the name "uri" and the URI-Reference as the value. (Rationale: While this does preempt "uri" as an attribute name, this usage is consistent with the use of "uri" in link-format query filtering [I-D.ietf-core-link-format]). (TBD: Should be do something special with the "hosts" relation? Should we include an anchor where the link-format does not explicitly set one?) Bormann Expires August 17, 2012 [Page 5] Internet-Draft Links-in-JSON February 2012 2.1. Examples ;rt="index";title="Sensor Index", ;rt="TemperatureC";if="sensor", ;rt="LightLux";if="sensor", ;anchor="/sensors/temp" ;rel="describedby", ;anchor="/sensors/temp";rel="alternate" Figure 1: Example from page 13 of [I-D.ietf-core-link-format] becomes " [{"uri":"/sensors","rt":"index","title":"Sensor Index"},{"uri":"/se nsors/temp","rt":"TemperatureC","if":"sensor"},{"uri":"/sensors/light ","rt":"LightLux","if":"sensor"},{"uri":"http://www.example.com/senso rs/t123","anchor":"/sensors/temp","rel":"describedby"},{"uri":"/t","a nchor":"/sensors/temp","rel":"alternate"}] " (More examples to be added.) Bormann Expires August 17, 2012 [Page 6] Internet-Draft Links-in-JSON February 2012 3. IANA Considerations (TBD. All the Media Type boilerplate, too, for:) application/link-format+json Bormann Expires August 17, 2012 [Page 7] Internet-Draft Links-in-JSON February 2012 4. Security Considerations (TBD.) Bormann Expires August 17, 2012 [Page 8] Internet-Draft Links-in-JSON February 2012 5. Acknowledgements (TBD.) Bormann Expires August 17, 2012 [Page 9] Internet-Draft Links-in-JSON February 2012 6. References 6.1. Normative References [I-D.ietf-core-link-format] Shelby, Z., "CoRE Link Format", draft-ietf-core-link-format-11 (work in progress), January 2012. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 6.2. Informative References [I-D.ietf-core-coap] Shelby, Z., Hartke, K., Bormann, C., and B. Frank, "Constrained Application Protocol (CoAP)", draft-ietf-core-coap-08 (work in progress), October 2011. [I-D.pbryan-zyp-json-ref] Bryan, P. and K. Zyp, "JSON Reference", draft-pbryan-zyp-json-ref-01 (work in progress), November 2011. [MNOT11] Nottingham, M., "Linking in JSON", November 2011, . [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text", RFC 2047, November 1996. Bormann Expires August 17, 2012 [Page 10] Internet-Draft Links-in-JSON February 2012 Appendix A. Implementation This appendix provides a simple reference implementation of the mapping between CoRE link format and Links-in-JSON. (TBD.) Bormann Expires August 17, 2012 [Page 11] Internet-Draft Links-in-JSON February 2012 Author's Address Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63921 Fax: +49-421-218-7000 Email: cabo@tzi.org Bormann Expires August 17, 2012 [Page 12]