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 09, 2014.

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 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. Requirements
• 3. JSON Meta Object
• 3.1. _links Member
• 3.1.1. href
• 3.1.2. content-type
• 3.1.3. title
• 3.1.4. method
• 3.1.5. Authorize
• 3.1.6. params
• 4. IANA Considerations
• 5. Security Considerations
• 5.1. href tampering
• 6. Acknowledgements
• 7. References
• 7.1. Normative References
• 7.2. Informational References
• Author's Address

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:

• JSON Hyper Schema [JSON_Hyper_Schema] as a part of JSON Schema.
• JSON Hypermedia API Language [HAL]
• Home Documents for HTTP APIs [JSON_Home]

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"},
          "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 [RFC5988] 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.

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

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

7.2. Informational References

Author's Address