Substitution formalism

Metadata associated with the natural payload of a resource can be quite extensive and the values they carry (often URLs) are quite verbose. To reduce bandwidth consumption and to ease readability, SData 2.0’s JSON format defines a formalism that allows a compressed representation of string values.

The substitution formalism is simple: the string values of metadata elements may contain a property name (metadata or payload) enclosed in curly brackets (“{“ and “}”). Once a payload is received, the above specified string portions are substituted with the corresponding values. The syntax is a simplified version of RFC 6570, “URI Template” [3], applicable to any information, not just URIs.

The substitution process is described as follows:

• For every complete resource (payload + all associated metadata), for every metadata string property in the object, perform the following:
• If the string contains an un-escaped³ “{identifierString}” substring then
  • If the identifierString is a defined property name determined according to the scoping rules below, then:
    • Replace “{identifierString}” with its corresponding value in string format.
  • Otherwise, a formal error has occurred.

Scoping rules: using the specification “X” : “{Y}”

• If the values of X and Y are different:
  • The initial search scope is the scope containing the definition of the property X.
• Otherwise:
  • The initial search scope is the scope immediately enclosing (logically “above”) the scope containing the definition of the property X.
• If a property Y can be found in this scope, its value is used in the substitution.
• Otherwise, the enclosing scopes are searched for property Y, from the initial scope “upwards”. The reader will encounter specifications of the form “X”: “X” in the section on Links, where they are used to indicate that the URL for a link should be obtained by substitution of the URL in the containing object.

The substitution formalism defines a recursive process with a fixed recursion depth set as default to 5; the value of the recursion depth can be overridden if necessary in the contract.

Example: Consider the following simple SData entry expressed in JSON:

{
    "$baseUrl": "http://www.example.com/sdata/MyApp/-/-",
    "$url": "{$baseUrl}/addresses?CreditExceeded=true",
    "$title": "Account {accountId} of {companyName} has exceeded credit limit",
    "companyName": "ACME Inc.",
    "accountId": "A-1322",
    "ID": "7123a",
    "Street": "Lerchenweg",
    "StreetNumber": 11,
    "PostalCode": 71711,
    "City": "Marbach am Neckar",
    "Country": {
        "$url": "{$baseUrl}/countries('{ISOCode}')",
        "Name": "Germany",
        "ISOCode": "DE"
    }
}

In this case, the metadata properties highlighted in red (two instances of $url and one of $title) have values that require substitution. This is applied as follows:

• $baseUrl value into:
  • $url at the entity level.
  • $url within the Country property.
• accountId and companyName in the $title at the feed level.
• ISOCode value into the respective $url of the Country object.

The substitutions and the resulting logical JSON object (final) are shown below:

{
    "$baseUrl": "http://www.example.com/sdata/MyApp/-/-",
    "$url": " http://www.example.com/sdata/MyApp/-/-/addresses?CreditExceeded=true",
    "$title": "Account  A-1322 of  ACME Inc. has exceeded credit limit",
    "companyName": "ACME Inc.",
    "accountId": "A-1322",
    "ID": "7123a",
    "Street": "Lerchenweg",
    "StreetNumber": 11,
    "PostalCode": 71711,
    "City": "Marbach am Neckar",
    "Country": {
        "$url": " http://www.example.com/sdata/MyApp/-/-/countries('DE')",
        "Name": "Germany",
        "ISOCode": "DE"
    }
}

---

3. The substitution mechanism can be escaped by using “ and “ instead of the single curly brackets.