Difference between revisions of "rest/json-collections"

From Microformats Wiki
Jump to navigation Jump to search
(First draft)
 
(→‎Fields: Added clarifications; changed "type" to a URI; add array-of-strings possibility for "members" fields.)
 
(2 intermediate revisions by one other user not shown)
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: 
 +
#  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.
 +
# 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.
 +
# 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.
 +
# 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.
 +
# 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:
 +
## A field named '''value''' in a member object is the JSON value that represents the member resource.
 +
## 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.
 +
## 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.
 +
## Other fields may be present in a member object, but their meanings are not defined by this standard.
 +
#  Likewise, other fields may be present in a collection object, but their meanings are not defined by this standard.
 +
#  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.
 +
#  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.
 +
# All URI references are relative to the base of the URI from which the collection was retrieved.
  
This is a trial balloon for a new format, tentatively dubbed "JSON Web
+
== 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.
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.
 

Latest revision as of 20:26, 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 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.