Difference between revisions of "rest/json-collections"

From Microformats Wiki
Jump to navigation Jump to search
(First draft)
 
(list-afied)
Line 1: Line 1:
= JSON Web Collection =
+
= 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:
This is a trial balloon for a new format, tentatively dubbed "JSON Web
+
# A field named "href" is a URI reference for retrieving the collection.  If absent, the collection cannot be retrieved by standardized means.  
Collections", with a MIME-type of application/webcoll+json. Every
+
# 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.  
JSON Web Collection is a JSON text, normally an object, and is
+
# 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.  
interpreted as follows:
+
# A field named "type" is a string representing the media type of the members of this collection.  If absent, no type information is available.  
 
+
# 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 "href" is a URI reference for retrieving the
+
## A field named "value" in a member object is the JSON value that represents the member resource.  
collection.  If absent, the collection cannot be retrieved by
+
## 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.  
standardized means.
+
## 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.  
 
+
## Other fields may be present in a member object, but their meanings are not defined by this standard.  
2. A field named "id" is a URI reference that identifies the
+
# Likewise, other fields may be present in a collection object, but their meanings are not defined by this standard.  
collection.  If absent, the collection is ad hoc and has no stable
+
# 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.  
identity. The result from GETting this URI is outside the scope of
+
# 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.
this standard.  Note that two instances of a collection may have the
+
== 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.
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.
 

Revision as of 18:58, 27 August 2008

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