Embedded metadata

SData payloads contain embedded metadata elements of two kinds:

• SData-defined elements: used throughout this document and collected in Appendix A.
• Application specific metadata elements.

Metadata inclusion in a JSON response is governed by the following rules:

• SData metadata for an object is presented as properties of the objects, along-side the native properties of the object. Given the leading $, it is possible to distinguish between the two.
• SData metadata pertaining to properties of an object is collected in a $properties object within the object itself. The structure of the $properties is as follows:
  • properties of the $properties JSON object mirror the native properties of the original object (and have the same name).
  • the contents are objects enclosing the metadata elements pertaining to corresponding native properties.
• The capability metadata elements (canRead, canUpdate, canDelete, canCreate) are replaced in their functionality by links.

Embedded metadata SHOULD be an exception, meant to override/extend the information contained in the prototype (see section SData prototypes for more details on prototypes). In this manner, it is possible to significantly reduce the volume of information transferred from the provider to the consumer.

Example: Consider a Product object with the following structure and data:

Product

• name -> “iPhone”
• ID -> “4711”
• unitPrice -> 459.00
• stock -> “available” [read only]

In this example, the value of the stock property is computed by the underlying application and therefore readOnly. Retrieving this product by means of a GET operation on …/Products(‘4711’) we should get the following format in JSON for the product in question:

{ 
    "$url" : "https://www.example.com/sdata/myapp/-/-/products('4711')", 
    "$key" : "4711", 
    "name" : "iPhone", 
    "ID" : "4711", 
    "unitPrice" : 459.00, 
    "stock" : "available", 
    "$properties" : {
        "stock" : { "$isReadOnly" : true}
    }
}

The result shows the SData required elements $url and $key embedded at the same level as the native properties of the object. Additionally, the $properties contains a stock object with the name-value pair passing the $isReadOnly attribute value to the caller.

$properties object

The $properties object encapsulates the properties of the resource kind as they would be returned by a GET operation in JSON, and has the following characteristics:

• The object structure is maintained, exactly matching the JSON structure in the payload.
• An individual property is a JSON object whose name does NOT start with $ and contains:
  • The metadata for the object represented as name-value pairs. The name will start with a $.
• Each property MUST have an associated $type specification.

Example:

Consider the following Address resource kind with metadata enclosed in square brackets:

• ID: [integer, Hidden, Mandatory]
• Street: [string, title=”Street”, Mandatory]
• StreetNumber: [integer, title=”Number”]
• City: [string, title=”City”, Mandatory]
• PostalCode: [string, title=”ZipCode”, Mandatory]
• Country: [referenceToCountryResourceKind, Mandatory]
  • Name: [string]
  • ISOCode: [string]
  • [url=”http://www.example.com/sdata/MyApp/-/-/countries”]

This would result in the following $properties object:

{
    "$properties": {
        "ID": {
            "$title": "AddressId",
            "$type": "sdata/integer",
            "$isMandatory": true,
            "$isHidden": true
        },
        "Street": {
            "$title": "Street",
            "$type": "sdata/string",
            "$isMandatory": true
        },
        "StreetNumber": {
            "$title": "Number",
            "$type": "sdata/integer"
        },
        "City": {
            "$title": "City",
            "$type": "sdata/string",
            "$isMandatory": true
        },
        "PostalCode": {
            "$title": "ZipCode",
            "$type": "sdata/string",
            "$isMandatory": true
        },
        "Country": {
            "$title": "Country",
            "$type": "sdata/reference",
            "$links": {
                "$prototype": {
                    "$id": "lookup",
                    "$url": "{$baseUrl}/$prototypes/countries('{$id}')",
                    "$title": "Prototype of Country thumbnail"
                }
            },
            "$isMandatory": true,
            "$item": {
                "$url": "http://www.example.com/sdata/MyApp/-/-/countries('{ISOCode}')",
                "$properties": {
                    "Name": {
                    "$title": "Country name",
                    "$type": "sdata/string",
                    "$isMandatory": true
                    },
                    "ISOCode": {
                        "$title": "Country code",
                        "$type": "sdata/string",
                        "$format": "country",
                        "$isMandatory": true
                    }
                }
            }
        }
    }
}

In the above, the scalar properties (ID, Street, …) are objects containing respectively the $title, $type and, if appropriate, the $isMandatory metadata.

The Country property is a reference to the countries resource kind. Accordingly, it has a type of “sdata/reference” and a $url specification. The metadata for the sub-properties of Country (i.e. Name and ISOCode) are defined in the body of the $item object.

---