This is an old revision of the document!
<html> <body> <section>
<header>
<h1>Collection.next+JSON - Document Format</h1>
<h2>Lightweight hypermedia type for read/write Hypermedia/RESTful/HTTP APIs</h2>
<h3>Description</h3>
<p>
Collection.next+JSON is a JSON-based read/write hypermedia-type designed to support management and querying of nested data collections. Collection.next+JSON is an extension of <a href="http://amundsen.com/media-types/collection/format/#data-types" title="Collection+JSON - Document Format">Collection+JSON</a> hypermedia format.
</p>
<dl>
<dt>Author:</dt>
<dd>Ioseb Dzmanashvili (<a href="mailto:ioseb.dzmanashvili@gmail.com">ioseb.dzmanashvili@gmail.com</a>)</dd>
<dt>Dates:</dt>
<dd>2012-03-26 (Created)</dd>
<dt>Status:</dt>
<dd class="stable">
application/vnd.collection.next+json (<a class="approved" href="http://www.iana.org/assignments/media-types/application/vnd.collection.next+json">Approved</a>)
</dd>
</dl>
<h3>Contents</h3>
<nav>
<ol>
<li><a href="#general">General Concepts and Goals</a></li>
<li><a href="#objects">Objects</a></li>
<li><a href="#arrays">Arrays</a></li>
<li><a href="#properties">Properties</a></li>
<li><a href="#relations">Link Relations</a></li>
<li><a href="#translating-to-x-www-form-urlencoded">Translating to application/x-www-form-urlencoded</a></li>
<li><a href="#acknowledgements">Acknowledgements</a></li>
<li><a href="#references">References</a></li>
<li><a href="#history">Update History</a></li>
</ol>
</nav>
<blockquote><b>NOTE:</b><br>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
<a href="http://tools.ietf.org/html/rfc2119" title="Key words for use in RFCs to Indicate Requirement Levels">RFC2119</a>.
</blockquote>
<blockquote><b>NOTE:</b><br>The data type names "OBJECT", "ARRAY", "NUMBER", "STRING", and "VALUE" in this document are to be interpreted as described in
<a href="http://amundsen.com/media-types/collection/format/#data-types" title="Collection+JSON - Document Format">Collection+JSON</a> specification.
</blockquote>
</header>
<section id="general">
<h2>1. General Concepts and Goals</h2>
<p>
Section defines general concepts describing all extensions to
<a href="http://amundsen.com/media-types/collection/format/#data-types" title="Collection+JSON - Document Format">Collection+JSON</a> specification.
</p>
<p>
Main goal of this extension is to improve existing capabilities of
<a href="http://amundsen.com/media-types/collection/format/#data-types" title="Collection+JSON - Document Format">Collection+JSON</a>
further and add more power and expressiveness to existing features of specification.
</p>
<p>
Extension introduces several new
<a href="#objects" class="keyword">objects</a>,
<a href="#arrays" class="keyword">arrays</a> and
<a href="#properties" class="keyword">properties</a> and adds more flexibility and semantics to various areas of base specification.
</p>
<p>
When Collection.next+JSON document format is used for implementing APIs <code>application/vnd.collection.next+json</code> MUST be used as a value of the
<a href="http://www.w3.org/Protocols/HTTP/1.1/rfc2616bis/draft-lafon-rfc2616bis-03.html#header.accept">Accept</a> and
<a href="http://www.w3.org/Protocols/HTTP/1.1/rfc2616bis/draft-lafon-rfc2616bis-03.html#header.content-type">Content-Type</a> headers as shown in the examples below:
</p>
<pre><span class="comment">// sample POST request</span>
*** REQUEST ***
POST /my-collection/ HTTP/1.1
Host: www.example.org
<b>Content-Type: application/vnd.collection.next+json</b>
Content-Length: ...
{
"template": {OBJECT}
}
</pre>
<p>OR</p>
<pre><span class="comment">// sample GET request</span>
*** REQUEST *** GET /my-collection/ HTTP/1.1 Host: www.example.org <b>Accept: application/vnd.collection.next+json</b>
</pre>
</section>
<section id="objects">
<h2>2. Objects</h2>
<p>
An object is an unordered collection of zero or more name/value
pairs, where a name is a string and a value is a <code>string</code>, <code>number</code>,
<code>boolean</code>, <code>null</code>, <code>object</code>, or <code>array</code>.
</p>
<p>
Extension defines new set of objects.
They are:
the <a href="#object-list" class="keyword">list</a>,
<a href="#object-status" class="keyword">status</a>,
<a href="#object-method" class="keyword">method</a> and
<a href="#object-enctype" class="keyword">enctype</a>.
</p>
<section id="object-list">
<h3>2.1. list</h3>
<p>
The <a href="#object-list" class="keyword">list</a> object is a child property of the
<a href="http://amundsen.com/media-types/collection/format/#arrays-data">data</a> array elements.
</p>
<p>
The <a href="#object-list" class="keyword">list</a> object MAY contain any of three possible properties:
<a href="#array-options" class="keyword">options</a> (REQUIRED),
<a href="#property-multiple" class="keyword">multiple</a> (OPTIONAL) and
<a href="#property-default" class="keyword">default</a> (OPTIONAL).
</p>
<p>
If the <a href="#object-list" class="keyword">list</a> object is specified and it doesn't contain
the <a href="#property-multiple" class="keyword">multiple</a> property
clients SHOULD only use one of the values provided by
the <a href="#array-options" class="keyword">options</a> array.
</p>
<p>
If the <a href="#object-list" class="keyword">list</a> object is specified and it contains
the <a href="#property-multiple" class="keyword">multiple</a> property which value is specified to <code>true</code>,
clients MAY use any possible combination of multiple values provided by
the <a href="#array-options" class="keyword">options</a> array.
</p>
<section id="query-templates">
<h4>2.1.1 Using the list object with query templates</h4>
<p>
Section describes possible behavior of using the <a href="#object-list" class="keyword">list</a> object within
<a href="http://amundsen.com/media-types/collection/format/#query-templates">query templates</a>.
</p>
<pre><span class="comment">// sample query template with list object</span>
{
"queries": [
{
"href": "http://service.com/my-resource",
"rel": "search",
"prompt": "Enter search string",
<b>"data" : [
{
"name": "gender",
"prompt": "gender",
"list": {
"options": [
{"value": "female", "prompt": "Female"},
{"value": "male", "prompt": "Male"}
]
}
}
]</b>
}
]
}
</pre>
<p>
There are two possible outcomes based on the example above and resulting queries are as follows:
</p>
<ul>
<li>
<p><code>http://service.com/my-resource?gender=female</code></p>
</li>
<li>
<p><code>http://service.com/my-resource?gender=male</code></p>
</li>
</ul>
<p>
If the <a href="#property-multiple" class="keyword">multiple</a>
property present and it's value is specified to <code>true</code> as shown in the following example:
</p>
<pre><span class="comment">// sample query template with list object and multiple property</span>
{
"queries": [
{
"href": "http://service.com/my-resource",
"rel": "search",
"prompt": "Enter search string",
"data" : [
{
"name": "gender",
"prompt": "gender",
"list": {
<b>"multiple": true</b>,
"options": [
{"value": "female", "prompt": "Female"},
{"value": "male", "prompt": "Male"}
]
}
}
]
}
]
}
</pre>
<p>
Possible outcomes of resulting queries would be as follows:
</p>
<ul>
<li>
<p><code>http://service.com/my-resource?gender=male&gender=female</code></p>
</li>
<li>
<p><code>http://service.com/my-resource?gender=female</code></p>
</li>
<li>
<p><code>http://service.com/my-resource?gender=male</code></p>
</li>
</ul>
</section> <!-- /query templates -->
<section id="object-template">
<h4>2.1.1 Using the list object in the template object</h4>
<p>
Section describes possible behavior of using the <a href="#object-list" class="keyword">list</a> object when used with
the <a href="http://amundsen.com/media-types/collection/format/#objects-template">template</a> object.
</p>
<p>
If the <a href="#property-multiple" class="keyword">multiple</a>
property present and it's value is specified to <code>true</code> as shown in following example:
</p>
<pre><span class="comment">// sample template object with list object and type property</span>
{"collection": {
"version": 1.0,
<b>"template": {</b>
"data" : [
{
"name": "interests",
"prompt": "Interests",
"list": {
<b>"multiple": true</b>,
"options": [
{"value": "sports", "prompt": "Sports"},
{"value": "music", "prompt": "Music"}
]
}
}
]
<b>}</b>
}}
</pre>
<p>
Clients MAY submit several combinations of <code>interests</code> input:
</p>
<pre><span class="comment">// sample template object with list object and type property</span>
*** REQUEST ***
POST /my-collection/ HTTP/1.1
Host: www.example.org
Content-Type: application/vnd.collection.next+json
{
"template": {
<b>"data" : [
{"name": "interests", "value": "sports"},
{"name": "interests", "value": "music"}
]</b>
}
}
</pre>
<p>
OR
</p>
<pre><span class="comment">// sample template object with list object and type property</span>
*** REQUEST ***
POST ...
{
"template": {
<b>"data" : [
{"name": "interests", "value": "sports"}
]</b>
}
}
</pre>
<p>
OR
</p>
<pre><span class="comment">// sample template object with list object and type property</span>
*** REQUEST ***
POST ...
{
"template": {
<b>"data" : [
{"name": "interests", "value": "music"}
]</b>
}
}
</pre>
</section> <!-- /template object -->
</section> <!-- /list -->
<section id="object-status">
<h3>2.2. status</h3>
<p>
The <a href="#object-status" class="keyword">status</a> object is an OPTIONAL child property of
the <a href="http://amundsen.com/media-types/collection/format/#objects-collection">collection</a> object.
There MUST NOT be more than one <a href="#object-status" class="keyword">status</a> object in a document. It is a top-level document property
</p>
<p>
The <a href="#object-status" class="keyword">status</a> object MAY contain any of two possible properties:
<a href="http://amundsen.com/media-types/collection/format/#properties-code">code</a> (OPTIONAL),
<a href="http://amundsen.com/media-types/collection/format/#properties-message">message</a> (REQUIRED).
</p>
<p>
The <a href="#object-status" class="keyword">status</a> object's purpose is to fulfill requirements
defined by HTTP <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3">202 Accepted</a> status code.
</p>
<pre><span class="comment">// sample payment data submission request</span>
***REQUEST***
POST /payments HTTP/1.1
Host: service.com
Content-Type: application/vnd.collection.next+json
Content-Length: ...
{
"template": {
<b>"data": [
{"name": "name", "John Doe"},
{"name": "email", "value": "john@doe.com"},
{"name": "creditcard", "value": 41111111111111},
{"name": "cvv2", "value": 123}
]</b>
}
}
</pre>
<pre><span class="comment">// sample payment data submission response</span>
***RESPONSE***
HTTP/1.1 <b>202 Accepted</b>
Location: http://service.com/payments/8888
Content-Type: application/vnd.collection.next+json
Content-Length: ...
{
"collection": {
"version": 1.0
"href": "http://service.com/payments/8888",
<b>"status": {
"code": "inprogress",
"message": "Payment is being processed"
}</b>
}
}
</pre>
</section> <!-- /status -->
<section id="object-method">
<h4>2.3. method</h3>
<p>
The <a href="#object-method" class="keyword">method</a> object represents list of all supported HTTP methods which can be potentially used for manipulating documents. This is an OPTIONAL object and is a child property of of the
<a href="http://amundsen.com/media-types/collection/format/#objects-template">template</a> object.
</p>
<p>
The <a href="#object-method" class="keyword">method</a> object SHOULD have an
<a href="#array-options" class="keyword">options</a> array.
</p>
<pre><span class="comment">// sample method object</span>
{
"template": {
<b>"method": {
"options": [ARRAY]
}</b>,
"data": [ARRAY]
}
}
</pre>
<p>
If the <a href="#object-method" class="keyword">method</a> object presents, it's
<a href="#array-options" class="keyword">options</a> array SHOULD only contain any of
HTTP <code>POST</code>, <code>PUT</code> and <code>PATCH</code>
methods which SHOULD be used by clients for manipulating particular collection
<a href="http://amundsen.com/media-types/collection/format/#arrays-items">items</a>.
</p>
<pre><span class="comment">// sample method object, only POST method is allowed</span>
{
"template": {
"method": {
<b>"options": [
{"value": "POST", "prompt": "Create Entry"}
]</b>
},
"data": [ARRAY]
}
}
</pre>
<p>OR</p>
<pre><span class="comment">// sample method object, PUT and PATCH methods are allowed</span>
{
"template": {
"method": {
<b>"options": [
{"value": "PUT", "prompt": "Replace Entry"}, <span class="comment">// replace entire resource</span>
{"value": "PATCH", "prompt": "Modify Entry"} <span class="comment">// or modify resource partially</span>
]</b>
},
"data": [ARRAY]
}
}
</pre>
<p>OR</p>
<pre><span class="comment">// sample method object, only POST method is allowed</span>
{
"template": {
"method": {
<b>"options": [
{"value": "PATCH", "prompt": "Modify Entry"} <span class="comment">// only partial updates of resource is supported</span>
]</b>
},
"data": [ARRAY]
}
}
</pre>
<p>
Support of HTTP's <code>GET</code> and <code>HEAD</code> methods SHOULD be always assumed by clients.
</p>
</section><!-- /method -->
<section id="object-enctype">
<h3>2.4. enctype</h3>
<p>
The <a href="#object-method" class="keyword">enctype</a> object represents a list of all supported content types other than
<code>application/vnd.collection.next+json</code> which potentially MAY be accepted by server for write requests.
This is an OPTIONAL object and is a child property of of the
<a href="http://amundsen.com/media-types/collection/format/#objects-template">template</a> object.
</p>
<p>
The <a href="#object-enctype" class="keyword">enctype</a> object SHOULD have an
<a href="#array-options" class="keyword">options</a> array.
</p>
<pre><span class="comment">// sample method object</span>
{
"template": {
"method": {
"options": [ARRAY]
},
<b>"enctype": {
"options": [
{"value": "application/x-www-form-urlencoded", "prompt": ""}
]
},</b>
"data": [ARRAY]
}
}
</pre>
<p>
Translation rules to other types MUST be defined by service implementors.
Current specification only defines translation rules for <code>application/x-www-form-urlencoded</code> content type(see. <a href="#translating-to-x-www-form-urlencoded">Translating to application/x-www-form-urlencoded</a>).
</p>
<p>
Despite the provided list of other supported content types, support for <code>application/vnd.collection.next+json</code> format MUST be always assumed by clients and services.
</p>
</section><!-- /enctype -->
</section> <!-- /objects -->
<section>
<h2 id="arrays">3. Arrays</h2>
<p>
An array is an ordered sequence of zero or more values.
</p>
<p>
Extension defines set of new arrays. These are:
<a href="#array-options" class="keyword">options</a> and
<a href="#array-messages" class="keyword">messages</a>.
</p>
<section id="array-options">
<h4>3.1. options</h4>
<p>
The <a href="#array-options" class="keyword">options</a> array MAY be a child property
of the <a href="#object-list" class="keyword">list</a> and <a href="#object-method" class="keyword">method</a> objects.
</p>
<p>
The <a href="#array-options" class="keyword">options</a> array SHOULD contain one or more anonymous objects. Each
object MAY have any of two possible properties:
<a href="http://amundsen.com/media-types/collection/format/#properties-value">value</a> (REQUIRED) and
<a href="http://amundsen.com/media-types/collection/format/#properties-prompt">prompt</a> (OPTIONAL).
</p>
<pre><span class="comment">// sample options array</span>
{
"template": {
"data": [
{"name": STRING, "value": 0, "prompt": STRING, <b>"list:" {
"options": [
{"value": VALUE, "prompt": STRING},
...
{"value": VALUE}
]
}</b>}
]
}
}
</pre>
</section> <!-- /options -->
<section id="array-messages">
<h3>3.2. messages</h3>
<p>
The <a href="#array-messages" class="keyword">messages</a> array is a child property of the
<a href="http://amundsen.com/media-types/collection/format/#objects-error">error</a> object property.
</p>
<p>
The <a href="#array-messages" class="keyword">messages</a> array SHOULD contain one or more anonymous objects. Each
object MAY have any of three possible properties:
<a href="http://amundsen.com/media-types/collection/format/#properties-code">code</a> (OPTIONAL),
<a href="http://amundsen.com/media-types/collection/format/#properties-name">name</a> (OPTIONAL) and
<a href="http://amundsen.com/media-types/collection/format/#properties-message">message</a> (REQUIRED).
</p>
<pre><span class="comment">// sample messages array</span>
"error": {
"code": STRING,
<b>"messages": [
{
"code": STRING,
"name": STRING,
"message": STRING
}
...
{
"name": STRING,
"message": STRING
}
...
{
"message": STRING
}
]</b>
}
</pre>
</section> <!-- /messages -->
</section> <!-- /Arrays -->
<section id="properties">
<section>
<h2>4. Properties</h2>
<p>
Properties represent individual name/value pairs for objects within
<a href="http://amundsen.com/media-types/collection/format/">Collection+JSON</a> documents.
</p>
<p>
Extension introduces several extra properties, these are: the <a href="#property-type" class="keyword">type</a> property
which meaning depends on the enclosing object,
the <a href="#property-multiple" class="keyword">multiple</a>,
the <a href="#property-default" class="keyword">default</a>, and
the <a href="#property-required" class="keyword">required</a>.
</p>
</section>
<section id="property-type">
<h3>4.1. type</h3>
<p>
The <a href="#property-type" class="keyword">type</a> is an OPTIONAL property and MAY be a child property of the
<a href="http://amundsen.com/media-types/collection/format/#arrays-links">links</a> array elements and
the <a href="http://amundsen.com/media-types/collection/format/#arrays-data">data</a> array elements when part of
the <a href="http://amundsen.com/media-types/collection/format/#objects-template">template</a> and
<a href="http://amundsen.com/media-types/collection/format/#arrays-queries">queries</a> array.
</p>
<p>
It SHOULD be a <a href="http://amundsen.com/media-types/collection/format/#type-string">STRING</a> data type.
</p>
<section id="links-type">
<h4>4.1.1. Using type property with links array elements</h4>
<p>
When used with
the <a href="http://amundsen.com/media-types/collection/format/#arrays-links">links</a>
array elements the value SHOULD be a standard MIME type. If the
<a href="#property-type" class="keyword">type</a> property does not appear on a
<a href="http://amundsen.com/media-types/collection/format/#arrays-links">links</a>
array element, it should be assumed to be set to <code>application/vnd.collection.next+json</code>.
</p>
<pre><span class="comment">// sample links array</span>
{
"version": "1.0",
"href": URI,
"items": [
{
"href": URI,
"data": [ARRAY],
<b>"links": [
{"href": URI, "rel": STRING, "prompt": STRING, "type": "image/png"},
{"href": URI, "rel": STRING, "prompt": STRING, "type": "image/jpeg"},
{"href": URI, "rel": STRING, "prompt": STRING, "type": "audio/mpeg3"},
{"href": URI, "rel": STRING, "prompt": STRING, "type": "application/rss+xml"},
...
{"href": URI, "rel": STRING, "prompt": STRING}
]</b>
}
]
}
</pre>
</section> <!-- /using with links -->
<section id="links-data">
<h4>4.1.2. Using type property with data array elements</h4>
<p>
By introducing possibility to explicitly indicate desired data
types for the input objects, extension addresses several important issues:
</p>
<ul>
<li>
<p>
Strengthen semantics of input objects.
</p>
</li>
<li>
<p>
By relying on commonly recognized types protect clients from implementing input processing logic relevant to only particular service format.
</p>
</li>
<li>
<p>Possibility to define agreed validation strategies on both - service and client sides.</p>
</li>
<li>
<p>Reduce communication between service and client by making
<a href="http://amundsen.com/media-types/collection/format/#arrays-data">data</a> array elements
more self contained and self explanatory.</p>
</li>
<li>
<p>Improve interoperability between heterogenous platforms(i.e. statically typed vs dynamically typed languages)
without introducing additional complexity.</p>
</li>
<li>
<p>
By reducing need to describe types of the input objects somewhere else, minimize hardcoding in service clients.
</p>
</li>
<li>
<p>
Improve rendering options in client applications. Client applications MAY determine rendering strategy by relying on
the value of the <a href="#property-type" class="keyword">type</a>
property and use most appropriate input controls in order to increase quality of interaction between application and user.
</p>
</li>
</ul>
<p>
Table below describes supported HTML5 input types which service implementors and clients MAY user in order to describe and determine meaning of the input objects:
</p>
<table border="1">
<thead>
<tr>
<th>Type</th>
<th>State(HTML5)</th>
<th>Data Type(HTML5)</th>
<th>Data Type(Collection+JSON)</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>number</code></td>
<td>
<a href="http://www.w3.org/TR/html5/states-of-the-type-attribute.html#number-state-type-number">
Number
</a>
</td>
<td>A numerical value</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-number">
NUMBER
</a>
</td>
</tr>
<tr>
<td><code>email</code></td>
<td>
<a href="http://www.w3.org/TR/html5/states-of-the-type-attribute.html#e-mail-state-type-email">
E-mail
</a>
</td>
<td>An e-mail address</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-string">
STRING
</a>
</td>
</tr>
<tr>
<td><code>url</code></td>
<td>
<a href="http://www.w3.org/TR/html5/states-of-the-type-attribute.html#url-state-type-url">
URL
</a>
</td>
<td>An absolute URL</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-string">
STRING
</a>
</td>
</tr>
<tr>
<td><code>date</code></td>
<td>
<a href="http://www.w3.org/TR/html5/states-of-the-type-attribute.html#date-state-type-date">
Date
</a>
</td>
<td>A date (year, month, day) with no time zone</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-string">
STRING
</a>
</td>
</tr>
<tr>
<td><code>datetime</code></td>
<td>
<a href="http://www.w3.org/TR/html5/states-of-the-type-attribute.html#date-and-time-state-type-datetime">
Date and Time
</a>
</td>
<td>A date and time (year, month, day, hour, minute, second, fraction of a second)
<br>with the time zone set to UTC</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-string">
STRING
</a>
</td>
</tr>
<tr>
<td><code>month</code></td>
<td>
<a href="http://www.w3.org/TR/html5/states-of-the-type-attribute.html#month-state-type-month">
Month
</a>
</td>
<td>A date consisting of a year and a month with no time zone</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-string">
STRING
</a>
</td>
</tr>
<tr>
<td><code>tel</code></td>
<td>
<a href="http://www.w3.org/TR/html5/states-of-the-type-attribute.html#telephone-state-type-tel">
Telephone
</a>
</td>
<td>Text with no line breaks</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-string">
STRING
</a>
</td>
</tr>
</tbody>
</table>
<p>
Below is the example data array using HTTP5 type attribute values for specifying input object type:
</p>
<pre><span class="comment">// sample usage of type property in the data array</span>
{
"template": {
<b>"data": [
{"name": STRING, "type": "number", "prompt": STRING}, <span class="comment">// NUMBER type</span>
{"name": STRING, "type": "email", "prompt": STRING}, <span class="comment">// email STRING type</span>
{"name": STRING, "type": "url", "prompt": STRING}, <span class="comment">// url STRING type</span>
{"name": STRING, "type": "date", "prompt": STRING}, <span class="comment">// date STRING type</span>
{"name": STRING, "type": "datetime", "prompt": STRING}, <span class="comment">// datetime STRING type</span>
{"name": STRING, "type": "month", "prompt": STRING}, <span class="comment">// month STRING type</span>
{"name": STRING, "type": "tel", "prompt": STRING} <span class="comment">// telephone STRING type</span>
]</b>
}
}
</pre>
<p>
Additionally extension specification defines two explicit data types <code>integer</code> and <code>boolean</code>. Table below summarizes both of these types:
</p>
<table border="1">
<thead>
<tr>
<th>Type</th>
<th>Description</th>
<th>Data Type(Collection+JSON)</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>integer</code></td>
<td>An integer value. When the type is specified any signed integer value SHOULD be used as a value of
the <a href="http://amundsen.com/media-types/collection/format/#properties-value">value</a> property.
</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-number">
NUMBER
</a>
</td>
</tr>
<tr>
<td><code>boolean</code></td>
<td>A boolean value. When the type is specified any of two <code>true</code> or <code>false</code> literal values MUST be used as a value of
the <a href="http://amundsen.com/media-types/collection/format/#properties-value">value</a> property.</td>
<td>
<a href="http://amundsen.com/media-types/collection/format/#type-number">
VALUE
</a>
</td>
</tr>
</tbody>
</table>
<pre><span class="comment">// sample default value usage in the data array</span>
{
"template": {
<b>"data": [
{"name": STRING, "prompt": STRING}, <span class="comment">// no type specified, any VALUE is legal</span>
{"name": STRING, "value": 0, "prompt": STRING, "type": "integer"}, <span class="comment">// integer type</span>
{"name": STRING, "value": false, "prompt": STRING, "type": "boolean"} <span class="comment">// boolean type</span>
]</b>
}
}
</pre>
</section> <!-- /using with data -->
</section>
<section id="property-multiple">
<h3>4.2. multiple</h3>
<p>
The <a href="#property-multiple" class="keyword">multiple</a> is an OPTIONAL property and MAY be a child property of the
<a href="#object-list" class="keyword">list</a> object.
</p>
<p>
It SHOULD be a <code>boolean</code> type and MAY only be specified to boolean <code>true</code> or <code>false</code>.
</p>
<pre><span class="comment">// sample usage of multiple property</span>
{
"queries": [
{
...
"data" : [
{
"name": "gender",
<b>"list": {
"multiple": true,
"options": [
{"value": "female", "prompt": "Female"},
{"value": "male", "prompt": "Male"}
]
}</b>
}
]
}
]
}
</pre>
</section> <!-- /multiple -->
<section id="property-default">
<h3>4.3. default</h3>
<p>
The <a href="#property-default" class="keyword">default</a> is an OPTIONAL property and MAY be a child property of the
<a href="#object-list" class="keyword">list</a> object.
</p>
<p>
It's value SHOULD be specified from one of the <a href="#array-options" class="keyword">options</a> array elements
<a href="http://amundsen.com/media-types/collection/format/#properties-value">value</a> property.
</p>
<pre><span class="comment">// sample usage of default property</span>
{
"queries": [
{
...
"data" : [
{
"name": "gender",
<b>"list": {
"multiple": true,
"default": "female", <span class="comment">// indicates default value</span>
"options": [
{"value": "female", "prompt": "Female"},
{"value": "male", "prompt": "Male"}
]
}</b>
}
]
}
]
}
</pre>
</section>
<section id="property-required">
<h3>4.3. required</h3>
<p>
The <a href="#property-required" class="keyword">required</a> is an OPTIONAL property and MAY be a child property of the
<a href="http://amundsen.com/media-types/collection/format/#arrays-data">data</a> array elements.
</p>
<p>
It SHOULD be a <code>boolean</code> type and MAY only be specified to boolean <code>true</code> or <code>false</code>.
</p>
<pre><span class="comment">// sample usage of the required property in the data array</span>
{
"template": {
"data": [
{"name": STRING, "type": "number", "prompt": STRING, <b>"required": true</b>},
{"name": STRING, "type": "email", "prompt": STRING, <b>"required": true</b>},
{"name": STRING, "type": "url", "prompt": STRING, <b>"required": false</b>},
{"name": STRING, "type": "date", "prompt": STRING},
{"name": STRING, "type": "datetime", "prompt": STRING, <b>"required": true</b>},
{"name": STRING, "type": "month", "prompt": STRING},
{"name": STRING, "type": "tel", "prompt": STRING}
]
}
}
</pre>
</section> <!-- /required -->
</section> <!-- /properties -->
<section id="relations">
<section>
<h2>5. Link Relations</h2>
<p>
Link relations can be used to annotate <a href="http://amundsen.com/media-types/collection/format/#arrays-links">links</a> array elements.
</p>
<p>
Specification defines one new link relation value.
</p>
</section>
<section id="relation-form">
<h3>5.1. form</h3>
<p>
The target IRI points to a resource that is a representation of a valid write form(create or edit) for the data represented by the context IRI.
</p>
<p>
This is a generic relation type and doesn't necessarily refer to the
<a href="http://amundsen.com/media-types/collection/format/#objects-template">template</a> object.
</p>
<p>
When included in a resource which represents a collection, the
<a href="#relation-form" class="keyword">form</a>
link relation identifies a target resource that represents the form
for adding a new member to the context collection.
</p>
<pre><span class="comment">// sample form relation use</span>
<b>GET /news</b> HTTP/1.1
Host: example.org
Accept: application/vnd.collection.next+json
{
"collection": {
"version": 1.0
"href": URI,
"items": [
{OBJECT},
{OBJECT},
...
{OBJECT}
],
"links": [
<b>{
"rel": "form",
"href": URI,
"prompt": "Add new item..."
}</b>
]
}
}
</pre>
<p>
In the example above <code>rel="form"</code> indicates that dereferencing of the URI SHOULD return representation of a valid create form.
In this particular case the <a href="http://amundsen.com/media-types/collection/format/#objects-template">template</a> object.
</p>
<p>
When included in a resource which represents a member of a
collection, the <a href="#relation-form" class="keyword">form</a> link relation identifies a target resource
that represents a pre-populated form for editing the context
resource.
</p>
<p>
When the <code>form</code> relation value is used inside the <a href="http://amundsen.com/media-types/collection/format/#array-items">item</a> object,
dereferencing of the URI SHOULD return the pre-populated valid <a href="http://amundsen.com/media-types/collection/format/#objects-template">template</a> object.
</p>
<pre><span class="comment">// sample form relation use</span>
<b>GET /news/12345</b> HTTP/1.1
Host: example.org
Accept: application/vnd.collection.next+json
{
"collection": {
"version": 1.0
"href": "http://example.org/news",
"items": [
{
"href": "http://example/org/news/12345",
"data": [ARRAY],
"links": [
<b>{
"rel": "form",
"href": "http://example/org/news/12345/edit-form",
"prompt": "Edit item..."
}</b>
]
},
{OBJECT},
...
{OBJECT}
],
}
}
</pre>
<p>
As far as the <code>form</code> relation value is intentionally generic service implementors MAY support various types of forms.
Different types of forms SHOULD be indicated by the <a href="#property-type">type</a> property value in links array elements.
</p>
<pre><span class="comment">// sample form relation use</span>
<b>GET /news</b> HTTP/1.1
Host: example.org
Accept: application/vnd.collection.next+json
{
"collection": {
"version": 1.0
"href": URI,
"items": [ARRAY],
"links": [
<b>{
"rel": "form",
"href": URI,
"type": "application/xhtml+xml",
"prompt": "Add new item..."
}</b>
]
}
}
</pre>
</section>
</section> <!-- /link relations -->
<section id="translating-to-x-www-form-urlencoded">
<h3>6. Translating to application/x-www-form-urlencoded</h4>
<p>
One of the goals of this specification is to define clear ways for translating content for update requests from <code>application/vnd.collection.next+json</code> to other formats.
</p>
<p>
Current specification defines translation rules only for <code>application/vnd.collection.next+json</code> to <code>application/x-www-form-urlencoded</code>.
</p>
<p>
Translation rules to other formats MUST be defined by service implementors.
Supported content types other than <code>application/vnd.collection.next+json</code> SHOULD be provided through <a href="#object-enctype" class="keyword">enctype</a> object.
</p>
<p>
Translation rules to to <code>application/x-www-form-urlencoded</code> are as follows:
</p>
<ul>
<li>
<p><code>null</code> values MUST be converted to empty strings <code>""</code>.</p>
</li>
<li>
<p><code>boolean</code> values MUST be converted to <code>integer</code> <code>0</code> and <code>1</code> correspondingly.</p>
</li>
<li>
<p>Encoding of name/value pairs MUST conform to <a href="http://tools.ietf.org/html/rfc3986">RFC3986</a> and MUST be properly implemented by clients.</p>
</li>
</ul>
<p>
Below is the example implemented in pure JavaScript for translating <a href="#array-data" class="keyword">data</a> array to <code>application/x-www-form-urlencoded</code> format.
</p>
<pre>
/** * encodeURIComponent() function is not 100% compatible with * RFC3986 http://www.faqs.org/rfcs/rfc3986.html */ function</span> encodeRFC3986</span>(value) {
return</span> encodeURIComponent</span>(value) . replace</span>( /!/g</span>, "%21"</span>) . replace</span>( /</span> \*</span> /g</span>, "%2A"</span>) . replace</span>( /</span> \(</span> /g</span>, "%28"</span>) . replace</span>( /</span> \)</span> /g</span>, "%29"</span>) . replace</span>( /'/g</span>, "%27"</span>);
}
function</span> translateToFormUrlEncoded</span>(data) {
var</span> buffer = [];
for</span> </span>( var</span> i = 0</span>; i < data.length; i++) {
var</span> input = data[i];
var</span> name = input.name;
var</span> value = input.value;
if</span> </span>(value === null) { <em> // convert null value to empty string
</span></em> value = ''</span>;
} else</span> if</span> </span>( typeof</span> value === "boolean"</span>) { <em> // convert boolean value to integer 0 or 1
</span></em> value = Number</span>(value);
}
buffer. push</span>( encodeRFC3986</span>(name) + "="</span> + encodeRFC3986</span>(value)); }
return</span> buffer. join</span>( "&"</span>);
}
var</span> data = [
{ "name"</span>: "first-name"</span>, "value"</span>: "John"</span>},
{ "name"</span>: "last-name"</span>, "value"</span>: "Doe"</span>},
{ "name"</span>: "email"</span>, "value"</span>: "john@doe.com"</span>},
{ "name"</span>: "website"</span>, "value"</span>: "http://john.doe.com"</span>},
{ "name"</span>: "age"</span>, "value"</span>: 37</span>},
{ "name"</span>: "interests"</span>, "value"</span>: "music"</span>},
{ "name"</span>: "interests"</span>, "value"</span>: "sports"</span>},
{ "name"</span>: "interests"</span>, "value"</span>: "cars"</span>},
{ "name"</span>: "subscribe"</span>, "value"</span>: false</span>}
];
<em> convert data array to application/x-www-form-urlencoded </span></em> var</span> postData = translateToFormUrlEncoded</span>(data); </div></div> </pre> <pre> encoded contents of resulting postData variable</span> <code> first-name=John&last-name=Doe&email=john%40doe.com&website=http%3A%2F%2Fjohn.doe.com&age=37&interests=music&interests=sports&interests=cars&subscribe=0 </code></pre> </section><!– /translating to form urlencoded –> <section id=“acknowledgements”> <h2>7. Acknowledgements</h2> <p>Special thanks to <a href=“http://amundsen.com/”>Mike Amundsen</a> for insightful advices and permissions to use <a href=“#”>Collections+JSON</a> specification as a reference material.</p> </section> <!– /acknowledgements –> <section> <h2 id=“references”>8. References</h2> <ul> <li><a href=“http://www.w3.org/TR/html5/the-input-element.html”>HTML5 - 4.10.7 The input element</a></li> <li><a href=“http://amundsen.com/media-types/collection/format/”>Collection+JSON - Document Format</a></li> <li><a href=“http://tools.ietf.org/html/rfc2119”>RFC2119 - Key words for use in RFCs to Indicate Requirement Levels</a></li> <li><a href=“http://www.iana.org/assignments/link-relations/link-relations.xml”>IANA Link Relations</a></li> <li><a href=“http://tools.ietf.org/html/rfc5988”>RFC5988 - Web Linking</a></li> <li><a href=“http://tools.ietf.org/html/rfc4627”>RFC2627 - The application/json Media Type for JavaScript Object Notation (JSON)</a></li> <li><a href=“http://tools.ietf.org/html/rfc5789”>RFC5789 - PATCH Method for HTTP</a></li> </ul> </section> <!– /references –> </section> </body> </html>
