Draft Specification Overview

Internet-Draft currently under development

As the first step in the RFC publication process, a SOAPjr Internet-Draft is currently being developed and will be made available for comment soon.

Introduction

SOAPjr messages are simple JSON data structures specifically designed to be sent over HTTP (or HTTPS/TLS).

A SOAPjr request message consists of the HTTP request "envelope", a parameter named "json" which contains the bulk of the message itself and then other related parameters. A response message generally contains the JSON data structure directly inline (e.g. no named parameter "json").

In a request the "envelope" defines content encoding type (e.g. application/x-www-urlencoded, application/json or multipart/form-data), the response content types accepted and all the other usual HTTP headers.

In a request the "json" parameter contains the MOBject ( MIME-like Object e.g. {"HEAD":{},"BODY":{}} ) style JSON data structure that represents the SOAPjr message itself. There may only be one of these per request.

In a request an optional "json_type" parameter can contain a URL which returns a JSON data structure of the rules for parsing the contents of the "json" parameters content (e.g. the top level is an object or specific type of ordered list, requires relaxed mode, uses single quotes, etc.). "json_type" may also optionally contain the parser rules JSON data structure inline.

In a response the content of the HTTP response may either contain a MOBject style ( {"HEAD":{},"BODY":{}} ) JSON data structure directly inline, or optionally may include any other type of correctly encoded Content-Type as per the HTTP specification.

JSON-Schema definitions

The following SOAPjr entities are defined as JSON-Schemas.

The latest versions are available from the http://SOAPjr.org/schemas/ directory or can also be downloaded in a single file

Example SOAPjr REQUEST message

ENVELOPE
json=
HEAD
BODY
RELATED

Example SOAPjr RESPONSE message

ENVELOPE
HEAD
BODY

ENVELOPE

In a request this consists of the standard HTTP request headers including Content-Type, Accept, Request-Method (e.g. GET, POST or PUT), Charset, Language, HTTP protocol, etc.

In a response this consists of the standard HTTP response headers including Set-Cookie, etc.

HEAD

Request

"service_type" is a mandatory named value that represents the Service or Object type (e.g. a noun) that this SOAPjr message describes.

"action_type" is a mandatory named value that represents the Action or Method/Procedure/Function (e.g. a verb) that this SOAPjr message describes.

"dmd" is an optional named value that contains a URL which returns a data model definition that the "json" contents "BODY" element is intended to conform to. The "dmd" concept is similar to the "dtd" concept from XML and is designed to enable the proliferation of shared data models targeted at specific domains. If not specified a default "dmd" is implied.

NOTE: SOAPjr.org aims to contribute to the creation of a common set of DMD's (Data Model Definitions) that may align with the JSON-Schema Proposal and Service Mapping Description Proposal. This is designed to allow applications within specific domains to more easily share data. The primary extension that SOAPjr may provide here is the addition of the ability to define consistent or standardised error codes. Other resources that may inform this development are common data models utilised within microformats and RDF.

"sid" is an optional named value that contains a session ID for use in authenticating and authorising this message/request.

Response

"result" is a mandatory named value that represents a binary representation of whether the SOAPjr request was successful or not. This is quite clearly distinct from the HTTP codes (e.g. 200, 500, etc.) that represent the status of the transport or HTTP request itself. The "result" parameter is designed to make the error handling of the SOAPjr request itself more robust.

"dmd" is an optional named value that contains a URL which returns a data model definition that the responses "BODY" or "error" elements are intended to conform to. If not specified the default "dmd" is implied (TBD).

"errors" is an optional named value that may only be present if "result" is set to 0 or false (e.g. the SOAPjr request was unsuccessful). This contains a JSON object based data structure that represents a collection of any error information related to the failure of the SOAPjr request. At it's top level it contains the standard MOBject style ( {"HEAD":{},"BODY":{}} ) data structure. Within either the "HEAD" or "BODY" are then named values that match the elements supplied in the initial SOAPjr request. Each of these named values that can contain the following two named values.

"code" which is a specific numeric code as defined in the "dmd". If no "dmd" is specified then the default "dmd" is implied (TBD).

"message" which contains a human readable string representation of the error for this specific MOBject named value.

BODY

This is the real payload of the SOAP-js message. This is can be anything from a null string through to a very rich nested data structure. This structure and it's relationship to the metadata in the "HEAD" element define your API.

RELATED

This is any of the other key/value parameters included alongside the "json" parameter. These are all optional and can represent anything from related external values (e.g. out of band signalling) or attached files being uploaded. In order to support attached/uploaded files the Content-Type must be set to "multipart/form-data".

However these fields (with the exception of the optional "json_type" are only truly "RELATED" if they are refered to by elements within the "json" data structure. Otherwise they are simply parameters that just happen to be sent along with the SOAPjr request and will be ignored leaving them to be processed separately.

Examples

Here are some simple example messages to show the type of JSON data structures used in SOAPjr messages.

SOAPjr Request Message Structure - View a Contact

This is a basic request to view the jCard details for a single user (based on their username). This message would be passed in a request within the "json" parameter e.g.
?json={"HEAD":{"service_type":"contacts","action_type":"view",
"sid":"80e5b8a8b9cbf3a79fe8d624628a0fe5"},"BODY":{"username":"jbloggs"}}
Of course this would be supplied with the relevant encoding.

NOTE: A jCard dmd is yet to be created - once available this should also be defined in the request HEAD.
{
    "HEAD" : {
        "service_type" : "contacts",
        "action_type" : "view",
        "sid" : "80e5b8a8b9cbf3a79fe8d624628a0fe5"
    },
    "BODY" : {
	    "username" : "jbloggs"
    }
}

SOAPjr Response Message Structure - View a Contact (No errors)

This is a simple SOAPjr response with a HEAD.result that represents a success. The BODY contains a single jCard record. In a list "list" or "search" context this would contain an array of 0 or more jCard records.
{
    "HEAD" : {
        "result" : 1
    },
    "BODY" : {
        "email" : [
            {
                "type" : ["internet","pref"],
                "value" : "jbloggs@SOAPjr.org"
            }
        ],
        "fn" : "Joe Bloggs",
        "kind" : "individual",
        "n" : {
            "family-name" : ["Bloggs"],
            "given-name" : ["Joe"],
            "value" : "Bloggs;Joe"
        },
        "org" : [
            {
                "organization-name" : "SOAPjr.org"
            }
        ]
    }
}

SOAPjr Response Message Structure - View a Contact (Invalid SID)

This SOAPjr response shows that an invalid Session ID was supplied. If HEAD.result does not equal 1 then there was an error. In that case you can walk HEAD.errors and retrieve and process as many errors as have been returned. Each element within the request object can then have a specified error code and message allowing for more robust and sophisticated error handling.
{
    "HEAD" : {
        "result" : 0,
        "errors" : {
            "HEAD" : {
                "sid" : {
                    "code" : "401",
                    "message" : "Invalid Session ID"
                }
            }
        }
    }
}

References

Latest News

New demonstration SOAPjr site added

Sep 27th 2009

A new site has been added to the demonstration section that shows a live working example of SOAPjr services - see http://SOAPjr.org/demos.html

File upload (related API) added to SOAPjr jquery plugin

Mar 25th 2009

A new version of the jquery plugin that support file uploads using the "related API" has been released. Version 1.3.0 of the SOAPjr jQuery plugin is available on the jQuery plugin site.

File upload (related API) added to SOAPjr CPAN module

Mar 25th 2009

A new version of the perl libs that support file uploads using the "related API" have been uploaded to CPAN. Thanks for the update Sean.

Redhat claim patent on SOAP over CGI

Mar 20th 2009

In 2007 Redhat lodged a patent on SOAP processing over CGI. Yet another great reason to migrate to SOAPjr which uses lightweight JSON instead of XML.

jQuery plugin bug fixes released

Dec 18th 2008

A variety of small bug fixes and tidy ups have been released (see revision history for more details). Version 1.1.2 of the SOAPjr jQuery plugin is available on the jQuery plugin site.

New jQuery plugin API

Dec 12th 2008

Now you can make SOAPjr calls with a single line, configure default settings or automatically validate the "send" or "receive" data against JSON Schemas. Version 1.1.0 of the SOAPjr jQuery plugin is available on the jQuery plugin site.

Creative Commons License
SOAPjr.org by SOAPjr.org is licensed under a Creative Commons Attribution-Share Alike 2.5 Australia License.
Based on a work at SOAPjr.org.