JSON responses

Provider responses to requests in (and for) JSON are in one of the following forms:

An entry: this is the representation of an individual resource and contains the native, JSON formatted objects
A feed: is a collection of entries
A diagnosis : returned in case something went wrong with the request
A tracking object: returned for an asynchronous call to enable subsequent polling of results

JSON entries

Entries encompass single resources such as a specific Customer or SalesOrder. Payloads will contain a single entry only when the request operates target an individual resource (ex: GET on a single resource URL or PUT/POST/DELETE operations).

In addition to the native properties of the resource, SData allows within an entry the presence of several protocol-defined properties meant to ease consumption. These are described in the table below:

	Description	Compliance
$url	URL pointing to the resource. The URL should be represented as relative to the value of the $baseUrl of the enclosing feed. Examples: given the "$baseUrl": "http://ex.com/MyApp/-/-" "$url": "{$baseUrl}/customers('1234')" "$url": "{$baseUrl}/customers?where=$uuid eq 'ab1C43sd-c1asdc2sT'" If a $baseUrl property is not specified, then the URL MUST be absolute. Examples: "$url": "http://ex.com/MyApp/-/-/customers('1234')" "$url": "http://ex.com/MyApp/-/-/customers?where=$uuid eq 'ab1C43sd-c1asd-c2sT'"	MAY
$key	the native primary key identifying the resource	MAY
$uuid	UUID identifying the resource	MAY
$title	humanly readable description of the resource	MAY
$updated	the time stamp of the last update of the resource, formatted according to ISO 8601 dateTime specification	MAY
$etag	opaque identifier assigned by the provider to a version of a resource	MAY
$properties¹	Object containing metadata for the properties of the resource	MAY
$links²	Object containing links that present functional aspects of the resource (ex: edit, lookup, create). They are to be understood as hypermedia controls	MAY
$diagnosis	Object containing a more detailed indication of errors and warnings encountered by the provider during the execution of a request	MAY
native properties	Native properties of the object	MAY

An example is the JSON variant of the Typical SData Entry in the SData documentation:

…
"$baseUrl": "http://www.acme.com/MyApp/-/-",
…
{ 
    "$url": "{$baseUrl}/salesOrders('43660')", 
    "$updated": "2008-03-31T13:46:45Z", 
    "$key": "43660", 
    "$title": "Sales Order 43660", 
    "$etag": "gJaGtgHyuAwW6jMI4i0njA==", 
    "orderDate": "2001-07-01", 
    "shipDate": null, 
    "contact": { 
        "$url": "contacts('216')", 
        "$key": "216" 
    }, 
    "subTotal": 1553.10 
}

JSON feeds

Feeds are collections of entries, returned by operations targeting several resources in parallel such as read or query operations on resource kinds. A feed is a JSON object with all entries contained in the $resources array - this is the only required property of a feed.

A feed may also contain a set of SData-defined properties, which are described in the table below:

	Description	Compliance
$resources	Array containing the individual entries	MUST
$baseUrl	URL leading to the resource kind level of an application. The URL SHOULD NOT end in a "/" Example: "$baseUrl": "http://www.acme.com/MyApp/MyContract/-"	MAY
$url	URL pointing to the resources returned. The URL should be represented as relative to the $baseUrl value. Examples: "$url": "{$baseUrl}/customers" "$url": "{$baseUrl}/customers?where=name ge 'm'" If a $baseUrl property is not specified, then the URL MUST be absolute. Examples: "$url": "http://ex.com/MyApp/-/-/customers" "$url": "http://ex.com/MyApp/-/-/customers?where=name ge 'm'"	MAY
$title	humanly readable description of the resource	MAY
$updated	the time stamp of the last update of the resource, formatted according to ISO 8601 dateTime specification	MAY
$links³	Object containing links that present functional aspects of the feed (ex: refresh, first-page, schema, template, …). They are to be understood as hypermedia controls	MAY
$diagnosis	Object containing a more detailed indication of errors and warnings encountered by the provider during the execution of a request	MAY

An example is the JSON variant of the SData Typical Feed :

{ 
    "$baseUrl": "https://www.example.com/MyApp/-/-",
    "$url": "{$baseUrl}/salesOrders", 
    "$title": "Sage App | Sales Orders", 
    "$totalResults": 31465, 
    "$startIndex": 1, 
    "$itemsPerPage": 10, 
    "$resources": [
        { 
            "$updated": "2008-03-31T13:46:45Z", 
            "$key": "43660", 
            "$title": "Sales Order 43660", 
            "$etag": "gJaGtgHyuAwW6jMI4i0njA==", 
            "orderDate": "2001-07-01", 
            "shipDate": null, 
            "contact": {
                "$url": "contacts('216')", 
                "$key": "216" 
            },
            "subTotal": 1553.10 
        },
        { 
            "$updated": "2008-03-31T13:46:45Z", 
            "$key": "43661", 
            "$title": "Sales Order 43660", 
            "$etag": "3nqPeQqoGoxQB5xf3NIijw==", 
            "orderDate": "2001-07-01", 
            "shipDate": null, 
            "contact": { 
                "$url": "contacts('281')", 
                "$key": "281" 
            }, 
            "subTotal": 39422.12 
        } 
    ] 
}

JSON diagnosis

The diagnoses is an object that contains information about the status (information, warning, error) of a request’s execution. Such an object MUST be present in a response if errors were encountered during the execution. The xml format of diagnosis is described in the SData protocol in the 3.10: Error payload section.
The JSON format of the diagnosis objects supports the following properties:

	Description	Compliance
$severity	Severity of the diagnosis entry. Possible values are: Info Warning Transient Error Fatal	MUST
$sdataCode	The SData diagnosis code	MUST
$applicationCode	Application specific diagnosis code	MAY
$message	Friendly message for the diagnosis	SHOULD
$stackTrace	Stack trace - to be used with care	MAY
$payloadPath	XPath expression that refers to the payload element responsible for the error	MAY

An example of a diagnoses JSON object is shown below:

{
    "$diagnoses": [
        { 
            "$severity": "error", 
            "$sdataCode": "BadWhereSyntax", 
            "$message": "Invalid query syntax",
            "$applicationCode": "2403"
        } 
    ] 
}

JSON tracking

The tracking object MUST be returned by a provider in response of an asynchronous operation. SData describes a set of properties that can be provided in a tracking object. For JSON, these are:

	Description	Compliance
$phase	End user message describing the current phase of the operation.	MAY
$phaseDetail	Detailed message for the progress within the current phase.	MAY
$progress	Percentage of operation completed.	MAY
$elapsedSeconds	Time elapsed since operation started, in seconds.	MUST
$remainingSeconds	Expected remaining time, in seconds.	MAY
$pollingMillis	Delay (in milliseconds) that the consumer should use before polling the service again.	MUST

An example of a tracking JSON object is shown below:

{
    "$tracking": {
        "$phase": "Archiving FY 2007", 
        "$phaseDetail": "Compressing file archive.dat", 
        "$progress": 12.0, 
        "$elapsedSeconds": 95, 
        "$remainingSeconds": 568, 
        "$pollingMillis": 500 
    } 
}

1. will be described in detail in another paper on JSON metadata and its usage.
2. will be described in detail in another paper on JSON metadata and its usage.
3. will be described in detail in another paper on JSON metadata and its usage.