2.2.6.3.3 Entity Type (as a Verbose JSON Object)
An instance of an EntityType MUST be serialized as a Verbose JSON object.
Each property on the EntityType MUST be represented as a name/value pair, as specified in [RFC4627], within the object. Alternatively, if the EntityType instance being represented is identified with a URI that includes a Select system query option (section 2.2.3.6.1.11), the prior rule is relaxed such that only the properties identified by the $select query option MUST be represented by name/value pairs. The name in the name/value pair is the name of the property as defined on the EntityType, and the value of the pair is the value of the property. The order name/value pairs that appear within a JSON object MUST be considered insignificant. Name/value pairs not representing a property defined on the EntityType SHOULD NOT be included. The following subsections describe additional formatting rules for each type of property defined on an EntityType.
The Verbose JSON serialization of an EntityType instance MAY<63> include a name/value pair named "__metadata". This name/value pair is not data, but instead, by convention defined in this document, specifies the metadata for the EntityType instance that the JSON object represents. The ordering of this name/value pair with respect to other name/value pairs that represent properties that are defined on the EntityType is insignificant. In OData 1.0 and OData 2.0, the value of the "__metadata" property contains seven name/value pairs: "uri", "type," "etag", "edit_media", "media_src", "media_etag", and "content_type". In OData 3.0, four more name/value pairs are added: "properties", "actions", "functions", and "id". The order of these name/value pairs is insignificant. The value of the "uri" name/value pair MUST be the Canonical URIs identifying the EntityType instance represented by the JSON object.
The "type" name/value pair MUST be included if the EntityType of the EntityType instance represented by the JSON object is part of an inheritance hierarchy, as described in [MC-CSDL] (section 1). If the EntityType is not part of an inheritance hierarchy, the "type" name/value pair MAY be included. The value of the "type" name/value pair MUST be the namespace qualified name, as specified in [MC-CSDL], of the EntityType of the instance that the JSON object represents.
The "etag" name/value pair MAY be included. When included, it MUST represent the concurrency token associated with the EntityType instance ETag (section 2.2.5.4) and MUST be used instead of the ETag HTTP header defined in ETag (section 2.2.5.4), which, as specified in [RFC2616], is used to represent a single entity when multiple entities are present in a single payload.
The "media_src" and "content_type" name/value pairs MUST be included and the "edit_media" and "media_etag" name/value pairs MAY be included if the entity being represented is a Media Link Entry. For example, the description of the entity type as shown in the data services' CSDL document includes the HasStream="true" attribute as defined in section 2.2.3.7.2. If the entity being represented is not a Media Link Entry, the "edit_media", "media_src", "media_etag", and "content_type" name/value pairs cannot be included.
The "id" name/value pair can be included if the server is using OData 2.0 and has to be included if the server is using OData 3.0.
The value of the "edit_media" name/value pair MUST be a URI that is equivalent to the value of the "href" attribute on an atom:linkrel="edit-media" AtomPub element if the entity was to be represented by the AtomPub [RFC5023] format, instead of Verbose JSON. The value of the "media_src" name/value pair MUST be a URI that is equivalent to the value of the "src" attribute on the atom:content AtomPub element if the entity was to be represented using the AtomPub [RFC5023] format, instead of Verbose JSON. The value of the "content_type" name/value pair MUST be equivalent to the value of the "type" attribute on the atom:content AtomPub element if the entity was to be represented using the AtomPub [RFC5023] format, instead of Verbose JSON. The value of the "media_etag" name/value pair MUST be equal to the value of the concurrency token associated with the Media Resource identified by the "edit_media" and/or "media_src" name/value pairs.
The value of the "properties" name/value pair MAY contain a JSON object for each NavigationProperty. Each NavigationProperty is serialized as name/value pairs in which the value is a JSON object that contains a single name/value pair, with the name equal to the name of the NavigationProperty and a value equal to the URI that can be used to manage the relationship between the related entities.
The JSON object representing the EntityType SHOULD also contain representations of the properties defined on the EntityType. Each EDMSimpleType, ComplexType, and NavigationProperty defined on the EntityType MUST be formatted according to the directives in sections EDMSimpleType Property (section 2.2.6.3.8), Complex Type (section 2.2.6.3.4), and Navigation Property (section 2.2.6.3.6).
The syntax of the Verbose JSON representation of an entity is defined by the grammar listed in this section. The grammar rule "entityTypeInVJson" defines the representation of an entity that can be used in both request and response payloads.
-
; OData 1.0, OData 2.0, and OData 3.0 Verbose JSON representation of an entity: entityTypeInVJson = entityTypeBody entityTypeBody = begin-object ( (entityTypeProperty) *( value-seperator ( entityTypeProperty / entityTypeProperty )) [ value-seperator metadataNVP] ) / metadataNVP end-object metadataNVP = quotation-mark "__metadata" quotation-mark name-seperator begin-object ( uriNVP [value-seperator idNVP] [value-seperator typeNVP] [value-seperator etagNVP] [value-separator mleMetadata]) [propmetadataNVP] [actionsNVP] [functionsNVP] / ( typeNVP [value-seperator etagNVP]) [propmetadataNVP] / etagNVP [propmetadataNVP] / propmetadataNVP end-object entityTypeProperty = entityPropertyInVJson /entityCTInVJson /deferredNavProperty /namedSteamInVJson uriNVP = quotation-mark "uri" quotation-mark name-seperator quotation-mark resourcePath quotation-mark ; OData 3.0 Verbose JSON representation of Actions: actionsNVP = quotation-mark "actions" quotation-mark name-seperator begin-object [ actionNVP *(value-seperator actionNVP) ] end-object actionNVP = quotation-mark actionUri quotation-mark name-seperator begin-object titleNVP value-seperator targetNVP end-object ; OData 3.0 Verbose JSON representation of Functions: functionsNVP = quotation-mark "functions" quotation-mark name-seperator begin-object [ functionNVP *(value-seperator functionNVP) ] end-object functionNVP = quotation-mark functionUri quotation-mark name-seperator begin-object titleNVP value-seperator targetNVP end-object titleNVP = quotation-mark "title" quotation-mark name-seperator quotation-mark titleValue quotation-mark titleValue = *pchar ; section 3.3 of [RFC3986] targetNVP = quotation-mark "target" quotation-mark name-seperator quotation-mark targetUrl quotation-mark targetUrl = ; a Url that can be used as the target for ; either an Invoke Action Request (section 2.2.7.5.1) or ; an Invoke Function Request (section 2.2.7.5.2) actionUrl = ; an Action Metadata URL (section 2.2.1.3.1) functionUrl = ; a Function Metadata URL (section 2.2.1.4.1) ; OData 3.0 Verbose JSON representation of the URI representing the relationship between ; related entities: propmetadataNVP = quotation-mark "properties" quotation-mark name-seperator begin-object ( entityTypeProperty name-seperator begin-object ( quotation-mark "associationuri" quotation-mark name-seperator quotation-mark resourcePath quotation-mark ) ) end-object typeNVP = quotation-mark "type" quotation-mark name-seperator quotation-mark entityType quotation-mark etagNVP = quotation-mark "type" quotation-mark name-seperator quotation-mark entityTag quotation-mark editMediaNVP = quotation-mark "edit_media" quotation-mark name-seperator quotation-mark resourcePath quotation-mark mediaSrcNVP = quotation-mark "media_src" quotation-mark name-seperator quotation-mark resourcePath quotation-mark contentTypeNVP = quotation-mark "content_type" quotation-mark name-seperator quotation-mark contentType quotation-mark idNVP = quotation-mark "id" quotation-mark name-seperator quotation-mark resourcePath quotation-mark mleMetadata = media_srcNVP value-seperator contentTypeNVP [value-seperator etagNVP] [value-seperator editMediaNVP] deferredNavProperty = entityNavProperty name-seperator begin-object quotation-mark "__deferred" quotation-mark name-seperator begin-object uriNVP end-object end-object contentType = <An IANA-defined [IANA-MMT] content type> resourcePath = ; section 2.2.3.1 entityCTInVJson = ; section 2.2.6.3.4 entityPropertyInVJson = ; section 2.2.6.3.8 entityPropertyValueInVJson = ; section 2.2.6.3.8 entityType = ; section 2.2.3.1 entityNavProperty = ; section 2.2.3.1 entityTag = ; section 2.2.5.4 begin-object = ; [RFC4627] section 2 name-seperator = ; [RFC4627] section 2 value-seperator = ; [RFC4627] section 2 value = ; [RFC4627] section 2.1
Listing: OData 3.0 Entity Type Verbose JSON Representation
For example, the Customer EntityType instance described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) is represented in Verbose JSON, as shown in the following listing.
-
{ "CustomerID": "ALFKI", "CompanyName": "Alfreds Futterkiste", "Address": { "Street": "57 Contoso St", "City": "Seattle" }, "Version": "AAAAAAAA+gE=", "Orders": { "__deferred": { "uri": "Customers(\'ALFKI\')/Orders" } }, "__metadata": { "uri": "Customers(\'ALFKI\')", "type": "SampleModel.Customer", "etag": "W/\"X\'000000000000FA01\'\"", "properties" : { "Orders" : { "associationuri" : "Customers(\'ALFKI\')/$links/Orders" } } } }
Listing: OData 3.0 Verbose JSON-formatted Customer Entity