One document matched: draft-sakimura-json-meta-01.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="info" docName="draft-sakimura-json-meta-01" ipr="trust200902">
  <front>
    <title abbrev="JSON Meta">JSON Metadata</title>

    <author fullname="Nat Sakimura" initials="N." role="editor"
            surname="Sakimura">
      <organization>Nomura Research Institute</organization>

      <address>
        <email>n-sakimura@nri.co.jp</email>
      </address>
    </author>

    <date day="3" month="November" year="2013"/>

    <area>Security</area>

    <workgroup>Json Working Group</workgroup>

    <abstract>
      <t>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.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>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.</t>

      <t>There have been several efforts to bring such hyperlink capability to
      JSON. To name a few, there has been such efforts like:</t>

      <t><list style="symbols">
          <t><xref target="JSON_Hyper_Schema">JSON Hyper Schema</xref> as a
          part of JSON Schema.</t>

          <t><xref target="HAL">JSON Hypermedia API Language</xref></t>

          <t><xref target="JSON_Home">Home Documents for HTTP APIs</xref></t>
        </list></t>

      <t>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.</t>

      <t>In addition, both <xref target="RFC7033">WebFinger</xref> and SCIM
      have defined similar mechanism for the use of themselves only.</t>

      <t>Exisitence of these overlapping specifications indicates that the
      community probably would benefit from a standard way of expressing such
      link relationships.</t>

      <t>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.</t>

      <t>EDITOR's NOTE: This document is inteded to start discussions on the
      topic.</t>
    </section>

    <section title="Requirements">
      <t>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 <xref
      target="RFC2119">RFC 2119</xref>.</t>
    </section>

    <section anchor="metaobjects" title="JSON Meta Object">
      <t>A JSON Meta Object uses the format described in <xref
      target="RFC4627"/> and is intended to be inserted into a JSON document
      to express some of the metadata associated with it as <spanx
      style="verb">_links</spanx> member.</t>

      <t>NOTE: <spanx style="verb">_links</spanx> was chosen because it
      probably would have less collision with the existing names since it
      starts with an underscore (_).</t>

      <t>The value of the <spanx style="verb">_links</spanx> member is a JSON
      object that expresses link relations (<spanx style="verb">rel</spanx>),
      which in turn holds an object with <spanx style="verb">href</spanx> and
      other members or an array of such objects.</t>

      <t>Following non-normative schematic example should help envisage what
      it would look like. (Note: line-wraps are for display purpose only.)</t>

      <figure>
        <artwork><![CDATA[      {
        "_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"
      }]]></artwork>
      </figure>

      <t/>

      <t>Here, we have <spanx style="verb">_links</spanx> member that
      expresses various "relations" such as <spanx style="verb">self</spanx>
      and <spanx style="verb">userinfo</spanx>, 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 <spanx
      style="verb">href</spanx>. They are explained in the next section.</t>

      <t/>

      <section anchor="_links" title="_links Member">
        <t><spanx style="verb">_links</spanx> member holds exactly one object
        that contains the following members with relation as the <spanx
        style="verb">string</spanx> defined in <xref target="RFC4627"/>. The
        <spanx style="verb">string</spanx> SHOULD be a link relation type that
        is either defined in the IANA registry defined in <xref format="title"
        target="RFC5988">Web Linking</xref> or a URI that describes the
        relation.</t>

        <t>Each relation member holds exactly one object or one array, whose
        elements are objects. Each object has following members, which are all
        optional.</t>

        <section anchor="href" title="href">
          <t>The value of the <spanx style="verb">href</spanx> member is a
          <xref target="RFC6570">URI Template</xref> 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
          <spanx style="verb">string</spanx> matches the template variable
          name.</t>
        </section>

        <section anchor="ctype" title="content-type">
          <t>The content-type to be used when the parameters are sent to the
          URL.</t>

          <t>[todo] Locate the proper reference and name for content transfer
          encodings.</t>

          <t>e.g., <spanx style="verb">application/x-www-form-urlencoded</spanx>,
          <spanx style="verb">multipart/form-data</spanx>, <spanx
          style="verb">application/json</spanx>.</t>
        </section>

        <section title="title">
          <t>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.</t>
        </section>

        <section title="method">
          <t>The HTTP method defined in [RFC2616] that can be used to the URL
          described in the href. e.g., GET, POST, PUT, DELETE.</t>

          <t>EDITOR'S NOTE: Maybe we want to drop this section for
          simplicity.</t>
        </section>

        <section anchor="authz" title="Authorize">
          <t>The HTTP Authorize header defined in <xref
          target="RFC2616">Hypertext Transfer Protocol -- HTTP/1.1</xref> to
          be used when accessing the resource identified by href. It is
          templated in exactly the same syntax as in <xref
          target="RFC6570">URI Template</xref> except that it is applied to
          the Authorization request header than the URI.</t>

          <t>EDITOR'S NOTE: Maybe we want to drop this section for
          simplicity.</t>
        </section>

        <section title="params">
          <t>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.</t>

          <t><list style="hanging">
              <t hangText="required">Boolean. true or false.</t>

              <t hangText="description">Human readable description of the
              variable.</t>
            </list>EDITOR'S NOTE: Maybe we want to drop this section for
          simplicity.</t>
        </section>
      </section>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>This document makes no request to IANA.</t>
    </section>

    <section anchor="Security" title="Security Considerations">
      <t/>

      <section title="href tampering">
        <t>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.</t>
      </section>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>This specification borrows heavily from <xref target="HAL"/>.</t>

      <t>[todo]</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119"?>

      <?rfc include='reference.RFC.2616'?>

      <?rfc include='reference.RFC.4627'?>

      <?rfc include='reference.RFC.5988'?>

      <?rfc include='reference.RFC.6570'?>
    </references>

    <references title="Informational References">
      <?rfc include='reference.RFC.6749'?>

      <?rfc include='reference.RFC.7033'?>

      <reference anchor="HAL"
                 target="http://tools.ietf.org/html/draft- kelly-json-hal-03">
        <front>
          <title>JSON Hypermedia API Language</title>

          <author fullname="Mike Kelly" initials="M." surname="Kelly">
            <address>
              <email>mike@stateless.co</email>
            </address>
          </author>

          <date day="12" month="February" year="2013"/>
        </front>
      </reference>

      <reference anchor="JSON_Home"
                 target="http://tools.ietf.org/html/draft-nottingham-json-home-03">
        <front>
          <title>Home Documents for HTTP APIs</title>

          <author fullname="Mark Nottingham" initials="M."
                  surname="Nottingham">
            <organization/>

            <address/>
          </author>

          <date day="8" month="May" year="2013"/>
        </front>
      </reference>

      <reference anchor="JSON_Hyper_Schema"
                 target="http://json-schema.org/latest/json-schema-hypermedia.html">
        <front>
          <title>JSON Hypermedia Schema</title>

          <author fullname="Geraint Luff" initials="G." surname="Luff">
            <address>
              <email>luffgd@gmail.com</email>
            </address>
          </author>

          <author fullname="Kris Zyp" initials="K." surname="Zyp">
            <organization>SitePen (USA)</organization>

            <address>
              <postal>
                <street/>

                <city/>

                <region/>

                <code/>

                <country/>
              </postal>

              <phone/>

              <facsimile/>

              <email>kris@sitepen.com</email>

              <uri/>
            </address>
          </author>

          <author fullname="Gary Court" initials="G." surname="Court">
            <organization>G</organization>

            <address>
              <postal>
                <street/>

                <city/>

                <region/>

                <code/>

                <country/>
              </postal>

              <phone/>

              <facsimile/>

              <email/>

              <uri/>
            </address>
          </author>

          <date day="12" month="February" year="2013"/>
        </front>
      </reference>
    </references>
  </back>
</rfc>