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