rest/json-collections

JSON Web Collection

This is a trial balloon for a new format, tentatively dubbed "JSON Web Collections", with a MIME-type of application/webcoll+json. Every JSON Web Collection is a JSON text, normally an object, and is interpreted as follows:

1. A field named "href" is a URI reference for retrieving the collection. If absent, the collection cannot be retrieved by standardized means.

2. A field named "id" is a URI reference that identifies the collection. If absent, the collection is ad hoc and has no stable identity. The result from GETting this URI is outside the scope of this standard. Note that two instances of a collection may have the same "id" but different "href" values if the collection is available from more than one URI.

3. A field named "version" is an opaque string that identifies this version of the collection; any changes to the collection require the version to change. It may or may not be derived from a timestamp.

4. A field named "type" is a string representing the media type of the members of this collection. If absent, no type information is available.

5. A field named "members" is an array of objects which represent the resources that are members of the collection. Each object may have "href", "id", "version", and "type" fields specific to that member. In addition:

5a. A field named "value" in a member object is the JSON value that represents the member resource.

5b. A field named "precis" in a member object is a JSON value that is related to, but not necessarily the same as, the value that represents the member resource. It is typically shorter or simpler.

5c. A field named "members" in a member object is an array of member objects, and means that the member is itself a collection with the given members. Note that the type of a member is also a way to specify that it is a collection.

5d. Other fields may be present in a member object, but their meanings are not defined by this standard.

6. Likewise, other fields may be present in a collection object, but their meanings are not defined by this standard.

7. If the collection is an array of objects, then this array is conceptually the value of the "members" field, and all other fields are unavailable.

8. If the collection is an array of strings, then the strings represent the "href" fields of the member objects, and all other fields of both member objects and the collection object itself are unavailable.

General remark: most of this is fairly boilerplate, but the concept of collections that contain collections in a uniform way is new, and means that we don't need separate mechanisms for service documents or magic ways to create new collections. A service document is just an ordinary collection of available collections, and adding a new collection is just POSTing to it. Typically the member objects in a service document would not contain "members" or "value" fields, though they might contain a "precis" field.