Internet DRAFT - draft-bormann-core-links-json
draft-bormann-core-links-json
CoRE Working Group C. Bormann
Internet-Draft Universitaet Bremen TZI
Intended status: Standards Track February 25, 2013
Expires: August 29, 2013
Representing CoRE Link Collections in JSON
draft-bormann-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 (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 29, 2013.
Copyright Notice
Copyright (c) 2013 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 29, 2013 [Page 1]
Internet-Draft Links-in-JSON February 2013
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 JSON . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
4. Security Considerations . . . . . . . . . . . . . . . . . . . 5
5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 5
6.1. Normative References . . . . . . . . . . . . . . . . . . 5
6.2. Informative References . . . . . . . . . . . . . . . . . 5
Appendix A. Implementation . . . . . . . . . . . . . . . . . . . 6
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
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.
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)
Bormann Expires August 29, 2013 [Page 2]
Internet-Draft Links-in-JSON February 2013
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 [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
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
Bormann Expires August 29, 2013 [Page 3]
Internet-Draft Links-in-JSON February 2013
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. (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/
temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/
temp","rel":"alternate"}] "
(More examples to be added.)
Bormann Expires August 29, 2013 [Page 4]
Internet-Draft Links-in-JSON February 2013
3. IANA Considerations
(TBD. All the Media Type boilerplate, too, for:)
application/link-format+json
4. Security Considerations
(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.
[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.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012.
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-13 (work in progress), December 2012.
[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.
Bormann Expires August 29, 2013 [Page 5]
Internet-Draft Links-in-JSON February 2013
Appendix A. Implementation
This appendix provides a simple reference implementation of the
mapping between CoRE link format and Links-in-JSON.
(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 August 29, 2013 [Page 6]
