SData Specification

Previous Page Arrow Next Page Arrow

SData JSON Types

The type of an SData JSON property or object is defined by its associated $type property. The possible values of the $type property follow the MIME type formalism; the process of registering the “sdata/” prefix with the Internet Assigned Numbers Authority (IANA) is underway. The types are presented in the following sub-sections, divided into basic and complex types.

The approach of defining explicit SData basic types for date, time and datetime (rather than representing these types as SData string types with associated formats) was taken in the interests of familiarity to application designers and programmers.

Basic types

sdata/boolean

The sdata/boolean type conforms to the JSON Boolean type with values that can be either true or false.

sdata/string

The sdata/string type conforms to the JSON string type.

An sdata/string type specification can be complemented through an additional format definition. This defines an underlying pattern for the string. The following $format specifications are defined:

  • email: the string MUST consist of an email address conforming to RFC 5322, “Internet Message Format” [4].
  • currency: the string MUST consist of an alphabetic 3 letter code conforming to ISO 4217, “Codes for the representation of currencies and funds” [5].
  • locale: the string MUST conform to the format specified in the HTTP Accept-Language header and detailed in the language tags specification of section 3.10 of RFC 2616, “Hypertext Transfer Protocol - HTTP/1.1” [6].
  • country: the string must consist of an alphabetic 2 letter code conforming to ISO 3166-1, “Codes for the representation of names of countries and their subdivisions” [7].
  • phone: the string SHOULD consist of a valid dialling sequence. Due to the lack of a widely accepted standard, no specific recommendation is made on conformance, but restriction of characters to “‘0’..’9’, ‘+’, ‘-‘, ‘ ‘, ‘.’, ‘(‘, ‘)’” (i.e., numbers, the plus sign conventionally used to indicate a nationally defined prefix for International Direct Dialling, and the dash, space, period and brackets commonly used to separate and group elements of a dialling sequence) is encouraged to aid interoperability.

Other formats can be defined as deemed necessary through contracts.

Example: Some properties of a fictional Contact resource could be expressed as follows:

{
    "..." : "...",
    "countryOfResidence" : {
        "$type" : "sdata/string",
        "$format" : "country"
    }, 
    "preferredCurrency" : {
        "$type" : "sdata/string",
        "$format" : "currency"
    },
    "displayLanguage" : {
        "$type" : "sdata/string",
        "$format" : "locale"
    },
    "emailAddress" : {
        "$type" : "sdata/string",
        "$format" : "email"
    },
    "telephone" : {
        "$type" : "sdata/string",
        "$format" : "phone"
    }
}

The payload for a resource conforming to this definition could look like:

{
    "..." : "...",
    "countryOfResidence" : "GB", 
    "preferredCurrency" : "GBP",
    "displayLanguage" : "en-GB",
    "emailAddress" : "john.doe@example.org", 
    "telephone" : "+44 191 294 3000"
}

sdata/number

The sdata/number type is equivalent to the JSON number type. Both specifications can be used in an SData context.

Example:

  • “avogadroConstant”: 6.0221413e+23

sdata/integer

An sdata/integer property contains a (possibly signed) integer value.

Examples:

  • “kilo”: 1024
  • “minusOne”: -1

sdata/decimal

The sdata/decimal type is a string representing a (possibly signed) rational number with a finite number of decimal places. The decimal point is a period. The string type is necessary since some languages, such as JavaScript, have difficulties in representing decimal numbers (for example, 0.1 + 0.2 === 0.3 is false in JavaScript).

The metadata elements $totalDigits and $fractionDigits allow a more precise description if it is required.

Example:

  • “exchangeRate”: “1.2990”

sdata/date

The sdata/date type is a string representing a date. The format of the contents MUST correspond to the “YYYY-MM-DD” representation as defined in the ISO8601 specification [8].

Example:

  • “creationDate”: “2014-07-16”

sdata/time

The sdata/time type is a string representing the time of day. The format of the contents MUST correspond to the “extended format” of “hh:mm:ss” of the ISO8601 specification [8], with an optional fractional part to the seconds. In addition, it is RECOMMENDED that the value contain the time-zone information as recommended by [8], although this may not be appropriate in some cases (for example, times for recurring events in locales using Daylight Savings).

Example:

  • “lastUpdatedTime”: “20:30Z”
  • “lastUpdatedTime”: “20:30:12+02:00”
  • “lastUpdatedTime”: “20:30:12.435-01:00”

sdata/datetime

The sdata/datetime type is a string representing a time on a particular date. The format of the contents MUST correspond to the ISO8601 specification [8], with the date and time parts following the SData requirements above. In addition, SData REQUIRES that the value contain the time-zone information as recommended by the standard.

Examples:

  • “invoicePrintedAt”: “2014-07-16T19:20:30+1:00”
  • “invoicePrintedAt”: “2014-07-16T19:20:30Z”

Complex types

Complex types describe properties that are either JSON objects or containers of objects and properties. The $item property of a complex type is a JSON object of the type that comprises the metadata (including the type) for the contained object. The $item property MUST be present for all complex types.

sdata/choice

The sdata/choice type describes an enumeration. The $item property MUST contain a $type and a $enum property. The $enum property is an array of JSON objects delivering the enumeration elements. Each JSON object in $enum MUST contain a $value property which defines the value of the enumeration elements.

Example: The property status taking on values “ready”, “pending” or “done” would be expressed as:

{ 
    "status" : {
        "$type" : "sdata/choice",
        "$item" : {
            "$type" : "sdata/string",
            "$enum" : [
                { "$value" : "ready", "$title" : "READY" }, 
                { "$value" : "pending", "$title" : "PENDING" }, 
                { "$value" : "done", "$title" : "DONE" } 
            ] 
        }
    }
}

The payload for a valid resource could look like:

{
    "status" : "ready"
}

sdata/array

The sdata/array type specifies that the property is a JSON array. The elements of the array are specified within $item and can be of any type. The $item property MUST be present.

Example: A simple object containing an array of tags can be expressed as:

{
    "firstName": { "$type": "sdata/string" },
    "lastName": { "$type": "sdata/string" },
    "...": "...",
    "tags": {
        "$type": "sdata/array",
        "$item": {
            "type": "sdata/string"
        }
    }
}

A valid resource payload could look like:

{
    "firstName": "John",
    "lastName": "Doe",
    "...": "...",
    "tags": [ "C#", "Java", "Programming" ] 
}

sdata/reference

The sdata/reference type identifies a property that contains a reference to another SData resource. The properties of the referenced resource MAY be included - fully or partially - in the payload. These properties are to be viewed as read-only, and consequently any modification on the consumer side to these properties will be ignored by the provider.

The metadata is presented as follows:

  • metadata pertaining to the property is defined within the object.
  • metadata pertaining to the sdata/reference object is defined within the $item object.

The referenced resource is pointed to by a $url specification located inside the $item block. The presence of:

  • $item is REQUIRED (in the object).
  • $url is REQUIRED (in the $item).
  • $properties is OPTIONAL.
  • $links is OPTIONAL but RECOMMENDED (see the next chapter for a discussion on links).

Example: The manager of an Employee resource could be represented as follows:

{
    "id": { "$type": "sdata/string" },
    "...": "...",
    "manager": {
        "$type": "sdata/reference",
        "$title": "Manager Link",
        "$key": "{$uuid}",
        "$item" : {
            "$url": "{$baseUrl}/users('{$key}')",
            "$title": "Manager Details",
            "$properties": {
                "firstName": { "$type": "sdata/string" },
                "lastName": { "$type": "sdata/string" }
            }
        }
    }  
}

A valid resource payload could look like:

{
    "id": "967-1111",
    "...": "...",
    "manager": {
        "firstName": "John",
        "lastName":  "Doe"
    }
}

IMPORTANT:

A consumer can only operate on the relationship with the referenced resources. This means that relationships between enclosing and referenced resources can be created or deleted and then persisted via a PUT/PATCH on the enclosing resource. It is not possible to create a new referenced resource in this context. This is achieved by operating directly (via POST, DELETE) on the resource kind of the reference. 4

sdata/object

The sdata/object type identifies an embedded resource. Please note that the payload of the embedded resource MUST be presented in its entirety within the payload of the enclosing resource.

The metadata is presented as follows:

  • metadata pertaining to the property is defined within the object.
  • metadata pertaining to the sdata/object is defined within the contained $item object.

The presence of:

  • $item is REQUIRED.
  • $url is OPTIONAL.
  • $properties is OPTIONAL.
  • $links is OPTIONAL but RECOMMENDED (see the next section for a discussion on links).

Example: An Employee with an embedded Address resource could be represented as follows:

{
    "firstName": { "$type": "sdata/string" },
    "lastName": { "$type": "sdata/string" },
    "...": "...",
    "address": {
        "$type": "sdata/object",
        "$title": "Address",
        "$item": {
            "$properties": {
                "street":  { "$type": "sdata/string" },
                "zip":   { "$type": "sdata/string" },
                "city":   { "$type": "sdata/string" },
                "state":   { "$type": "sdata/string" },
                "country": { "$type": "sdata/string", 
                "$format": "country"}
            }
        }
    }
}

A valid resource payload could look like:

{
    "firstName": "John",
    "lastName":  "Doe",
    "...": "...",
    "address": {
        "street":  "444 High Street",
        "zip":   "92301",
        "city":   "Palo Alto",
        "state":   "California",
        "country": "US"
    }
}

IMPORTANT:

Unlike the sdata/reference case, the consumer can create, delete, and update the resources embedded as an sdata/object in the context of the object. A PUT operation on a resource containing an sdata/object property will have the effect of persisting the resource and the embedded sdata/object resources as they stand (barring, of course, the case of constraint violations on the provider side).

Other internet media types

Any internet media type outside the ones described in the previous sections MAY be attached to an SData JSON property. The associated value (or object) in the payload is transparent to SData, although it could be meaningful in the context of a particular contract.

Note: if a JSON object is specified using “application/JSON”, there is no requirement for the attached JSON object to conform to the SData standard.

Example: An Employee resource referencing a photograph resource could be represented as follows:

{
    "$baseUrl": "http://www.example.com/sdata/MyApp/-/-",
    "...": "...",
    "$properties": {
        "firstName": {
            "$type": "sdata/string"
        },
        "lastName": {
            "$type": "sdata/string"
        },
        "photoKey": {
            "$type": "sdata/string",
            "$isHidden": true
        },
        "photograph": {
            "$type": "image/jpeg",
            "$url": "{$baseUrl}/pictures('{photoKey}')"
        }
    },
    "...": "...",
    "firstName": "John",
    "lastName": "Doe",
    "photoKey": "445-C...",
    "photograph": "http://www.example.com/sdata/MyApp/-/-/pictures('445-C...')"
}

In the example above, the consumer would be able to retrieve the image associated with an employee by combining the information from the photograph object with the information passed in the payload through the photoKey property.

The $isHidden property indicates that the photoKey property SHOULD NOT be rendered on any user interface.

4. Or by operating via the appropriate links: $create, $delete, $updateFull, $updatePartial as described in the next section.

Previous Page Arrow Next Page Arrow