Below is my proposal for a RESTful JSON protocol, called JSON resources. This proposal is focused on defining the use of REST architecture for integration with JSON documents, and intends to leverage and build on existing standards, and on existing implementations (and my experience working on them). However, this proposal is not a reverse-engineer or documentation of any existing implementation. Where possible, this proposal uses implementation tested or existing standards based techniques; there are a number of mechanisms in here that are somewhat new, partly due to desires expressed by this group, or by applications of standards that simply have not yet been implemented due to lack of demand so far. This proposal is admittedly quite rough, but hopefully it can serve to put forth some ideas for a RESTful JSON protocol.

I don't believe this proposal is mutually exclusive with John Cowan's proposal for JSON Web Collections. The JSON resources proposal is primarily concerned with semantics of RESTful communication and interaction with JSON data, and generally does not impose any format/structure on the JSON data, however I did include a section on defining a structure for collections that uses a top-level array that is partly based on Cowan's proposal, although this is rather peripheral to main focus of the proposal. Even beyond top-level objects, JSON Web Collections may also be useful as an additional content type as a JSON structure for inclusion of per-resource metadata. This may have value with metadata intensive application, and I think it should work properly with the JSON resources proposal.

http://www.json.com/specifications/json-resources/

JSON Resources Proposal
Abstract
The JSON resources proposal defines how to interoperably use JSON on a REST architecture. JSON resources describes how to meaningfully apply the specifications defined in the HTTP protocol (http://www.ietf.org/rfc/rfc2616.txt) to JSON data, and integrate information from JSON resources into high level interaction. As much as possible, this proposal follows the HTTP specification.

JSON resources does not specify a JSON format, any valid JSON structure can be used with JSON resources. JSON resources does recommend a structure for hyper-referencing objects, but this structure can still be used with any JSON format, and it is not required. The specification assumes the use of the HTTP protocol for RESTful interaction because of it's ubiquity and position as the reference implementation for REST. JSON resources can be used with any REST architectures, but alternate REST architecture bear the responsibility for defining the resource metadata and methods in their own equivalent terms.

Resource Locator Determination
A central function of the JSON resources specification is determining the locator path for JSON resources. When a resource is retrieved through a request, the top-level resource that is returned in the response has an implicit locator, the same locator that was used to retrieve the resource. An alternate canonical locator can be provided by the server with the "Location" header as defined in the HTTP specification.

JSON is hierarchical in nature. A top level JSON entity (object or array) may have objects that can be treated as resources as themselves. In order for these sub-entities to be properly treated as resources, a client must be able to determine the resource's locator path (URL). An object's URL is determined from the object's locator property, treated as a relative URL. To calculate an object's URL, the URL used to retrieve the JSON document is the base URL and the value of the locator property is the relative URL. Then, the absolute URL can be computed based on RFC 1808's specification (http://www.ietf.org/rfc/rfc1808.txt).

A server can declare which property is the locator property for objects in an JSON document with a MIME parameter (MIME parameters are defined in http://tools.ietf.org/html/rfc2045#section-5). Alternate JSON sub-content types (like application/collections+json) may utilize a predefined JSON structure which indicates the locator property. When a MIME parameter is used to define the locator property. The MIME parameter name should be "locator" and the value should be the name of the locator property. For example if the content type of the resource was "application/json" (alternate subtypes are allowed), then the locator property can be declared by suffixing the content type, and the following JSON representation could be sent. If the a request was made to http://site.com/Person/, then the following response could be returned:

Content-Type: application/json;locator=my_id[
 {"my_id":"1","name":"John Doe"},
 {"my_id":"2","name":"Jane Doe"}
]This resource representation would indicate that two subresources have been included. The first subresource has locator (computed by relative URL) of http://site.com/Person/1 and is represented by:

{"my_id":"1","name":"John Doe"}If a request is made to http://site.com/Person/1 with the same headers as the initial response, the server should respond with the representation shown above. If the client wishes to modify the resource it may request the modification by sending a PUT method and the representation of the resource with modifications.

PUT /Person/1

{"my_id":"1","name":"Jim Doe"}If the server permits the operation, the resource should be modified to match the provided representation. New properties that were not in the old version should be added, modified properties should be updated, and properties not listed in the old version should be deleted.

The client may request the deletion of the resource with the DELETE method:

DELETE /Person/1Resource Creation
New resources may be created by using a POST method with a collection resource, or a PUT method with an client defined location. A collection resource is a resource that returns an array of JSON values that represent subresources. To attempt to create a new resource in a collection, a client can make a POST request to the URL for the collection resource with a JSON value indicating the desired properties or values of the resource to be created. For example:

POST /Person/

{"name":"Josh Doe"}This indicates that the client requests a new object be created with a "name" property with the value of "Josh Doe". If successful, the server respond with a response with a status of 201 Created. The response must also include a "Location" header that indicates the location of the newly created resource. For example:

Location: /Person/3If the server does not support creation of resources in this manner, or the operation was unauthorized, the server should respond with the appropriate HTTP response status.

A new resource may alternately be created with the PUT method. With the approach, the client provides the location for which it desires the resource to be accessible from in the future. The desired resource representation should still be included as with a POST method creation except that the client should include the appropriate locator property corresponding to the new resource's location. For example:

PUT /Person/josh

{"my_id":"josh","name":"Josh Doe"}If the operation is successful, the server should respond with a 201 status. The server may include a "Location" header indicating where the resource will be accessible from in the future, however this is not necessary if the client's defined location is acceptable to the server.

Hyper References
A JSON resource may utilize JSON referencing for linking to other resources. A property may utilize a reference to indicate that it's value can be determined by resolving the reference. An array item may also use a reference to indicate it's target value. A JSON reference is a JSON object with a property named "$ref", and a value indicating the location of the resource to be used as the value. The value can be resolved to a URL by relative URL computation in the same manner as the locator property. A client can use the computed URL to retrieve the resource to resolve the reference. For example, if a JSON resource retrieved from http://site.com/Person/1 was represented:

{"my_id":"1","name":"John Doe","spouse":{"$ref":"2"}}This would indicate that the "spouse" property's value is the JSON resource located at http://site.com/Person/2. If both subresources http://site.com/Person/1 and http://site.com/Person/2 were both provided within a single collection:

[
 {"my_id":"1","name":"John Doe","spouse":{"$ref":"2"},
 {"my_id":"2","name":"Jane Doe","spouse":{"$ref":"1"}
]The client would not need to make any additional requests, but would know that the first object's spouse property's referent was the second object and vice versa.

Property Path Based Referencing
References are not limited to self-identified, URL locatable JSON resources. JSON values embedded within the data structures of JSON resources can be referenced by using path-based references. These references include a property path that indicates where the JSON value can be found. A property path is composed of property segments that each refer to the property name to be used to progressively locate a JSON value. A full path-based reference may optionally start with location path (relative URI as with a standard JSON reference) followed by an optional #, followed by path segments. A path segment may be a . followed by a property name,a quoted string enclosed in brackets, or a number enclosed in a bracket. If the reference starts with # instead of object location, the current JSON resource should be considered the starting point for the property reference. For example:

GET /Person/[ {"my_id":"1","name":"John Doe","spouse":{"$ref":"2"},       children:[{"my_id":"3","name":"Jill Doe"}]}, {"my_id":"2","name":"Jane Doe","spouse":{"$ref":"1"}       children:{"$ref":"1#.children"}}]In this example, both "John Doe" and "Jane Doe" refer to the same "children" JSON array. Another example:

{"my_id":"1","foo":[{"bar":3},{"$ref":"#.foo[0]"}]}In this example, the resource indicates that both the first and second entry in the array in the "foo" property, should be the same object (the object {"bar":3}). The grammar for a JSON reference (building on the grammar defined in RFC 2616):

json-reference = "{" <"> "$ref" <"> ":" <"> [relativeURI | absoluteURI] ["#"] *property-segment <"> "}"property-segment = ("." token) | ("[" 1*DIGIT "]") | ("[" single-quoted-string "]")single-quoted-string = "'" *(<any TEXT except "'"> | single-quoted-pair) "'"single-quoted-pair = "\" CHARPartial Loading
A reference object is not limited to only have the "$ref" property. A reference object may include any properties from the target resource object. A reference object can include any property desired from the target resource object. Any properties included in a reference object should have the same value as the target resource object, with the exception that the properties that have a string value may use a truncation of the true value. Reference objects with partial sets of properties can be useful for efficient transfer of relevant information, while allowing clients to request more detailed information as needed. For example, a collection could include references

[
 {"$ref":"1","name":"John Doe"},
 {"$ref":"2","name":"Jane Doe"}
]A client could then provide a list of people's names. A request for more detailed information could be made by making a request to the actual target location , and the target resource object would include a full set of properties (perhaps age, spouse, etc).

A client can request that the objects that are returned from the server only include certain properties using a Range header with "properties" range units. The "properties" range unit defines a set of properties with a comma delimited set of property names as tokens or quoted strings. For example, to request a collection of objects where each object only includes the "name" property:

GET /Person/ HTTP/1.1Range: properties=nameIf the server supports the "properties" range unit, the server should return a response like the example above where each object is a reference object with the properties specified in the Range header.

Permission Indication
A server may indicate the acceptable forms of modification to a given JSON resource by including an "Allow" header. The Allow header value should be a list of allowed methods. PUT indicates that a resource can be updated. DELETE indicates that the resource may be deleted. POST may be included with a collection resource to indicate new resources may be created as a subresources of the collection resource.

When a collection resource is requested, a "X-Sub-Allow" header may also be included that indicates the allowable operations on the sub-resources:

For example, if a server responded to the request for /Person/ with headers:

Allow: GET, HEAD, POST
X-Sub-Allow: GET, HEAD, PUTThis would indicate new resources may be created with the POST method, and sub resources can be updated, but not deleted.

Note that a server should be prepared to handle any method (and possibly reject), as a client may not respect the Allow header.

Permission Setting
When creating a JSON resource with a PUT or POST method, or modifying a JSON resource with a PUT method, the client may wish to indicate the desired permission level of the resource. The client may do this by including an Allow header in the request. The Allow header should indicate permission by including a list of allowed methods. Generally the permission level indicated should be the permission for the general public (someone with special permissions) to access the resource. GET indicates readable, HEAD indicates meta-data is accessible, PUT indicates updateable, DELETE indicates it is deletable, and POST may be used if you have created a new collection resource that can accept new resources within it. For example, creating a new resource that is intended to be publicly readonly could be done with a request:

POST /Person/Allow: HEAD, GET...Paging
A subset of a collection (a JSON resource that is represented as an array) may be requested by using a Range header with the "items" range unit. A Range header can specify the set of array items to be returned by index. The Range header follows the same rules as HTTP RFC 2616 specifies for byte range units, except applied to collection indices.

The returned entity from a Range should be a textual section of the entire JSON array. Consequently, the entity should start with "[" only if the first item in the array is included. It should end with "]" only if the last item is included, otherwise it should end with a ",". This allows Range responses to be properly concatenated by non-JSON aware proxy servers.

The response should also include a Content-Range header indicating the items returned and the total count using the format defined in RFC 2616. For example:

GET /Person/ HTTP/1.1
Range: items=0-1response:
Content-Range: items 0-1/33
[{"$ref":"1","name":"John Doe"},
 {"$ref":"2","name":"Jane Doe"},Servers that can respond to Range requests with the "items" range unit should indicate this capability by including the Accept-Ranges header on responses:

Accept-Ranges: itemsPartial Object Updates
Normally, JSON resouces are updated in whole with a PUT operation. However, a PUT operation can update a subset of the properties of a JSON object using a partial update. To indicate a partial update, the client includes a Content-Range header with a properties range unit. The properties that should be affected by the update should be comma delimited after the "properties" range unit declaration. Properties may be tokens or quoted strings.

PUT /Person/2
Content-Range: properties name,"current age"{"name":"Kristopher",
 "current age",32}If a property is listed in the Content-Range header, but is omitted from the JSON object representation in the entity, this indicates that this property should be deleted.

A server that can handle partial object updates using the "properties" range unit may indicate this capability with the Accept-Ranges header. For example to indicate support for "items" and "properties" range units:

Accept-Ranges: items, propertiesTable and Schema Discovery
The set of available JSON collections or tables can be advertising using Service Method Description (SMD) (http://groups.google.com/group/json-schema/web/service-mapping-descri...). The SMD may include schema information that defines the structure of the objects in the table as defined in JSON Schema (http://json-schema.org). It is recommended that an SMD that lists the available tables should be available at /SMD. The SMD should define a transport of "REST" and a envelope of "PATH". For example:

{
"transport":"REST",
"envelope":"PATH",
"services":{
   "Person" :{
      "type":"object",
      "properties":{
          "name":{"type":"string"},
          "age":{"type":"integer"}
       }
   }
 }

Rational
REST is an architectural approach that should impose no (or minimal) constraints on the actual resource content. JSON Resources can be used with any existing JSON data structure. Integrating into and leveraging REST (via hyperlinking) should be feasible for JSON documents without significant alterations to the data.