Media Types

Collection+JSON - Document Format

Description

Collection+JSON is a JSON-based read/write hypermedia-type designed to support management and querying of simple collections.

Author:
Mike Amundsen (mamund@yahoo.com)
Dates:
2011-05-04 (Created)
2013-02-24 (Updated)
Status:
Approved

Contents

  1. Profiles
  2. General Concepts
  3. Objects
  4. Arrays
  5. Properties
  6. Link Relations
  7. Data Types
  8. Extensibility
  9. Acknowledgements
  10. References
  11. Update History
NOTE:
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 RFC2119.

1.

Profiles

This section is proposed draft (2013-02-24 --mamund).

The Collection+JSON media-type supports the use of semantic profiles in order to provide additional information about the application-level semantics for the message body. This version of the specifiction supports three possible ways to communicate profile information in a Collection+JSON conversation:

  1. The profile parameter in the media type identifier
  2. A LINK header with rel="profile"
  3. Within the Collection+JSON body as a link element (in the links collection) with a relpoperty value of "profile".

The profile value is a list of one or more IRIs identifying specific constraints or conventions that apply to a Collection+JSON document. The profile MUST NOT change the semantics of the resource representation when processed without the profile. The profile value MAY also be used by clients to express their preferences. Profile IRIs SHOULD be dereferenceable and SHOULD provide additional related semantic information.

The profile value is OPTIONAL. It MAY be used in a request/response conversation. Servers MAY ignore this value when sent by the client. Clients MAY ignore this value when sent by the server.

NOTE:
The semantics of the profile parameter, link header, and link relation are covered in the Profile Link Relation Type specification.

1.1.

Profile Media-Type Parameter

Profile information can be supplied via the media type profile parameter. Examples of valid profile media-type parameters are:

  • application/vnd.collection+json;profile=http://example.org/profiles/vcard
  • application/vnd.collection+json;profile=http://example.org/profiles/vcard http://schema.org/Person
NOTE
The profile media type parameter value MAY be sent with both HTTP Requests (by clients) and HTTP Responses (by servers).

1.2.

Profile Link Header

The Link Header[RFC5988] can also be used to communicate profile details. Examples of valid profile Link headers are:

  • Link: <http://example.org/profiles/vcard>; rel="profile"
  • Link: <http://example.org/profiles/vcard>; rel="profile", <http://schema.org/Person>; rel="profile"
NOTE
Link header profile value MAY be sent with both HTTP Requests (by clients) and HTTP Responses (by servers).

1.3.

Profile Link Element

Profile information can be supplied as part of the top-level links collection in a Collection+JSON document. Examples of valid profile Link elements within a Collection+JSON document are:

  • "links: [{"link" : {"href" : "http://example.org/profiles/vcard", "rel" : "profile"}]
  • "links: [
    {"link" : {"href" : "http://example.org/profiles/vcard", "rel" : "profile"},
    {"link" : {"href" : "http://schema.org/Person", "rel" : "profile"}
    ]
NOTE
The profile link element MAY be sent with HTTP Responses (by servers), but not with HTTP Requests.

2.

General Concepts

This section contains general concepts that apply to all Collection+JSON documents.

The Collection+JSON hypermedia type is designed to support full read/write capability for simple lists (contacts, tasks, blog entries, etc.). The standard application semantics supported by this media type include Create, Read, Update, and Delete (CRUD) along w/ support for predefined queries including query templates (similar to HTML "GET" forms). Write operations are defined using a template object supplied by the server as part of the response representation.

Each item in a Collection+JSONcollection has an assigned URI (via the href property) and an optional array of one or more data elements along with an optional array of one or more link elements. Both arrays support a name property for each object in the collection in order to decorate these elements with domain-specific semantic information (e.g. "data" : [{"name" : "first-name", ...},...]).

The Collection+JSON hypermedia type has a limited set of predefined link relation values and supports additional values applied by implementors in order to better describe the application domain to which the media type is applied.

The following sections describe the process of reading and writing data using the Collection+JSON hypermedia type as well as the way to parse and execute Query Templates. Additional examples can be found in the Examples section of this documentation.

2.1.

Reading and Writing Data

The Collection+JSON media type supports a limited form of read/write semantics; the Create-Read-Update-Delete (or CRUD) pattern. In addition to CRUD operations, the Collection+JSON media type supports Query Templates.

This section describes the details of how clients can recognize and implement reads and writes found within Collection+JSON responses.

2.1.1.

Reading Collections

To get a list of the items in a collection, the client sends an HTTP GET request to the URI of a collection. a Collection+JSON Document is returned which contains one or more item objects in an array. The response may describe all, or only a partial list, of the items in a collection.

*** REQUEST ***
GET /my-collection/ HTTP/1.1
Host: www.example.org
Accept: application/vnd.collection+json

*** RESPONSE ***
200 OK HTTP/1.1
Content-Type: application/vnd.collection+json
Content-Length: xxx

{ "collection" : {...}, ... }

2.1.2.

Adding an Item

To create a new item in the collection, the client first uses the template object to compose a valid item representation and then uses HTTP POST to send that representation to the server for processing.

If the item resource was created successfully, the server responds with a status code of 201 and a Location header that contains the URI of the newly created item resource.

*** REQUEST ***
POST /my-collection/ HTTP/1.1
Host: www.example.org
Content-Type: application/vnd.collection+json

{ "template" : { "data" : [ ...] } }
 
*** RESPONSE ***
201 Created HTTP/1.1
Location: http://www.example.org/my-collection/1

Once an item resource has been created and its URI is known, that URI can be used to read, update, and delete the resource.

2.1.3.

Reading an Item

Clients can retrieve an existing item resource by sending an HTTP GET request to the URI of an item resource. If the request is valid, the server will respond with a representation of that item resource.

*** REQUEST ***
GET /my-collection/1 HTTP/1.1
Host: www.example.org
Accept: application/vnd.collection+json

*** RESPONSE ***
200 OK HTTP/1.1
Content-Type: application/vnd.collection+json
Content-Length: xxx

{ "collection" : { "href" : "...", "items" : [ { "href" : "...", "data" : [...] } } }

Note that the valid response is actually a complete collection document that contains only one item (and possibly related queries and template properties).

2.1.4.

Updating an Item

To update an existing resource, the client uses the template object as a guide to composing a replacement item representation and then uses HTTP PUT to send that representation to the server.

If the update is successful, the server will respond with HTTP status code 200 and possibly a representation of the updated item resource representation.

*** REQUEST ***
PUT /my-collection/1 HTTP/1.1
Host: www.example.org
Content-Type: application/vnd.collection+json

{ "template" : { "data" : [ ...] } }
 
*** RESPONSE ***
200 OK HTTP/1.1   

2.1.5.

Deleting an Item

Clients can delete existing resources by sending an HTTP DELETE request to the URI of the item resource.

If the delete request is successful, the server SHOULD respond with an HTTP status code of 204.

*** REQUEST ***
DELETE /my-collection/1 HTTP/1.1
Host: www.example.org
 
*** RESPONSE ***
204 No Content HTTP/1.1   

2.2.

Query Templates

Clients that support the Collection+JSON media type SHOULD be able to recognize and parse query templates found within responses. Query templates consist of a data array associated with an href property. The queries array supports query templates.

For query templates, the name/value pairs of the data array set are appended to the URI found in the href property associated with the queries array (with a question-mark ["?"] as separator) and this new URI is sent to the processing agent.

// query template sample
{
  "queries" :
  [
    {
      "href" : "http://example.org/search",
      "rel" : "search",
      "prompt" : "Enter search string",
      "data" :
      [
        {"name" : "search", "value" : ""}
      ]
    }
  ]
}

In the above example, if the user supplied "JSON" for the value property, the user agent would construct the following URI:

http://example.org/search?search=JSON

3.

Objects

An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a string, number, boolean, null, object, or array.

3.1.

collection

The collection object contains all the "records" in the representation. This is a REQUIRED object and there MUST NOT be more than one collection object in a Collection+JSON document. It is a top-level document property.

The collection object SHOULD have a version property. For this release, the value of the version property MUST be set to 1.0. If there is no version property present, it should be assumed to be set to 1.0.

The collection object SHOULD have an href property. The href property MUST contain a valid URI. This URI SHOULD represent the address used to retrieve a representation of the document. This URI MAY be used to add a new record (See Reading and Writing Data).

The collection object MAY have an links array child property.

The collection object MAY have an items array child property.

The collection object MAY have an queries array child property.

The collection object MAY have an template object child property.

The collection object MAY have an error object child property.

// sample collection object
{
  "collection" :
  {
    "version" : "1.0",
    "href" : URI,
    "links" : [ARRAY],
    "items" : [ARRAY],
    "queries" : [ARRAY],
    "template" : {OBJECT},
    "error" : {OBJECT}
  }
}

3.2.

error

The error object contains addiitional information on the latest error condition reported by the server. This is an OPTIONAL object and there MUST NOT be more than one error object in a Collection+JSON document. It is a top-level document property.

// sample error object
{
  "error" :
  {
    "title" : STRING,
    "code" : STRING,
    "message" : STRING  
  }
}

3.3.

template

The template object contains all the input elements used to add or edit collection "records." This is an OPTIONAL object and there MUST NOT be more than one template object in a Collection+JSON document. It is a top-level document property.

The template object SHOULD have a data array child property.

// sample template object
{
  "template" :
  {
    "data" : [ARRAY]  
  }
}

4.

Arrays

An array is an ordered sequence of zero or more values.

4.1.

items

The items array represents the list of records in the Collection+JSON document. It is a child property of the collection object.

Each element in the items array SHOULD contain an href property. The href property MUST contain a URI. This URI MAY be used to retrieve a Collection+JSON document representing the associated item. It MAY be used to edit or delete the associated item. See Reading and Writing Data for details.

The items array MAY have a data array child property.

The items array MAY have a links array child property.

// sample items array
{
  "collection" :
  {
    "version" : "1.0",
    "href" : URI,
    "items" :
    [
      {
        "href" : URI,
        "data" : [ARRAY],
        "links" : [ARRAY]
      },
      ...
      {
        "href" : URI,
        "data" : [ARRAY],
        "links" : [ARRAY]
      }
    ]
  }
}

4.2.

data

The data array is a child property of the items array and the template object.

The data array SHOULD contain one or more anonymous objects. Each object is MAY have any of three possible properties: name (REQUIRED), value (OPTIONAL), and prompt (OPTIONAL).

// sample data array
{
  "template" :
  {
    "data" :
    [
      {"prompt" : STRING, "name" : STRING, "value" : VALUE},
      {"prompt" : STRING, "name" : STRING, "value" : VALUE},
      ...
      {"prompt" : STRING, "name" : STRING, "value" : VALUE}
    ]
  }
}

4.3.

queries

The queries array is an OPTIONAL top-level property of the Collection+JSON document.

The queries array SHOULD contain one or more anonymous objects. Each object composed of five possible properties: href (REQUIRED), rel (REQUIRED), name (OPTIONAL), prompt (OPTIONAL), and a data array (OPTIONAL).

If present, the data array represents query parameters for the associated href property of the same object. See Query Templates for details.

// sample queries array
{
  "queries" :
  [
    {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING},
    {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING,
      "data" :
      [
        {"name" : STRING, "value" : VALUE}
      ]
    },
    ...
    {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING}
  ]
}

4.4.

links

The links array is an OPTIONAL child property of the items array. It SHOULD contain one or more anonymous objects. Each has five possible properties: href (REQUIRED), rel (REQURIED), name (OPTIONAL), render (OPTIONAL), and prompt, (OPTIONAL).

// sample links array
{
  "collection" :
  {
    "version" : "1.0",
    "href" : URI,
    "items" :
    [
      {
        "href" : URI,
        "data" : [ARRAY],
        "links" :
        [
          {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING, "render" : "image"},
          {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING, "render" : "link"},
          ...
          {"href" : URI, "rel" : STRING, "prompt" : STRING, "name" : STRING}
        ]
      }
    ]
  }
}

5.

Properties

Properties represent individual name/value pairs for objects within Collection+JSON documents.

5.1.

code

The code property MAY be a child property of the error object.

It SHOULD be a STRING type.

5.2.

href

It MUST contain a valid URI.

5.3.

message

The message property MAY be a child property of the error object.

It SHOULD be a STRING type.

5.4.

name

The name property MAY be a child element of the data array and the links array.

It SHOULD be a STRING data type.

5.5.

prompt

The prompt property MAY appear as a child property of the queries array, the links array, and the data array.

It SHOULD be a STRING data type.

5.6.

rel

    The rel MAY be a child property of the following:
  • links array elements
  • and
  • queries array elements
  • .

It SHOULD be a STRING data type.

5.7.

render

The render MAY be a child property of the links array element.

It SHOULD be a STRING data type. The value MUST be either image or link. If the render property does not appear on a links array element, it should be assumed to be set to link.

5.8.

title

The title property MAY be a child property of the error object.

It SHOULD be a STRING type.

5.9.

value

The value property MAY be a child element of data array elements

    It MAY contain one of the following data types:
  • STRING
  • NUMBER
  • truev
  • false
  • or
  • null

5.10.

version

The version SHOULD be a child property of the collection collection element. It SHOULD be a STRING data type. For this release, the version SHOULD be set to 1.0.

6.

Link Relations

Link relation values can be used to annotate links array and queries array properties.

6.1.

collection

The target IRI points to a resource which represents a list of which the context IRI is a member.

When used in the Collection+JSON media type, this link relation value refers to a collection document.

Logged with the Microformats Existing Rel Values.

6.2.

item

The target IRI points to a resource that is a member of a collection represented by the context IRI.

When used in the Collection+JSON media type, this link relation refers to an individual item in a collection.

Logged with the Microformats Existing Rel Values.

6.3.

template

The target IRI points to a resource that is a representation of a valid write template for the data represented by the context IRI.

When use in the Collection+JSON media type, this link relation value refers to the template object of a collection.

6.4.

queries

The target IRI points to a resource that is a representation of a list of valid queries that can be executed against the data represented by the context IRI.

When used in the Collection+JSON media type, this link relation value refers to the queries object of a collection.

6.5.

Other Link Relation Values

The Collection+JSON media type has a limited set of defined link relations. Implementors are free to use any additional link relation values as needed and are encouraged to use already defined link relation values found in existing registries.

Suggested registries are (but not limited to):

Implementors may also wish to create their own unique link relation values using the standards outlined in RFC5988.

7.

Data Types

Below are the data types used in Collection+JSON documents. The reference for most of the data type definitions below is the JSON Grammar section of the RFC4627 .

7.1.

OBJECT

An OBJECT structure is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members). A name is a string. A single colon comes after each name, separating the name from the value. A single comma separates a value from a following name. The names within an object SHOULD be unique.

7.2.

ARRAY

An ARRAY structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas.

7.3.

NUMBER

A NUMBER contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part.

Octal and hex forms are not allowed. Leading zeros are not allowed.

A fraction part is a decimal point followed by one or more digits.

An exponent part begins with the letter E in upper or lowercase, which may be followed by a plus or minus sign. The E and optional sign are followed by one or more digits.

7.4.

STRING

A STRING begins and ends with quotation marks. All Unicode characters may be placed within the quotation marks except for the characters that must be escaped: quotation mark, reverse solidus, and the control characters (U+0000 through U+001F).

7.5.

URI

A URI is defined by RFC 3986

7.6.

VALUE

A VALUE data type MUST be a NUMBER, STRING, or one of the following literal names: false, null, or true.

NOTE: This release of Collection+JSON does not support OBJECT or ARRAY as a valid VALUE.

8.

Extensibility

This document describes the Collection+JSON markup vocabulary. Markup from other vocabularies ("foreign markup") can be used in a Collection+JSON document. Any extensions to the Collection+JSON vocabulary MUST not redefine any objects (or their properties), arrays, properties, link relations, or data types defined in this document. Clients that do not recognize extensions to the Collection+JSON vocabulary SHOULD ignore them.

The details of designing and implementing Collection+JSON extensions is beyond the scope of this document.

NOTE: It is possible that future forward-compatible modifications to this specification will include new objects, arrays, properties, link-relations, and data types. Extension designers should take care to prevent future modifications from breaking or redefining those extensions.

9.

Acknowledgements

The author gratefully acknowledges the following individuals who generously contributed corrections, comments, and criticism on the design of this media type:

10.

References