One document matched: draft-sakimura-json-meta-00.txt
INTERNET-DRAFT Nat Sakimura
Intended Status: Informational Nomura Research Institute
Expires: June 4, 2013 December 1, 2012
JSON Meta Object
draft-sakimura-json-meta-00
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 to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/1id-abstracts.html
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
Copyright and License 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
Nat Sakimura Expires June 4, 2013 [Page 1]
INTERNET DRAFT JSON Meta Object December 1, 2012
(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 . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3
3 JSON Meta Object . . . . . . . . . . . . . . . . . . . . . . . 4
3.1 _links Property . . . . . . . . . . . . . . . . . . . . . . 4
3.1.1 href . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.2 method . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.3 Authorize . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.4 params . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.5 content-type . . . . . . . . . . . . . . . . . . . . . . 5
4 Security Considerations . . . . . . . . . . . . . . . . . . . . 5
4.1 href tampering . . . . . . . . . . . . . . . . . . . . . . . 5
5 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
6 References . . . . . . . . . . . . . . . . . . . . . . . . . . 6
6.1 Normative References . . . . . . . . . . . . . . . . . . . 6
6.2 Informative References . . . . . . . . . . . . . . . . . . 6
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 6
Nat Sakimura Expires June 4, 2013 [Page 2]
INTERNET DRAFT JSON Meta Object December 1, 2012
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 has been several efforts to bring such hyperlink capability to
JSON. To name a few, there has been such efforts like:
* JSON Hyper Schema as a part of JSON Schema.
(http://tools.ietf.org/html/draft-zyp-json-schema-03#section-6)
* JSON Hypermedia API Language (http://tools.ietf.org/html/draft-
kelly-json-hal-03)
* Home Documents for HTTP APIs (http://tools.ietf.org/html/draft-
nottingham-json-home-02)
Of those, JSON Hyper Schema seems to most closely match the needs for
"insertable JSON Stub" into currently existing JSON responses.
However, at the same time, 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.
Another disadvantage of JSON Hyper Schema is the document structure.
In particular, the fact that it is embedded inside a much larger
JSON Schema specification means that it comes with a lot of baggage
that many developers would not need for the purpose of just adding
metadata to existing JSON responses.
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.
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].
Nat Sakimura Expires June 4, 2013 [Page 3]
INTERNET DRAFT JSON Meta Object December 1, 2012
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" property.
The value of the "_links" property is a JSON object that expresses
link relationships (rel), which in turn holds an array of object with
"href" and other properties.
Following non-normative schematic example should help envisage what
it would look like the following. (Note: line-wraps are for display
purpose only.)
{
"_links":{
"self":[
{"href":"https://example.com/token?code=123"}
],
"http://openid.net/specs/
openid-connect-messages-1_0.html#userinfo_ep":[
{
"href":"https://example.com/user/{user_id}",
"method":"GET",
"Authorize":"{token_type} {access_token}"
},
{
"href":"https://example.com/user/{user_id}",
"method":"POST",
"Authorize":"{token_type} {access_token}",
"params":[
"name","birthday"
]
}
},
"token_type":"Bearer",
"access_token":"aCessToKen"
}
Here, we have "_links" property that expresses various "relations"
such as "self" and "http://openid.net/specs/openid-connect-messages-
1_0.html#userinfo_ep". Each relationships has an array as its value,
and the array holds multiple objects that holds various properties
such as "href". They are explained in the next section.
3.1 _links Property
_links property holds exactly one object the holds the following
Nat Sakimura Expires June 4, 2013 [Page 4]
INTERNET DRAFT JSON Meta Object December 1, 2012
properties with relation as the key. The key SHOULD be link relation
types that are defined in the IANA registry defined in [RFC5988] or a
URL that describes the relation.
Each relation property holds exactly one array, whose items are
objects. Each object has following properties, which are all
optional.
3.1.1 href
URI Template [RFC6570] that the relation points to. The values for
template parameters SHOULD be taken from the matching top-level
properties in the including JSON object.
3.1.2 method
The HTTP method defined in [RFC2616] that can be used to the URL
described in the href. e.g., GET, POST, PUT, DELETE.
3.1.3 Authorize
The HTTP Authorize header defined in [RFC2616] to be used when
accessing the resource identified by href. It is templated in a
similar manner as in URI template. This will be explained further
later.
3.1.4 params
The parameters to be sent to the URL expressed in "href". The value
is an array of strings that corresponds to the parameter names of the
parameters that are to be sent to the URL.
3.1.5 content-type
The content-type to be used when the parameters are sent to the URL.
e.g., "application/x-www-form-urlencoded", "multipart/form-data",
"application/json".
4 Security Considerations
4.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
Nat Sakimura Expires June 4, 2013 [Page 5]
INTERNET DRAFT JSON Meta Object December 1, 2012
parameters.
To mitigate this risk, an integrity protected channel such as TLS
protected channel should be used.
5 IANA Considerations
This document makes no request to IANA.
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.
[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.
6.2 Informative References
[RFC5513] Farrel, A., "IANA Considerations for Three Letter
Acronyms", RFC 5513, April 1 2009.
[OIDC1.0] Sakimura, N., Bradley, J., Jones, M., de Madeiros, B.,
Mortimore, C., Jay, E., "OpenID Connect Messages 1.0"
Authors' Addresses
Nat Sakimura
Nomura Research Institute
EMail: n-sakimura@nri.co.jp
Nat Sakimura Expires June 4, 2013 [Page 6]
| PAFTECH AB 2003-2026 | 2026-04-23 14:46:29 |