SData payload elements
The structure SData content is aligned with the ATOM specification, according to the initial direction we took. ATOM divides the payload in three levels (a division maintained in the JSON format):
- The feed: envelops a set of resources
- An entry: envelops a single resource
- A property: is an individual information carrier in the context of a resource
The following sub-sections present the upcoming SData 2.0 changes for each level.
Feed level
The following subsections discuss feed-level aspects of the SData 2.0 standard, namely:
- Namespaces
- Protocol-defined elements
- Links
- Categories
Namespaces
Namespaces are relevant only for the atom+xml format. The table below shows namespaces and their compliance level for SData 2.0:
| Namespace | Compliance level |
|---|---|
| Http | MUST |
| Atom | MUST |
| SData | MUST |
| Xsi | MAY (meaningful only when schemas are involved) |
| Opensearch | MAY; meaningful only when paging is implemented |
| Sle | MAY; meaningful in a very reduced number of cases |
Non-essential namespaces (sle, xsi, and others) should be used as dictated by the individual necessities of a scenario.
Protocol-defined elements
SData 2.0 recognizes two payload formats: atom+xml and json.
ATOM elements³ are dictated by the ATOM specification and SData, being ATOM conformant, MUST require the presence of these elements in the atom+xml format. As only moderate benefits are derived in the SData from ATOM elements, the support is kept at a minimum . The SData 1.x definitions are found in section 3.2 Feed Elements.
In the JSON format, not being attached to a standard, SData keeps a free hand. Most of the ATOM elements deemed meaningful for JSON maintain similar names - these are preceded by a $ (example: title in atom becomes $title in JSON).
The following table presents the SData 2.0 feed-level elements:
| Sdata 1.x | SData 2.0 ATOM | SData 2.0 JSON | Notest | |
|---|---|---|---|---|
| id | MUST | MUST | NO | In JSON, this information is carried by the $url object (see below) |
| title | MUST | MUST | MAY | Just as a matter of good practice, encourage people to fill this |
| updated | MUST | MUST | MAY | Meaningful for syndication context but with little value for SData. In practice, we will not compute on every GET the updated value for the whole feed. |
| author | SHOULD | MAY | NO | A relaxation to the 1.x standard |
| summary | MAY | MAY | NO | To be specified only if value can be derived from the element |
| category | SHOULD | NO | NO | This is a candidate for deprecation |
| xml:base | NO | SHOULD | NO | Allows specification of relative URLs, thus greatly reducing the size of the payloads (see [XMLbase specification](http://www.w3.org/TR/xmlbase/#XMLNS)) |
| $resources | NO | NO | MUST | The JSON object that envelopes individual resources |
| $baseUrl | NO | NO | MAY | The JSON pendant to the xml:base attribute |
| $url | NO | NO | MAY | The JSON pendant to the ID and Self ATOM links |
| $links | NO | NO | MAY | The JSON object encompassing the link elements of a feed |
| $diagnosis | NO | NO | MAY | The JSON pendant to the ATOM diagnosis element (see: sdata.xsd and 3.10 Error Payload) |
Links
Links are used to point to resources (data, services, etc.) related to an object. In the atom+xml format, links have a standardized format (see section 4.2.7 of the ATOM syndication format). In JSON, links are represented as sub-objects of the $links object mentioned previously.
In the SData 2.0 specification of any specific link is optional. Specific links may be required by a contract, the standard however does not impose any such requirements.
SData 2.0 recommends that the URL components of a link object (with the exception of the ATOM id element) be defined relatively. This is achieved by using:
- the xml:base attribute in the atom+xml format
- the $baseUrl name-value pair in JSON
The names of links are not standardized in the 1.x version of the SData standard. Although no standardization effort is undertaken by the SData 2.0 version, it is recommended that the IANA Link relations be consulted prior to defining a new link name. The following is a list of links as they emerged in examples of the 1.x version and their handling in the 2.0 version:
| SData 1.x | SData 2.0 | Notes | |
|---|---|---|---|
| self | MUST | MAY | It seems a little odd to include this at all as it is the same almost always identical to the ATOM ID element. However, existing implementations may rely upon its presence |
| first | MAY | MAY | Only in conjunction with a paged feed |
| next | '' | '' | '' |
| prev | '' | '' | '' |
| last | '' | '' | '' |
| schema | MUST (XML) | MAY | Points to schema location of a resource kind |
| template | MAY | MAY | Points to template of a resource kind |
| post | MAY | MAY | Points to location of POST operation for a resource kind |
| queries | MAY | MAY | Points to location of relevant queries of a resource kind |
| service | MAY | MAY | Points to location of relevant services of a resource kind |
| batch | MAY | MAY | Points to location of relevant batching services of a resource kind |
Categories
The Categories feature is a candidate for deprecation. Anyone with reasons to request support for this feature in SData 2.0 should do so on the corresponding Open team.
Entry level
The following subsections discuss Entry-level aspects of the SData 2.0 standard, namely:
Protocol-defined elements
As mentioned in the corresponding section of the Feed Level chapter, for the atom+xml format the existence and nature of protocol defined elements results from the ATOM syndication definition.
In the JSON format the ATOM element names are prefixed by a $ (example: author becomes $author). Additionally, as JSON had no attributes support, these are represented by objects or name-value pairs (see for example $key in the table).
The corresponding SData 1.x definitions are found in section 3.7 Typical Feed Entry. The following table presents the SData 2.0 entry-level elements:
| Element | SData 1.x | SData 2.0 ATOM | SData 2.0 Json | Notes |
|---|---|---|---|---|
| id | MUST | MUST | NO | $url is the JSON counterpart |
| title | MUST | MUST | MAY | |
| updated | MUST | MUST | MAY | This is an alternate version recognition mechanism to the etag. |
| author | SHOULD | MAY | MAY | |
| summary | MAY | MAY | MAY | |
| category | SHOULD | NO | NO | This is a deprecation candidate |
| content | SHOULD | MAY | NO | |
| payload | MUST | MUST | NO | |
| etag | MAY | MAY | MAY | |
| $url | NO | NO | MAY | $url points to the entry. It is the JSON counterpart to the ATOM ID. |
| $key | NO | NO | MAY | $key contains the value of the primary key of an entry. It is the JSON representation of the propertylevel attribute key |
| $properties | NO | NO | MAY | Container for metadata associated with the entry |
| $links | NO | NO | MAY | Object containing links that present functional aspects of the resource (example: edit, lookup, create). They are to be understood as hypermedia controls |
| $diagnosis | NO | NO | MAY | The JSON pendant to the ATOM diagnoses element (see: sdata.xsd and 3.10 Error Payload) |
Links
In the SData 2.0 specification of any specific link is optional.
The discussion on feed-level links holds true for entry-level links as well. A more comprehensive standardization on links is currently under consideration.
Property level
There are several xml attributes defined in the sdata.xsd document that may annotate a resource’s properties; these remain valid in SData 2.0.
As JSON has no comparable mechanism, xml attributes are represented in JSON as name/value pairs:
| atom-xml attribute name | JSON name | JSON Value type |
|---|---|---|
| key | $key | String |
| url | $url | String |
| uuid | $uuid | String |
| lookup | $lookup | String (is a link located in the $links object) |
| descriptor | $title | String |
| isDeleted | $isDeleted | Boolean |
| deleteMissing | $deleteMissing | Boolean |
| index | $index | Reserved |
3. These elements are hardly any use to us in practical terms