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.

Fields

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 a representation (normally this same representation, possibly updated) of the collection. If absent, the collection cannot be retrieved by standardized means. When the collection is transmitted by HTTP, this would normally be the same as the content of the "Location" or "Content-Location" header.
2. A field named id is a URI reference that gives the collection a name, distinguishing it from all other collections. 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. When the collection is transmitted via HTTP, this would normally be the same as the content of the ETag header.
4. A field named type is a URI representing the type (in some generalized sense) of the members of this collection. If absent, no type information is available. This is intended for use when all members have the same type. Providing this field allows consumers of the collection to avoid processing members they do not understand.
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. If the field contains an array of strings rather than an array of objects, the strings are conceptually the href fields, and no other member-object fields are available. In addition:
   1. A field named value in a member object is the JSON value that represents the member resource.
   2. 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.
   3. 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. Like the collection field "member", this field may also be an array of strings, with the same interpretation.
   4. 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.
9. All URI references are relative to the base of the URI from which the collection was retrieved.

== Remarks == 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.