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 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:
   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.
   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.

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