Previous Page Arrow Next Page Arrow

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.xSData 2.0 ATOMSData 2.0 JSONNotest
idMUSTMUSTNOIn JSON, this information is carried by the $url object (see below)
titleMUSTMUSTMAYJust as a matter of good practice, encourage people to fill this
updatedMUSTMUSTMAYMeaningful 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.
authorSHOULDMAYNOA relaxation to the 1.x standard
summaryMAYMAYNOTo be specified only if value can be derived from the element
categorySHOULDNONOThis is a candidate for deprecation
xml:baseNOSHOULDNOAllows specification of relative URLs, thus greatly reducing the size of the payloads (see [XMLbase specification](http://www.w3.org/TR/xmlbase/#XMLNS))
$resourcesNONOMUSTThe JSON object that envelopes individual resources
$baseUrlNONOMAYThe JSON pendant to the xml:base attribute
$urlNONOMAYThe JSON pendant to the ID and Self ATOM links
$linksNONOMAYThe JSON object encompassing the link elements of a feed
$diagnosisNONOMAYThe JSON pendant to the ATOM diagnosis element (see: sdata.xsd and 3.10 Error Payload)

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.xSData 2.0Notes
selfMUSTMAYIt 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
firstMAYMAYOnly in conjunction with a paged feed
next''''''
prev''''''
last''''''
schemaMUST (XML)MAYPoints to schema location of a resource kind
templateMAYMAYPoints to template of a resource kind
postMAYMAYPoints to location of POST operation for a resource kind
queriesMAYMAYPoints to location of relevant queries of a resource kind
serviceMAYMAYPoints to location of relevant services of a resource kind
batchMAYMAYPoints 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:

ElementSData 1.xSData 2.0 ATOMSData 2.0 JsonNotes
idMUSTMUSTNO$url is the JSON counterpart
titleMUSTMUSTMAY
updatedMUSTMUSTMAYThis is an alternate version recognition mechanism to the etag.
authorSHOULDMAYMAY
summaryMAYMAYMAY
categorySHOULDNONOThis is a deprecation candidate
contentSHOULDMAYNO
payloadMUSTMUSTNO
etagMAYMAYMAY
$urlNONOMAY$url points to the entry. It is the JSON counterpart to the ATOM ID.
$keyNONOMAY$key contains the value of the primary key of an entry. It is the JSON representation of the propertylevel attribute key
$propertiesNONOMAYContainer for metadata associated with the entry
$linksNONOMAYObject containing links that present functional aspects of the resource (example: edit, lookup, create). They are to be understood as hypermedia controls
$diagnosisNONOMAYThe JSON pendant to the ATOM diagnoses element (see: sdata.xsd and 3.10 Error Payload)

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 nameJSON nameJSON Value type
key$keyString
url$urlString
uuid$uuidString
lookup$lookupString (is a link located in the $links object)
descriptor$titleString
isDeleted$isDeletedBoolean
deleteMissing$deleteMissingBoolean
index$indexReserved

3. These elements are hardly any use to us in practical terms

Previous Page Arrow Next Page Arrow