Internet Engineering Task Force                              K. Zyp, Ed.

Internet-Draft                                             SitePen (USA)

Intended status: Informational                            March 23, 2010

Expires: September 24, 2010

   A JSON Media Type for Describing the Structure and Meaning of JSON

                               Documents

                        draft-zyp-json-schema-02

Abstract

   JSON (JavaScript Object Notation) Schema defines the media type

   application/schema+json, a JSON based format for defining the

   structure of JSON data.  JSON Schema provides a contract for what

   JSON data is required for a given application and how to interact

   with it.  JSON Schema is intended to define validation,

   documentation, hyperlink navigation, and interaction control of JSON

   data.

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/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at

   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on September 24, 2010.

Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the

   document authors.  All rights reserved.

Zyp                    Expires September 24, 2010               [Page 1]

Internet-Draft           JSON Schema Media Type               March 2010

   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 BSD License.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4

   2.  Conventions  . . . . . . . . . . . . . . . . . . . . . . . . .  4

   3.  Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

     3.1.  Terminology  . . . . . . . . . . . . . . . . . . . . . . .  5

     3.2.  Design Considerations  . . . . . . . . . . . . . . . . . .  6

   4.  Schema/Instance Association  . . . . . . . . . . . . . . . . .  6

     4.1.  Self-Descriptive Schema  . . . . . . . . . . . . . . . . .  7

   5.  Core Schema Definition . . . . . . . . . . . . . . . . . . . .  7

     5.1.  type . . . . . . . . . . . . . . . . . . . . . . . . . . .  8

     5.2.  properties . . . . . . . . . . . . . . . . . . . . . . . .  8

     5.3.  items  . . . . . . . . . . . . . . . . . . . . . . . . . .  9

     5.4.  optional . . . . . . . . . . . . . . . . . . . . . . . . .  9

     5.5.  additionalProperties . . . . . . . . . . . . . . . . . . .  9

     5.6.  requires . . . . . . . . . . . . . . . . . . . . . . . . .  9

     5.7.  minimum  . . . . . . . . . . . . . . . . . . . . . . . . . 10

     5.8.  maximum  . . . . . . . . . . . . . . . . . . . . . . . . . 10

     5.9.  minimumCanEqual  . . . . . . . . . . . . . . . . . . . . . 10

     5.10. maximumCanEqual  . . . . . . . . . . . . . . . . . . . . . 10

     5.11. minItems . . . . . . . . . . . . . . . . . . . . . . . . . 10

     5.12. maxItems . . . . . . . . . . . . . . . . . . . . . . . . . 10

     5.13. uniqueItems  . . . . . . . . . . . . . . . . . . . . . . . 10

     5.14. pattern  . . . . . . . . . . . . . . . . . . . . . . . . . 10

     5.15. maxLength  . . . . . . . . . . . . . . . . . . . . . . . . 11

     5.16. minLength  . . . . . . . . . . . . . . . . . . . . . . . . 11

     5.17. enum . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

     5.18. title  . . . . . . . . . . . . . . . . . . . . . . . . . . 11

     5.19. description  . . . . . . . . . . . . . . . . . . . . . . . 11

     5.20. format . . . . . . . . . . . . . . . . . . . . . . . . . . 11

     5.21. contentEncoding  . . . . . . . . . . . . . . . . . . . . . 12

     5.22. default  . . . . . . . . . . . . . . . . . . . . . . . . . 13

     5.23. divisibleBy  . . . . . . . . . . . . . . . . . . . . . . . 13

     5.24. disallow . . . . . . . . . . . . . . . . . . . . . . . . . 13

     5.25. extends  . . . . . . . . . . . . . . . . . . . . . . . . . 13

   6.  Hyper Schema . . . . . . . . . . . . . . . . . . . . . . . . . 13

     6.1.  links  . . . . . . . . . . . . . . . . . . . . . . . . . . 13

       6.1.1.  Link Description Object  . . . . . . . . . . . . . . . 14

Zyp                    Expires September 24, 2010               [Page 2]

Internet-Draft           JSON Schema Media Type               March 2010

     6.2.  fragmentResolution . . . . . . . . . . . . . . . . . . . . 18

       6.2.1.  dot-delimited fragment resolution  . . . . . . . . . . 18

       6.2.2.  slash-delimited fragment resolution  . . . . . . . . . 19

     6.3.  root . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

     6.4.  readonly . . . . . . . . . . . . . . . . . . . . . . . . . 19

     6.5.  pathStart  . . . . . . . . . . . . . . . . . . . . . . . . 20

     6.6.  mediaType  . . . . . . . . . . . . . . . . . . . . . . . . 20

     6.7.  alternate  . . . . . . . . . . . . . . . . . . . . . . . . 20

   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 20

   8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 21

     8.1.  Registry of Link Relations . . . . . . . . . . . . . . . . 21

   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 22

     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 22

     9.2.  Informative References . . . . . . . . . . . . . . . . . . 22

   Appendix A.  Change Log  . . . . . . . . . . . . . . . . . . . . . 23

   Appendix B.  Open Issues . . . . . . . . . . . . . . . . . . . . . 24

Zyp                    Expires September 24, 2010               [Page 3]

Internet-Draft           JSON Schema Media Type               March 2010

1.  Introduction

   JSON (JavaScript Object Notation) Schema is a JSON media type for

   defining the structure of JSON data.  JSON Schema provides a contract

   for what JSON data is required for a given application and how to

   interact with it.  JSON Schema is intended to define validation,

   documentation, hyperlink navigation, and interaction control of JSON

   data.

2.  Conventions

   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.

3.  Overview

   JSON Schema defines the media type application/schema+json for

   describing the structure of other JSON documents.  JSON Schema is

   JSON-based and includes facilities for describing the structure of

   JSON documents in terms of allowable values, descriptions, and

   interpreting relations with other resources.

   JSON Schema format is organized into several separate definitions.

   The first definition is the core schema specification.  This

   definition is primary concerned with describing a JSON structure and

   specifying valid elements in the structure.  The second definition is

   the Hyper Schema specification which is intended define elements in a

   structure that can be interpreted as hyperlinks.  Hyper Schema builds

   on JSON Schema to describe the hyperlink structure of other JSON

   documents.  This allows user agents to be able to successfully

   navigate JSON documents based on their schemas.

   Cumulatively JSON Schema acts as a meta-document that can be used to

   define the required type and constraints on property values, as well

   as define the meaning of the property values for the purpose of

   describing a resource and determining hyperlinks within the

   representation.

   An example JSON Schema that describes products might look like:

Zyp                    Expires September 24, 2010               [Page 4]

Internet-Draft           JSON Schema Media Type               March 2010

   {

     "name":"Product",

     "properties":{

       "id":{

         "type":"number",

         "description":"Product identifier"

       },

       "name":{

         "description":"Name of the product",

         "type":"string"

       },

       "price":{

         "type": "number",

         "minimum":0

       },

       "tags":{

         "optional":true,

         "type":"array",

         "items":{

            "type":"string"

         }

       }

     },

     "links":[

       {

         "rel":"full",

         "href":"{id}"

       },

       {

         "rel":"comments",

         "href":"comments/?id={id}"

       }

     ]

   }

   This schema defines the properties of the instance JSON documents and

   their required properties (id, name, and price) as well as an

   optional property (tags).  This also defines the link relations of

   the instance JSON documents.

3.1.  Terminology

   For this specification, a schema will be used to denote a JSON Schema

   definition, and an instance refers to the JSON object or array that

   the schema will be describing and validating

Zyp                    Expires September 24, 2010               [Page 5]

Internet-Draft           JSON Schema Media Type               March 2010

3.2.  Design Considerations

   The JSON Schema media type does not attempt to dictate the structure

   of JSON representations that contain data, but rather provides a

   separate format for flexibly communicating how a JSON representation

   should be interpreted and validated, such that user agents can

   properly understand acceptable structures and extrapolate hyperlink

   information with the JSON document.  It is acknowledged that JSON

   documents come in a variety of structures, and JSON is unique in that

   the structure of stored data structures often prescribes a non-

   ambiguous definite JSON representation.  Attempting to force a

   specific structure is generally not viable, and therefore JSON Schema

   allows for great flexibility in the structure of JSON data that it

   describes.

   This specification is protocol agnostic.  The underlying protocol

   (such as HTTP) should sufficiently define the semantics of the

   client-server interface, the retrieval of resource representations

   linked to by JSON representations, and modification of those

   resources.  The goal of this format is to sufficiently describe JSON

   structures such that one can utilize existing information available

   in existing JSON representations from a large variety of services

   that leverage a representational state transfer architecture using

   existing protocols.

4.  Schema/Instance Association

   JSON Schema instances are correlated to their schema by the

   "describedby" relation, where the schema is defined to be the target

   of the relation.  Instance representations may be of the application/

   json media type or any other subtype.  Consequently, dictating how an

   instance representation should specify the relation to the schema is

   beyond the normative scope of this document (since this document

   specifically defines the JSON Schema media type, and no other), but

   it is recommended that instances specify their schema so that user

   agents can interpret the instance representation and messages may

   retain the self-descriptive characteristic, avoiding the need for

   out-of-band information about instance data.  Two approaches are

   recommended for declaring the relation to the schema that describes

   the meaning of a JSON instance's (or collection of instances)

   structure.  A MIME type parameter named "profile" or a Link header

   with a relation of "describedby" SHOULD be used:

   Content-Type: application/json;

                 profile=http://json.com/my-hyper-schema

   or if the content is being transferred by a protocol (such as HTTP)

Zyp                    Expires September 24, 2010               [Page 6]

Internet-Draft           JSON Schema Media Type               March 2010

   that provides headers, a Link header can be used:

   Link: <http://json.com/my-hyper-schema>; rel="describedby"

   Instances MAY specify multiple schemas, to indicate all the schemas

   that are applicable to the data.  The instance data may have multiple

   schemas that it is defined by (the instance data should be valid for

   those schemas).  Or if the document is a collection of instances, the

   collection may contain instances from different schemas.  When

   collections contain heterogeneous instances, the pathStart attribute

   MAY be specified in the schema to disambiguate which schema should be

   applied for each item in the collection.

4.1.  Self-Descriptive Schema

   JSON Schemas are themselves instances for the schema schemas.  A

   self-describing JSON Schema for the core JSON Schema can be found at

   http://json-schema.org/schema and the hyper schema self-description

   can be found at: http://json-schema.org/hyper-schema.  All schemas

   used within a protocol with media type definitions SHOULD include a

   MIME parameter that refers to the self-descriptive hyper schema or

   another schema that extends this hyper schema:

   Content-Type: application/json;

                 profile=http://www.json-schema.org/hyper-schema

5.  Core Schema Definition

   A JSON Schema is a JSON Object that defines various attributes of the

   instance and defines it's usage and valid values.  A JSON Schema is a

   JSON Object with schema attribute properties.  The following is the

   grammar of a JSON Schema:

   And an example JSON Schema definition could look like:

   {"description":"A person",

    "type":"object",

    "properties":

     {"name": {"type":"string"},

      "age" : {"type":"integer",

        "maximum":125}}

   }

   A JSON Schema object may have any of the following properties, called

Zyp                    Expires September 24, 2010               [Page 7]

Internet-Draft           JSON Schema Media Type               March 2010

   schema attributes (all attributes are optional):

5.1.  type

      Union type definition - An array with two or more items which

      indicates a union of type definitions.  Each item in the array may

      be a simple type definition or a schema.  The instance value is

      valid if it is of the same type as one the type definitions in the

      array or if it is valid by one of the schemas in the array.  For

      example to indicate that a string or number is a valid: {"type":

      ["string","number"]}

      Simple type definition - A string indicating a primitive or simple

      type.  The following are acceptable strings:

         string - Value must be a string.

         number - Value must be a number, floating point numbers are

         allowed.

         integer - Value must be an integer, no floating point numbers

         are allowed.  This is a subset of the number type.

         boolean - Value must be a boolean.

         object - Value must be an object.

         array - Value must be an array.

         null - Value must be null.  Note this is mainly for purpose of

         being able use union types to define nullability.

         any - Value may be of any type including null.  If the property

         is not defined or is not in this list, than any type of value

         is acceptable.  Other type values may be used for custom

         purposes, but minimal validators of the specification

         implementation can allow any instance value on unknown type

         values.

5.2.  properties

   This should be an object type definition, which is an object with

   property definitions that correspond to instance object properties.

   When the instance value is an object, the property values of the

   instance object must conform to the property definitions in this

   object.  In this object, each property definition's value should be a

   schema, and the property's name should be the name of the instance

   property that it defines.

Zyp                    Expires September 24, 2010               [Page 8]

Internet-Draft           JSON Schema Media Type               March 2010

5.3.  items

   This should be a schema or an array of schemas.  When this is an

   object/schema and the instance value is an array, all the items in

   the array must conform to this schema.  When this is an array of

   schemas and the instance value is an array, each position in the

   instance array must conform to the schema in the corresponding

   position for this array.  This called tuple typing.  When tuple

   typing is used, additional items are allowed, disallowed, or

   constrained by the additionalProperties attribute using the same

   rules as extra properties for objects.  The default value is an empty

   schema which allows any value for items in the instance array.

5.4.  optional

   This indicates that the instance property in the instance object is

   optional.  This is false by default.

5.5.  additionalProperties

   This provides a default property definition for all properties that

   are not explicitly defined in an object type definition.  The value

   must be a schema.  If false is provided, no additional properties are

   allowed, and the schema can not be extended.  The default value is an

   empty schema which allows any value for additional properties.

5.6.  requires

   This indicates that if this property is present in the containing

   instance object, the property given by requires attribute must also

   be present in the containing instance object.  The value of this

   property may be a string, indicating the require property name.  Or

   the value may be a schema, in which case the containing instance must

   be valid by the schema if the property is present.  For example if a

   object type definition is defined:

   {

     "state":

     {

       "optional":true

     },

     "town":

     {

       "requires":"state",

       "optional":true

     }

   }

Zyp                    Expires September 24, 2010               [Page 9]

Internet-Draft           JSON Schema Media Type               March 2010

   An instance must include a state property if a town property is

   included.  If a town property is not included, the state property is

   optional.

5.7.  minimum

   This indicates the minimum value for the instance property when the

   type of the instance value is a number.

5.8.  maximum

   This indicates the minimum value for the instance property when the

   type of the instance value is a number.

5.9.  minimumCanEqual

   If the minimum is defined, this indicates whether or not the instance

   property value can equal the minimum.

5.10.  maximumCanEqual

   If the maximum is defined, this indicates whether or not the instance

   property value can equal the maximum.

5.11.  minItems

   This indicates the minimum number of values in an array when an array

   is the instance value.

5.12.  maxItems

   This indicates the maximum number of values in an array when an array

   is the instance value.

5.13.  uniqueItems

   This indicates that all the items in an array must be unique (no two

   identical values) within that array when an array is the instance

   value.

5.14.  pattern

   When the instance value is a string, this provides a regular

   expression that a instance string value should match in order to be

   valid.  Regular expressions should follow the regular expression

   specification from ECMA 262/Perl 5

Zyp                    Expires September 24, 2010              [Page 10]

Internet-Draft           JSON Schema Media Type               March 2010

5.15.  maxLength

   When the instance value is a string, this indicates maximum length of

   the string.

5.16.  minLength

   When the instance value is a string, this indicates minimum length of

   the string.

5.17.  enum

   This provides an enumeration of possible values that are valid for

   the instance property.  This should be an array, and each item in the

   array represents a possible value for the instance value.  If "enum"

   is included, the instance value must be one of the values in enum

   array in order for the schema to be valid.

5.18.  title

   This provides a short description of the instance property.  The

   value must be a string.

5.19.  description

   This provides a full description of the of purpose the instance

   property.  The value must be a string.

5.20.  format

   This property indicates the type of data, content type, or

   microformat to be expected in the instance property values.  A format

   attribute may be one of the values listed below, and if so, should

   adhere to the semantics describing for the format.  A format should

   only be used give meaning to primitive types (string, integer,

   number, or boolean).  Validators are not required to validate that

   the instance values conform to a format.  The following formats are

   defined:

      Any valid MIME media type may be used as a format value, in which

      case the instance property value must be a string, representing

      the contents of the MIME file.

      date-time - This should be a date in ISO 8601 format of YYYY-MM-

      DDThh:mm:ssZ in UTC time.  This is the recommended form of date/

      timestamp.

Zyp                    Expires September 24, 2010              [Page 11]

Internet-Draft           JSON Schema Media Type               March 2010

      date - This should be a date in the format of YYYY-MM-DD.  It is

      recommended that you use the "date-time" format instead of "date"

      unless you need to transfer only the date part.

      time - This should be a time in the format of hh:mm:ss.  It is

      recommended that you use the "date-time" format instead of "time"

      unless you need to transfer only the time part.

      utc-millisec - This should be the difference, measured in

      milliseconds, between the specified time and midnight, January 1,

      1970 UTC.  The value should be a number (integer or float).

      regex - A regular expression.

      color - This is a CSS color (like "#FF0000" or "red").

      style - This is a CSS style definition (like "color: red;

      background-color:#FFF").

      phone - This should be a phone number (format may follow E.123).

      uri - This value should be a URI..

      email - This should be an email address.

      ip-address - This should be an ip version 4 address.

      ipv6 - This should be an ip version 6 address.

      street-address - This should be a street address.

      locality - This should be a city or town.

      region - This should be a region (a state in the US, province in

      Canada, etc.)

      postal-code - This should be a postal code (AKA zip code).

      country - This should be the name of a country.

      Additional custom formats may be defined with a URL to a

      definition of the format.

5.21.  contentEncoding

   If the instance property value is a string, this indicates that the

   string should be interpreted as binary data and decoded using the

   encoding named by this schema property.  RFC 2045, Sec 6.1 lists

Zyp                    Expires September 24, 2010              [Page 12]

Internet-Draft           JSON Schema Media Type               March 2010

   possible values.

5.22.  default

   This indicates the default for the instance property.

5.23.  divisibleBy

   This indicates that the instance property value must be divisible by

   the given schema value when the instance property value is a number.

5.24.  disallow

   This attribute may take the same values as the "type" attribute,

   however if the instance matches the type or if this value is an array

   and the instance matches any type or schema in the array, than this

   instance is not valid.

5.25.  extends

   The value of this property should be another schema which will

   provide a base schema which the current schema will inherit from.

   The inheritance rules are such that any instance that is valid

   according to the current schema must be valid according to the

   referenced schema.  This may also be an array, in which case, the

   instance must be valid for all the schemas in the array.

6.  Hyper Schema

   This section defines hypermedia definitions of JSON schema.  The

   following attributes are specified in addition to those attributes

   that already provided by JSON schema with the specific purpose of

   informing user agents of relations between resources based on JSON

   data.  Just as with JSON schema attributes, all the attributes in

   hyper-schema are optional.  Therefore an empty object is a valid

   (non-informative) schema, and essentially describes plain JSON (no

   constraints on the structures).  Addition of attributes provides

   additive information for user agents.

6.1.  links

   The value of the links property should be an array, where each item

   in the array is a link description object which describes the link

   relations of the instances.

Zyp                    Expires September 24, 2010              [Page 13]

Internet-Draft           JSON Schema Media Type               March 2010

6.1.1.  Link Description Object

   A link description object is used to describe the link relations.  In

   the context of a schema, it defines the link relations of the

   instances of the schema, and can be parameterized by the instance

   values.  The link description format can be used on its own in

   regular (non-schema documents), and use of this format can be

   declared by referencing the normative link description schema as the

   the schema for the data structure that uses the links.  The URI of

   the normative link description schema is:

   http://json-schema.org/links.

6.1.1.1.  href

   The value of the "href" link description property indicates the

   target URI of the related resource.  The value of the instance

   property should be resolved as a URI-Reference per [RFC3986] and may

   be a relative URI.  The base URI to be used for relative resolution

   should be the URI used to retrieve the instance object (not the

   schema) when used in the context of a schema.  Also, the URI may be

   parametrized by the property values of the instance object.

   Instance property values should be substituted into the URIs where

   matching braces ('{', '}') are found surrounding zero or more

   characters, creating an expanded URI.  Instance property value

   substitutions are resolved by using the text between the braces to

   denote the property name from the instance to get the value to

   substitute.  For example, if an href value is defined:

   http://somesite.com/{id}

   Then it would be resolved by replace the value of the "id" property

   value from the instance object.  If the value of the "id" property

   was "45", the expanded URI would be:

   http://somesite.com/45

   If matching braces are found with the string "-this" (no quotes)

   between the braces, than the actual instance value should be used to

   replace the braces, rather than a property value.  This should only

   be used in situations where the instance is a scalar (string,

   boolean, or number), and not for objects or arrays.

Zyp                    Expires September 24, 2010              [Page 14]

Internet-Draft           JSON Schema Media Type               March 2010

6.1.1.2.  rel

   The value of the "rel" property indicates the name of the relation to

   the target resource.  The relation to the target should be

   interpreted as specifically from the instance object that the schema

   (or sub-schema) applies to, not just the top level resource that

   contains the object within its hierarchy.  If a resource JSON

   representation contains a sub object with a property interpreted as a

   link, that sub-object holds the relation with the target.  A relation

   to target from the top level resource must be indicated with the

   schema describing the top level JSON representation.

   Relationship definitions SHOULD NOT be media type dependent, and

   users are encouraged to utilize existing accepted relation

   definitions, including those in existing relation registries (see

   &rfc4287).  However, we define these relation here for clarity of

   normative interpretation within the context of JSON hyper schema

   defined relations:

      self - If the relation value is "self", when this property is

      encountered in the instance object, the object represents a

      resource and the instance object is treated as a full

      representation of the target resource identified by the specified

      URI.

      full - This indicates that the target of the link is the full

      representation for the instance object.  The object that contains

      this link may not be the full representation.

      describedby - This indicates the target of the link is the schema

      for the instance object.  This may be used to specifically denote

      the schemas of objects within a JSON object hierarchy,

      facilitating polymorphic type data structures.

      The following relations are applicable for schemas (the schema as

      the "from" resource in the relation).

      instances - This indicates the target resource that represents

      collection of instances of a schema.

      create - This indicates a target to use for creating new instances

      of a schema.  This link definition SHOULD be a submission link

      with a non-safe method (like POST).

   For example, if a schema is defined:

Zyp                    Expires September 24, 2010              [Page 15]

Internet-Draft           JSON Schema Media Type               March 2010

   {

       "links": [

           {

                   "rel": "self"

                   "href": "{id}"

           },

           {

                   "rel": "up"

                   "href": "{upId}"

           },

           {

                   "rel": "children"

                   "href": "?upId={id}"

           }

       ]

   }

   And if a collection of instance resource's JSON representation was

   retrieved:

   GET /Resource/

   [

       {

           "id": "thing",

           "upId": "parent"

       },

       {

           "id": "thing2",

           "upId": "parent"

       }

   ]

   This would indicate that for the first item in the collection, it's

   own (self) URI would resolve to "/Resource/thing" and the first

   item's "up" relation should be resolved to the resource at