Internet DRAFT - draft-sakimura-json-meta
draft-sakimura-json-meta
Json Working Group N. Sakimura, Ed.
Internet-Draft Nomura Research Institute
Intended status: Informational November 06, 2013
Expires: May 10, 2014
JSON Metadata
draft-sakimura-json-meta-01
Abstract
Although JSON has become a popular choice of the web services
response that tries to be REST like, the lack of its capability to
express the hyperlink and other metadata in a standardized manner has
been felt. This document proposes a method to minimally represent
such metadata that can be inserted into the existing JSON responses
to express such metadata.
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 May 10, 2014.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
Sakimura Expires May 10, 2014 [Page 1]
Internet-Draft JSON Meta November 2013
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
2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3
3. JSON Meta Object . . . . . . . . . . . . . . . . . . . . . . 3
3.1. _links Member . . . . . . . . . . . . . . . . . . . . . . 4
3.1.1. href . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1.2. content-type . . . . . . . . . . . . . . . . . . . . 4
3.1.3. title . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.4. method . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.5. Authorize . . . . . . . . . . . . . . . . . . . . . . 5
3.1.6. params . . . . . . . . . . . . . . . . . . . . . . . 5
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
5. Security Considerations . . . . . . . . . . . . . . . . . . . 5
5.1. href tampering . . . . . . . . . . . . . . . . . . . . . 6
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
7.1. Normative References . . . . . . . . . . . . . . . . . . 6
7.2. Informational References . . . . . . . . . . . . . . . . 6
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7
1. Introduction
JSON has become one of the most popular format of the choice of the
"REST like" web services. However, the lack of the standardized way
of expressing hyperlinks and other metadata about the response has
remained a issue for a long time.
There have been several efforts to bring such hyperlink capability to
JSON. To name a few, there has been such efforts like:
o JSON Hyper Schema [JSON_Hyper_Schema] as a part of JSON Schema.
o JSON Hypermedia API Language [HAL]
o Home Documents for HTTP APIs [JSON_Home]
Sakimura Expires May 10, 2014 [Page 2]
Internet-Draft JSON Meta November 2013
The later two shares a very similar design principle of expressing
link relations (commonly referred to as "rel") as the keys in JSON
rather than values like in the case of JSON Hyper Schema. It has a
distinctive advantage of being able to use the indexing capability of
JSON instead of going through the loop to find the right
relationship. On the other hand, the combination of JSON Hyper
Schema and JSON Schema has much richer set of functionality.
In addition, both WebFinger [RFC7033] and SCIM have defined similar
mechanism for the use of themselves only.
Exisitence of these overlapping specifications indicates that the
community probably would benefit from a standard way of expressing
such link relationships.
Under this kind of situation, this document attempts to produce a
minimum set of JSON stub to achieve a metadata that can express the
hyperlinks and other relations.
EDITOR's NOTE: This document is inteded to start discussions on the
topic.
2. Requirements
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 [RFC2119].
3. JSON Meta Object
A JSON Meta Object uses the format described in [RFC4627] and is
intended to be inserted into a JSON document to express some of the
metadata associated with it as "_links" member.
NOTE: "_links" was chosen because it probably would have less
collision with the existing names since it starts with an underscore
(_).
The value of the "_links" member is a JSON object that expresses link
relations ("rel"), which in turn holds an object with "href" and
other members or an array of such objects.
Following non-normative schematic example should help envisage what
it would look like. (Note: line-wraps are for display purpose only.)
{
"_links":{
"self":{"href":"https://example.com/token?code=123"},
Sakimura Expires May 10, 2014 [Page 3]
Internet-Draft JSON Meta November 2013
"related":[
{"href":"https://example.com/p1"},
{"href":"https://example.com/p2"}
],
"http://example.com/userinfo":
{
"href":"https://example.com/user/{user_id}",
"Authorize":"{token_type} {access_token}"
}
},
"token_type":"Bearer",
"access_token":"aCeSsToKen",
"user_id":"a1234"
}
Here, we have "_links" member that expresses various "relations" such
as "self" and "userinfo", which is a resource type of OpenID
Connect's Userinfo endpoint. Each relationships has either a link
relations object or an array of link relations objects as its value.
The link relations objects holds various members such as "href".
They are explained in the next section.
3.1. _links Member
"_links" member holds exactly one object that contains the following
members with relation as the "string" defined in [RFC4627]. The
"string" SHOULD be a link relation type that is either defined in the
IANA registry defined in Web Linking (Web Linking) or a URI that
describes the relation.
Each relation member holds exactly one object or one array, whose
elements are objects. Each object has following members, which are
all optional.
3.1.1. href
The value of the "href" member is a URI Template [RFC6570] that the
relation points to. The values for template parameters SHOULD be
taken from the value of the top-level members in the including JSON
object whose "string" matches the template variable name.
3.1.2. content-type
The content-type to be used when the parameters are sent to the URL.
[todo] Locate the proper reference and name for content transfer
encodings.
Sakimura Expires May 10, 2014 [Page 4]
Internet-Draft JSON Meta November 2013
e.g., "application/x-www-form-urlencoded", "multipart/form-data",
"application/json".
3.1.3. title
The label the destination of a link such that it can be used as a
human-readable identifier (e.g., a menu entry) in the language
indicated by the Content- Language header (if present). The "title"
parameter MUST NOT appear more than once in a given link-value;
occurrences after the first MUST be ignored by parsers.
3.1.4. method
The HTTP method defined in [RFC2616] that can be used to the URL
described in the href. e.g., GET, POST, PUT, DELETE.
EDITOR'S NOTE: Maybe we want to drop this section for simplicity.
3.1.5. Authorize
The HTTP Authorize header defined in Hypertext Transfer Protocol --
HTTP/1.1 [RFC2616] to be used when accessing the resource identified
by href. It is templated in exactly the same syntax as in URI
Template [RFC6570] except that it is applied to the Authorization
request header than the URI.
EDITOR'S NOTE: Maybe we want to drop this section for simplicity.
3.1.6. params
The parameters to be sent to the URL expressed in "href". The value
is an array of pairs whose string corresponds to the parameter names
of the parameters that are to be sent to the URL. The value of the
pair is an object with following members. All parameters are
optional.
required Boolean. true or false.
description Human readable description of the variable.
EDITOR'S NOTE: Maybe we want to drop this section for simplicity.
4. IANA Considerations
This document makes no request to IANA.
5. Security Considerations
Sakimura Expires May 10, 2014 [Page 5]
Internet-Draft JSON Meta November 2013
5.1. href tampering
Unless integrity protected channel is used, an attacker may be able
to tamper the value of the href thereby causing the receiver of the
JSON response to send a request to the URL under the attacker's
control with potentially confidential information contained in the
parameters. To mitigate this risk, an integrity protected channel
such as TLS protected channel should be used.
6. Acknowledgements
This specification borrows heavily from [HAL].
[todo]
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.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[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.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012.
7.2. Informational References
[HAL] Kelly, M., "JSON Hypermedia API Language", February 2013,
<http://tools.ietf.org/html/draft- kelly-json-hal-03>.
[JSON_Home]
Nottingham, M., "Home Documents for HTTP APIs", May 2013,
<http://tools.ietf.org/html/draft-nottingham-json-
home-03>.
[JSON_Hyper_Schema]
Luff, G., Zyp, K., and G. Court, "JSON Hypermedia Schema",
February 2013, <http://json-schema.org/latest/json-schema-
hypermedia.html>.
Sakimura Expires May 10, 2014 [Page 6]
Internet-Draft JSON Meta November 2013
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC
6749, October 2012.
[RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr,
"WebFinger", RFC 7033, September 2013.
Author's Address
Nat Sakimura (editor)
Nomura Research Institute
Email: n-sakimura@nri.co.jp
Sakimura Expires May 10, 2014 [Page 7]
