The following subsections describe how the context URL is constructed for each category of payload by providing a context URL template. The context URL template uses the following terms:
{context-url} is the canonical resource path to the $metadata document,{entity-set} is the name of an entity set OData-CSDL, section 13.2 or the canonical path to a collection-valued containment navigation property (implicit entity set OData-CSDL, section 8.4),{single-entity} is the name of a singleton or the canonical path to a single-valued containment navigation property,{entity} is the canonical URL for an entity,{entity-collection} is the name of an entity set OData-CSDL, section 13.2 or the canonical path to a collection-valued containment navigation property (implicit entity set OData-CSDL, section 8.4),{entity-singleton} is the name of a singleton or the canonical path to a single-valued containment navigation property,{entity} is the canonical URL for an entity within a collection,{select-list} is an optional parenthesized comma-separated list of selected properties, instance annotations, functions, and actions,{property-path} is the path to a structural property of the entity,{type-name} is a qualified type name,{/type-name} is an optional type-cast segment containing the qualified name of a derived or implemented type prefixed with a forward slash.Key values in the canonical path in {entity-set}, {single-entity}, and {entity} are represented in canonical form (parentheses-style) without percent-encoding.
Key values in the canonical path in {entity-collection}, {entity-singleton}, and {entity} are represented in canonical form (parentheses-style) without percent-encoding.
The full grammar for the context URL is defined in OData-ABNF. Note that the syntax of the context URL is independent of whatever URL conventions the service uses for addressing individual entities.
Context URL template:
-{context-url}#{entity-set}
+{context-url}#{entity-collection}
{context-url}#Collection({type-name})
-If all entities in the collection are members of one (named or implicit) entity set, the context URL fragment is the canonical path {entity-set} to the entity set.
+If all entities in the collection are members of one entity set (including implicit), the context URL fragment is the canonical path {entity-collection} to the entity set.
Example 11: resource URL and corresponding context URL
http://host/service/Customers
@@ -1341,52 +1341,51 @@ 10.3 Entity
Context URL template:
-{context-url}#{entity-set}/$entity
-{context-url}#{single-entity}
+{context-url}#{entity-collection}/$entity
{context-url}#{type-name}
-If a response or response part is an entity of the declared type of a (named or implicit) entity set, the context URL fragment is the canonical path {entity-set} to the entity set with /$entity appended.
+If a response or response part is an entity bound to an entity set (including implicit), the context URL fragment is the canonical path {entity-collection} to the entity set with /$entity appended.
Example 13: resource URL and corresponding context URL for named entity set. Note the absence of the key predicate (1) in the context URL.
http://host/service/Customers(1)
http://host/service/$metadata#Customers/$entity
-Example 14: resource URL and corresponding context URL for contained entity (implicit entity set)
+Example 14: resource URL and corresponding context URL for contained entity
http://host/service/Orders(4711)/Items(1)
http://host/service/$metadata#Orders(4711)/Items/$entity
-If a response or response part is an entity of the declared type of a single-valued containment navigation property, the context URL fragment is the canonical path {single-entity} to that navigation property without /$entity appended.
-
-Example 15: resource URL and corresponding context URL for entity targeted by a single-valued containment navigation property
-http://host/service/Orders(4711)/DeliveryAddress
-http://host/service/$metadata#Orders(4711)/DeliveryAddress
-
-If the entity is not bound to an entity set, such as an entity returned from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL fragment specifies the type {type-name} of the returned entity.
+If the entity is within a collection, but its entity set (including implicit) cannot be determined, such as for an entity returned from a function or action with no entity set path, a function import or action import with no specified entity set, or a navigation property with no navigation property binding, the context URL fragment specifies the type {type-name} of the returned entity.
10.4 Singleton
Context URL template:
-{context-url}#{single-entity}
+{context-url}#{entity-singleton}
If a response or response part is a singleton, its name is the context URL fragment.
-Example 16: resource URL and corresponding context URL
+Example 15: resource URL and corresponding context URL
http://host/service/MainSupplier
http://host/service/$metadata#MainSupplier
+If a response or response part is an entity targeted by a single-valued containment navigation property, the context URL fragment is the canonical path {entity-singleton} to that navigation property without /$entity appended.
+
+Example 16: resource URL and corresponding context URL for entity targeted by a single-valued containment navigation property
+http://host/service/Orders(4711)/DeliveryAddress
+http://host/service/$metadata#Orders(4711)/DeliveryAddress
+
10.5 Collection of Derived Entities
Context URL template:
-{context-url}#{entity-set}{/type-name}
-If an entity set consists exclusively of derived entities, a type-cast segment is added to the context URL.
+{context-url}#{entity-collection}{/type-name}
+If a response or response part is a collection filtered by a type cast segment in the resource URL OData-URL, section 4.11, the type-cast segment is added to the context URL.
Example 17: resource URL and corresponding context URL
http://host/service/Customers/Model.VipCustomer
@@ -1397,28 +1396,34 @@ 10.6 Derived Entity
Context URL template:
-{context-url}#{entity-set}{/type-name}/$entity
-If a response or response part is an entity of a type derived from the declared type of an entity set, a type-cast segment is appended to the entity set name.
+{context-url}#{entity-collection}{/type-name}/$entity
+{context-url}#{entity-singleton}{/type-name}
+If a response or response part is an entity filtered by a type cast segment in the resource URL OData-URL, section 4.11, the type-cast segment is appended to the {entity-collection} or {entity-singleton} and prior to appending /$entity, if any.
-Example 18: resource URL and corresponding context URL
+Example 18: resource URL with key predicate and corresponding context URL
http://host/service/Customers(2)/Model.VipCustomer
http://host/service/$metadata#Customers/Model.VipCustomer/$entity
+
+Example 19: resource URL for singleton and corresponding context URL
+http://host/service/MainSupplier/Model.PreferredVendor
+http://host/service/$metadata#MainSupplier/Model.PreferredVendor
+
10.7 Collection of Projected Entities
Context URL templates:
-{context-url}#{entity-set}{/type-name}{select-list}
+{context-url}#{entity-collection}{/type-name}{select-list}
{context-url}#Collection({type-name}){select-list}
-If a result contains only a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, instance annotations, navigation properties, functions, and actions is appended to the context URL representing the collection of entities.
+If a response or response part contains only a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, instance annotations, navigation properties, functions, and actions is appended to the context URL representing the collection of entities.
Regardless of how contained structural properties are represented in the request URL (as paths or as select options) they are represented in the context URL using path syntax, as defined in OData 4.0.
The shortcut * represents the list of all structural properties. Properties defined on types derived from the declared type of the entity set (or type specified in the type-cast segment if specified) are prefixed with the qualified name of the derived type as defined in OData-ABNF.
The list also contains explicitly selected or expanded instance annotations. It is possible to select or expand only instance annotations, in which case only those selected or expanded annotations appear in the result. Note that annotations specified only in the include-annotations preference do not appear in the context URL and do not affect the selected/expanded properties.
Operations in the context URL are represented using the namespace- or alias-qualified name. Function names suffixed with parentheses represent a specific overload, while function names without parentheses represent all overloads of the function.
OData 4.01 responses MAY use the shortcut pattern {namespace}.* to represent the list of all bound actions or functions available for entities in the collection, see system query option $select.
-Example 19: resource URL and corresponding context URL
+Example 20: resource URL and corresponding context URL
http://host/service/Customers?$select=Address,Orders,Model.VipCustomer/PreferredContact
http://host/service/$metadata#Customers(Address,Orders,Model.VipCustomer/PreferredContact)
@@ -1427,17 +1432,17 @@ 10.8 Projected Entity
Context URL templates:
-{context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{single-entity}{select-list}
+{context-url}#{entity-collection}{/type-name}{select-list}/$entity
+{context-url}#{entity-singleton}{/type-name}{select-list}
{context-url}#{type-name}{select-list}
-If an entity contains a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, instance annotations, navigation properties, functions, and actions is appended to the {entity-set} after an optional type-cast segment and prior to appending /$entity, or to the {single-entity}. If the response is not a subset of a single entity set, the {select-list} is instead appended to the {type-name} of the returned entity.
+If a response or response part is an entity that contains a subset of properties, the parenthesized comma-separated list of the selected defined or dynamic properties, instance annotations, navigation properties, functions, and actions is appended to the {entity-collection} or {entity-singleton} after an optional type-cast segment and prior to appending /$entity, if any.
Regardless of how contained structural properties are represented in the request URL (as paths or as select options) they are represented in the context URL using path syntax, as defined in OData 4.0.
The shortcut * represents the list of all structural properties. Properties defined on types derived from the type of the entity set (or type specified in the type-cast segment if specified) are prefixed with the qualified name of the derived type as defined in OData-ABNF. Note that expanded properties are automatically included in the response.
The list also contains explicitly selected or expanded instance annotations. It is possible to select or expand only instance annotations, in which case only those selected or expanded annotations appear in the result. Note that annotations specified only in the include-annotations preference do not appear in the context URL and do not affect the selected/expanded properties.
Operations in the context URL are represented using the namespace- or alias-qualified name. Function names suffixed with parentheses represent a specific overload, while function names without parentheses represent all overloads of the function.
OData 4.01 responses MAY use the shortcut pattern {namespace}.* to represent the list of all bound actions or functions available for the returned entity, see system query option $select.
-Example 20: resource URL and corresponding context URL
+Example 21: resource URL and corresponding context URL
http://host/service/Customers(1)?$select=Name,Rating
http://host/service/$metadata#Customers(Name,Rating)/$entity
@@ -1446,7 +1451,7 @@ 10
10.9 Collection of Expanded Entities
Context URL template:
-{context-url}#{entity-set}{/type-name}{select-list}
+{context-url}#{entity-collection}{/type-name}{select-list}
{context-url}#Collection({type-name}){select-list}
For a 4.01 response, if a navigation property is explicitly expanded, then in addition to any non-suffixed names of any selected properties, navigation properties, functions or actions, the comma-separated list of properties MUST include the name of the expanded property, suffixed with the parenthesized comma-separated list of any properties of the expanded navigation property that are selected or expanded. If the expanded navigation property does not contain a nested $select or $expand, then the expanded property is suffixed with empty parentheses. If the expansion is recursive for nested children, a plus sign (+) is infixed between the navigation property name and the opening parenthesis.
For a 4.0 response, the expanded navigation property suffixed with parentheses is omitted from the select-list if it does not contain a nested $select or $expand, but MUST still be present, without a suffix, if it is explicitly selected.
@@ -1454,17 +1459,17 @@
-Example 21: resource URL and corresponding context URL — select and expand
+Example 22: resource URL and corresponding context URL — select and expand
http://host/service/Customers?$select=Name&$expand=Address/Country
http://host/service/$metadata#Customers(Name,Address/Country())
-Example 22: resource URL and corresponding context URL — expand $ref
+Example 23: resource URL and corresponding context URL — expand $ref
http://host/service/Customers?$expand=Orders/$ref
http://host/service/$metadata#Customers
-Example 23: resource URL and corresponding context URL — expand with $levels
+Example 24: resource URL and corresponding context URL — expand with $levels
http://host/service/Employees/Sales.Manager?$select=DirectReports
&$expand=DirectReports($select=FirstName,LastName;$levels=4)
http://host/service/$metadata
@@ -1475,15 +1480,15 @@ 10.10 Expanded Entity
Context URL template:
-{context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{single-entity}{select-list}
+{context-url}#{entity-collection}{/type-name}{select-list}/$entity
+{context-url}#{entity-singleton}{/type-name}{select-list}
{context-url}#{type-name}{select-list}
For a 4.01 response, if a navigation property is explicitly expanded, then in addition to the non-suffixed names of any selected properties, navigation properties, functions or actions, the comma-separated list of properties MUST include the name of the expanded property, suffixed with the parenthesized comma-separated list of any properties of the expanded navigation property that are selected or expanded. If the expanded navigation property does not contain a nested $select or $expand, then the expanded property is suffixed with empty parentheses. If the expansion is recursive for nested children, a plus sign (+) is infixed between the navigation property name and the opening parenthesis.
For a 4.0 response, the expanded navigation property suffixed with parentheses is omitted from the select-list if it does not contain a nested $select or $expand, but MUST still be present, without a suffix, if it is explicitly selected.
If the context URL includes only expanded navigation properties (i.e., only navigation properties suffixed with parentheses), then all structural properties are implicitly selected (same as if there were no properties listed in the select-list).
Navigation properties with expanded references are not represented in the context URL.
-Example 24: resource URL and corresponding context URL
+Example 25: resource URL and corresponding context URL
http://host/service/Employees(1)/Sales.Manager?
$expand=DirectReports($select=FirstName,LastName;$levels=4)
http://host/service/$metadata
@@ -1497,7 +1502,7 @@
-Example 25: resource URL and corresponding context URL for a collection of entity references
+Example 26: resource URL and corresponding context URL for a collection of entity references
http://host/service/Customers('ALFKI')/Orders/$ref
http://host/service/$metadata#Collection($ref)
@@ -1509,7 +1514,7 @@ 1
{context-url}#$ref
If a response is one entity reference, $ref is the context URL fragment.
-Example 26: resource URL and corresponding context URL for a single entity reference
+Example 27: resource URL and corresponding context URL for a single entity reference
http://host/service/Orders(10643)/Customer/$ref
http://host/service/$metadata#$ref
@@ -1523,7 +1528,7 @@ 10.13 P
If a response represents an individual property of an entity with a canonical URL, the context URL specifies the canonical URL of the entity and the path to the structural property of that entity. The path MUST include cast segments for properties defined on types derived from the expected type of the previous segment.
If the property value does not contain explicitly or implicitly selected navigation properties or operations, OData 4.01 responses MAY use the less specific second template.
-Example 27: resource URL and corresponding context URL
+Example 28: resource URL and corresponding context URL
http://host/service/Customers(1)/Addresses
http://host/service/$metadata#Customers(1)/Addresses
@@ -1535,7 +1540,7 @@
-Example 28: resource URL and corresponding context URL
+Example 29: resource URL and corresponding context URL
http://host/service/TopFiveHobbies()
http://host/service/$metadata#Collection(Edm.String)
@@ -1547,7 +1552,7 @@
-Example 29: resource URL and corresponding context URL
+Example 30: resource URL and corresponding context URL
http://host/service/MostPopularName()
http://host/service/$metadata#Edm.String
@@ -1556,14 +1561,14 @@ 10.16 Operation Result
Context URL templates:
-{context-url}#{entity-set}{/type-name}{select-list}
-{context-url}#{entity-set}{/type-name}{select-list}/$entity
+{context-url}#{entity-collection}{/type-name}{select-list}
+{context-url}#{entity-collection}{/type-name}{select-list}/$entity
{context-url}#{entity}/{property-path}{select-list}
{context-url}#Collection({type-name}){select-list}
{context-url}#{type-name}{select-list}
If the response from an action or function is a collection of entities or one entity that is a member of an entity set, the context URL identifies the entity set. If the response from an action or function is a property of one entity, the context URL identifies the entity and property. Otherwise, the context URL identifies the type returned by the operation. The context URL will correspond to one of the former examples.
-Example 30: resource URL and corresponding context URL
+Example 31: resource URL and corresponding context URL
http://host/service/TopFiveCustomers()
http://host/service/$metadata#Customers
@@ -1572,14 +1577,14 @@ 1
10.17 Delta Payload
Context URL template:
-{context-url}#{entity-set}{/type-name}{select-list}/$delta
+{context-url}#{entity-collection}{/type-name}{select-list}/$delta
{context-url}#{entity}{select-list}/$delta
{context-url}#{entity}/{property-path}{select-list}/$delta
#$delta
The context URL of a delta response is the context URL of the response to the defining query, followed by /$delta. This includes singletons, single-valued navigation properties, and collection-valued navigation properties.
-If the entities are contained, then {entity-set} is the top-level entity set followed by the path to the containment navigation property of the containing entity.
+If the entities are contained, then {entity-collection} is the top-level entity set followed by the path to the containment navigation property of the containing entity.
-Example 31: resource URL and corresponding context URL
+Example 32: resource URL and corresponding context URL
http://host/service/Customers?$deltatoken=1234
http://host/service/$metadata#Customers/$delta
@@ -1589,10 +1594,10 @@ 10.17 Delt
10.18 Item in a Delta Payload
Context URL templates:
-{context-url}#{entity-set}/$deletedEntity
-{context-url}#{entity-set}/$link
-{context-url}#{entity-set}/$deletedLink
-In addition to new or changed entities which have the canonical context URL for an entity, a delta response can contain deleted entities, new links, and deleted links. They are identified by the corresponding context URL fragment. {entity-set} corresponds to the set of the deleted entity, or source entity for an added or deleted link.
+{context-url}#{entity-collection}/$deletedEntity
+{context-url}#{entity-collection}/$link
+{context-url}#{entity-collection}/$deletedLink
+In addition to new or changed entities which have the canonical context URL for an entity, a delta response can contain deleted entities, new links, and deleted links. They are identified by the corresponding context URL fragment. {entity-collection} corresponds to the set of the deleted entity, or source entity for an added or deleted link.
$all Response204 No Content.
If the property is not available, for example due to permissions, the service responds with 404 Not Found.
Example 32:
+Example 33:
GET http://host/service/Products(1)/Name204 No Content response.
If the property or operation result is not available, for example due to permissions, the service responds with 404 Not Found.
Example 33:
+Example 34:
GET http://host/service/Products(1)/Name/$valueThe value of the $select query option is a comma-separated list of paths that end with properties, non-entity-valued instance annotations, qualified action names, or qualified function names, as well as of the star operator (*), or the star operator prefixed with the namespace or alias of the schema in order to specify all operations defined in the schema. Only aliases defined in the metadata document of the service can be used in URLs.
Example 34: request only the Rating and ReleaseDate for the matching Products
Example 35: request only the Rating and ReleaseDate for the matching Products
GET http://host/service/Products?$select=Rating,ReleaseDateIt is also possible to request all structural properties, including any dynamic properties, using the star operator. The star operator SHOULD NOT introduce navigation properties, actions or functions not otherwise requested.
Example 35:
+Example 36:
GET http://host/service/Products?$select=*Properties of related entities can be specified by including the $select query option within the $expand.
Example 36:
+Example 37:
GET http://host/service/Products?$expand=Category($select=Name)The properties specified in $select are represented in addition to any expanded navigation or stream properties. If a navigation property is specified in $select, then the corresponding navigation link is represented in the response. If the navigation property also appears in an $expand query option, then it is additionally represented as inline content.
Example 37: for each category, return the CategoryName and the Products navigation link
Example 38: for each category, return the CategoryName and the Products navigation link
GET http://host/service/Categories?$select=CategoryName,ProductsIt is also possible to request all actions or functions available for each returned entity.
Example 38:
+Example 39:
GET http://host/service/Products?$select=DemoService.*Query options can be applied to a selected property by appending a semicolon-separated list of query options, enclosed in parentheses, to the property. Allowed system query options are $select and $compute for complex properties, plus $filter, $search, $count, $orderby, $skip, and $top for collection-valued properties. A property MUST NOT have select options specified in more than one place in a request and MUST NOT have both select options and expand options specified.
Example 39: for each customer entity within the Customers entity set the value of all related Orders will be represented inline
+Example 40: for each customer entity within the Customers entity set the value of all related Orders will be represented inline
GET http://host/service.svc/Customers?$expand=OrdersExample 40: for each customer entity within the Customers entity set the references to the related Orders will be represented inline
+Example 41: for each customer entity within the Customers entity set the references to the related Orders will be represented inline
GET http://host/service.svc/Customers?$expand=Orders/$refExample 41: for each customer entity within the Customers entity set the media stream representing the customer photo will be represented inline
+Example 42: for each customer entity within the Customers entity set the media stream representing the customer photo will be represented inline
GET http://host/service.svc/Customers?$expand=PhotoThe set of expanded entities can be further refined through the application of expand options, expressed as a semicolon-separated list of system query options, enclosed in parentheses, see OData-URL.
Allowed system query options are $compute, $select, $expand, and $levels for all navigation properties, plus $filter, $orderby, $skip, $top, $count, and $search for collection-valued navigation properties.
Example 42: for each customer entity within the Customers entity set, the value of those related Orders whose Amount is greater than 100 will be represented inline
Example 43: for each customer entity within the Customers entity set, the value of those related Orders whose Amount is greater than 100 will be represented inline
GET http://host/service.svc/Customers?$expand=Orders($filter=Amount gt 100)Example 43: for each order within the Orders entity set, the following will be represented inline:
Example 44: for each order within the Orders entity set, the following will be represented inline:
Items related to the Orders identified by the resource path section of the URL and the products related to each order item.Customer related to each order returned.GET http://host/service.svc/Orders?$expand=Items($expand=Product),CustomerExample 44: for each customer entity in the Customers entity set, the value of all related InHouseStaff will be represented inline if the entity is of type VipCustomer or a subtype of that. For entities that are not of type VipCustomer, or any of its subtypes, that entity may be returned with no inline representation for the expanded navigation property InHouseStaff (the service can always send more than requested)
Example 45: for each customer entity in the Customers entity set, the value of all related InHouseStaff will be represented inline if the entity is of type VipCustomer or a subtype of that. For entities that are not of type VipCustomer, or any of its subtypes, that entity may be returned with no inline representation for the expanded navigation property InHouseStaff (the service can always send more than requested)
GET http://host/service.svc/Customers?$expand=SampleModel.VipCustomer/InHouseStaff$compute system query option allows clients to define computed properties that can be used in a $select or within a $filter or $orderby expression.
Computed properties SHOULD be included as dynamic properties in the result and MUST be included if $select is specified with the computed property name, or star (*).
Example 46: compute total price for order items (line breaks only for readability)
+Example 47: compute total price for order items (line breaks only for readability)
GET http://host/service/Customers
?$filter=Orders/any(o:o/TotalPrice gt 100)
&$expand=Orders($compute=Price mult Qty as TotalPrice
@@ -1876,12 +1881,12 @@
-Example 47: return all Products whose Price is less than $10.00
+Example 48: return all Products whose Price is less than $10.00
GET http://host/service/Products?$filter=Price lt 10.00
The $count segment may be used within a $filter expression to limit the items returned based on the exact count of related entities or items within a collection-valued property.
Example 48: return all Categories with less than 10 products
+Example 49: return all Categories with less than 10 products
GET http://host/service/Categories?$filter=Products/$count lt 10The value of the $filter option is a Boolean expression as defined in OData-ABNF.
$compute, $filter or $orderby expression. Parameters aliases are names beginning with an at sign (@).
Actual parameter values are specified as query options in the query part of the request URL. The query option name is the name of the parameter alias, and the query option value is the value to be used for the specified parameter alias.
Example 49: returns all employees whose Region property matches the string parameter value WA
Example 50: returns all employees whose Region property matches the string parameter value WA
GET http://host/service.svc/Employees?$filter=Region eq @p1&@p1='WA'Parameter aliases allow the same value to be used multiple times in a request and may be used to reference primitive, structured, or collection values.
@@ -1989,7 +1994,7 @@Example 50: returns all employees, expands their manager, and expands all direct reports with the same first name as the manager, using a parameter alias for $this to pass the manager into the filter on the expanded direct reports
Example 51: returns all employees, expands their manager, and expands all direct reports with the same first name as the manager, using a parameter alias for $this to pass the manager into the filter on the expanded direct reports
GET http://host/service.svc/Employees?$expand=Manager(@m=$this;$expand=DirectReports($filter=@m/FirstName eq FirstName))Content-Language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.
Values of type Edm.Stream or any of the Geo types cannot be sorted.
Example 51: return all Products ordered by release date in ascending order, then by rating in descending order
+Example 52: return all Products ordered by release date in ascending order, then by rating in descending order
GET http://host/service/Products?$orderby=ReleaseDate asc, Rating descRelated entities may be ordered by specifying $orderby within the $expand clause.
Example 52: return all Categories, and their Products ordered according to release date and in descending order of rating
+Example 53: return all Categories, and their Products ordered according to release date and in descending order of rating
GET http://host/service/Categories?$expand=Products($orderby=ReleaseDate asc, Rating desc)$count may be used within a $orderby expression to order the returned items according to the exact count of related entities or items within a collection-valued property.
Example 53: return all Categories ordered by the number of Products within each category
+Example 54: return all Categories ordered by the number of Products within each category
GET http://host/service/Categories?$orderby=Products/$count$orderby query option, the service MUST choose a stable ordering across requests that include $top or $skip.
If \(A\) contains more than \(n\) instances, the result of \({\tt \$top}=n\) consists of the first \(n\) instances in \(A\). Otherwise, the result equals \(A\). The instances in the result are in the same order as they occur in \(A\).
Example 54: return only the first five products of the Products entity set
+Example 55: return only the first five products of the Products entity set
GET http://host/service/Products?$top=5$orderby query option, the service MUST choose a stable ordering across requests that include $top or $skip.
If \(A\) contains \(n\) or fewer instances, the result of \({\tt \$skip}=n\) is empty. Otherwise, the first \(n\) instances in \(A\) are omitted from the result and all remaining instances are kept in the same order as they occur in \(A\).
Example 55: return products starting with the 6th product of the Products entity set
Example 56: return products starting with the 6th product of the Products entity set
GET http://host/service/Products?$skip=5Where $top and $skip are used together, $skip MUST be applied before $top, regardless of the order in which they appear in the request.
Example 56: return the third through seventh products of the Products entity set
Example 57: return the third through seventh products of the Products entity set
GET http://host/service/Products?$top=5&$skip=2If no unique ordering is imposed through an $orderby query option, the service MUST impose a stable ordering across requests that include $skip.
Example 57: return, along with the results, the total number of products in the collection
+Example 58: return, along with the results, the total number of products in the collection
GET http://host/service/Products?$count=trueThe count of related entities can be requested by specifying the $count query option within the $expand clause.
Example 58:
+Example 59:
GET http://host/service/Categories?$expand=Products($count=true)A $count query option with a value of false (or not specified) hints that the service SHOULD NOT return a count.
Example 59: return all Products that match the search term bike
Example 60: return all Products that match the search term bike
GET http://host/service/Products?$search=bikeThe search expression can contain phrases, enclosed in double-quotes.
Example 60: return all Products that match the phrase mountain bike
Example 61: return all Products that match the phrase mountain bike
GET http://host/service/Products?$search="mountain bike"The upper-case keyword NOT restricts the set of entities to those that do not match the specified term.
Example 61: return all Products that do not match clothing
Example 62: return all Products that do not match clothing
GET http://host/service/Products?$search=NOT clothingMultiple terms within a search expression are separated by a space (implicit AND) or the upper-case keyword AND, indicating that all such terms must be matched.
Example 62: return all Products that match both mountain and bike
Example 63: return all Products that match both mountain and bike
GET http://host/service/Products?$search=mountain AND bikeThe upper-case keyword OR is used to return entities that satisfy either the immediately preceding or subsequent expression.
Example 63: return all Products that match mountain or bike
Example 64: return all Products that match mountain or bike
GET http://host/service/Products?$search=mountain OR bikeParentheses within the search expression group together multiple expressions.
Example 64: return all Products that match mountain or bike and do not match clothing
Example 65: return all Products that match mountain or bike and do not match clothing
GET http://host/service/Products?$search=(mountain OR bike) AND NOT clothingThe operations within a search expression MUST be evaluated in the following order: grouping operator, NOT operator, AND operator, OR operator
Entities are stably addressable using their canonical URL and are not accessible using an ordinal index.
Example 65: the first address in a list of addresses for MainSupplier
Example 66: the first address in a list of addresses for MainSupplier
GET http://host/service/MainSupplier/Addresses/0If the relationship terminates on a single entity, the response MUST be the format-specific representation of the related single entity. If no entity is related, the service returns 204 No Content.
Example 66: return the supplier of the product with ID=1 in the Products entity set
Example 67: return the supplier of the product with ID=1 in the Products entity set
GET http://host/service/Products(1)/SupplierETag header which represents the identity of the referenced entity. If the resource path terminates in a single-valued navigation path, the ETag value changes if the relationship is changed and points to a different OData entity. If the resource path is the canonical path for a single entity, the returned ETag can never change.
If the resource path terminates on a single entity and no such entity exists, the service returns either 204 No Content or 404 Not Found.
Example 67: collection with an entity reference for each Order related to the Product with ID=0
Example 68: collection with an entity reference for each Order related to the Product with ID=0
GET http://host/service/Products(0)/Orders/$refGET request to the $entity resource located at the URL $entity relative to the service root. The entity-id MUST be specified using the system query option $id.
Example 68: return the entity representation for a given entity-id
+Example 69: return the entity representation for a given entity-id
GET http://host/service/$entity?$id=http://host/service/Products(0)A type segment following the $entity resource casts the resource to the specified type. If the identified entity is not of the specified type, or a type derived from the specified type, the service returns 404 Not Found.
After applying a type-cast segment to cast to a specific type, the system query options $select and $expand can be specified in GET requests to the $entity resource.
Example 69: return the entity representation for a given entity-id and specify properties to return
+Example 70: return the entity representation for a given entity-id and specify properties to return
GET http://host/service/$entity/Model.Customer
?$id=http://host/service/Customers('ALFKI')
&$select=CompanyName,ContactName
@@ -2171,27 +2176,27 @@ $filter or $search system query options, formatted as a simple primitive integer value with media type text/plain. Clients SHOULD NOT combine the system query options $top, $skip, $orderby, $expand, and $format with the path suffix /$count. The result of such a request is undefined.
-Example 70: return the number of products in the Products entity set
+Example 71: return the number of products in the Products entity set
GET http://host/service/Products/$count
With 4.01 services the /$count segment MAY be used in combination with the /$filter path segment to count the items in the filtered collection.
-Example 71: return the number of products whose Price is less than $10.00
+Example 72: return the number of products whose Price is less than $10.00
GET http://host/service/Products/$filter(@foo)/$count?@foo=Price lt 10.00
For backwards compatibility, the /$count suffix MAY be used in combination with the $filter system query option.
-Example 72: return the number of products whose Price is less than $10.00
+Example 73: return the number of products whose Price is less than $10.00
GET http://host/service/Products/$count?$filter=Price lt 10.00
The $filter system query option MUST NOT be used in conjunction with a both a /$count path segment and a /$filter path segment.
The /$count suffix can also be used in path expressions within system query options, e.g. $filter.
-Example 73: return all customers with more than five interests
+Example 74: return all customers with more than five interests
GET http://host/service/Customers?$filter=Interests/$count gt 5
-Example 74: return all categories with more than one product over $5.00
+Example 75: return all categories with more than one product over $5.00
GET http://host/service/Categories?$filter=Products/$filter(Price gt 5.0)/$count gt 1
@@ -2203,12 +2208,12 @@ OData-JSON, but format parameters MUST NOT be appended to the format abbreviations.
-Example 75: the request
+Example 76: the request
GET http://host/service/Orders?$format=application/json;metadata=full
is equivalent to a request with an Accept header using the same media type; it requests the set of Order entities represented using the JSON media type including full metadata, as defined in OData-JSON.
-Example 76: the request
+Example 77: the request
GET http://host/service/Orders?$format=json
is equivalent to a request with the Accept header set to application/json; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in OData-JSON.
@@ -2342,29 +2347,29 @@
-Example 77: using the JSON format, 4.0 clients can create a new manager entity with links to an existing manager (of managers) and to two existing employees by applying the odata.bind annotation to the Manager and DirectReports navigation properties
-{
- "@type": "#Northwind.Manager",
- "ID": 1,
- "FirstName": "Pat",
- "LastName": "Griswold",
- "Manager@odata.bind": "http://host/service/Employees(0)",
- "DirectReports@odata.bind": [
- "http://host/service/Employees(5)",
- "http://host/service/Employees(6)"
- ]
-}
-
Example 78: using the JSON format, 4.01 clients can create a new manager entity with links to an existing manager (of managers) and to two existing employees by including the entity-ids within the Manager and DirectReports navigation properties
Example 78: using the JSON format, 4.0 clients can create a new manager entity with links to an existing manager (of managers) and to two existing employees by applying the odata.bind annotation to the Manager and DirectReports navigation properties
{
"@type": "#Northwind.Manager",
"ID": 1,
"FirstName": "Pat",
"LastName": "Griswold",
- "Manager": { "@id": "Employees(0)" },
- "DirectReports": [{ "@id": "Employees(5)" }, { "@id": "Employees(6)" }]
-}Example 79: using the JSON format, 4.01 clients can create a new manager entity with links to an existing manager (of managers) and to two existing employees by including the entity-ids within the Manager and DirectReports navigation properties
{
+ "@type": "#Northwind.Manager",
+ "ID": 1,
+ "FirstName": "Pat",
+ "LastName": "Griswold",
+ "Manager": { "@id": "Employees(0)" },
+ "DirectReports": [{ "@id": "Employees(5)" }, { "@id": "Employees(6)" }]
+}Upon successful completion of the operation, the service creates the requested entity and relates it to the requested existing entities.
If the target URL for the collection the entity is created in and binding information provided in the POST body contradicts the implicit binding information provided by the request URL, the request MUST fail, and the service responds with 400 Bad Request.
If a navigation property is absent from a PUT or PATCH request payload, the referenced or contained entity, or the collection thereof, remains unchanged by a successful update.
Example 79: using the JSON format, a 4.01 PATCH request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named Suzanne Brown. The LastName of employee 6 is updated to Smith.
{
- "@type": "#Northwind.Manager",
- "FirstName": "Patricia",
- "DirectReports": [
- {
- "@id": "Employees(5)"
- },
- {
- "@id": "Employees(6)",
- "LastName": "Smith"
- },
- {
- "FirstName": "Suzanne",
- "LastName": "Brown"
- }
- ]
-}Example 80: using the JSON format, a 4.01 PATCH request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named Suzanne Brown. The LastName of employee 6 is updated to Smith.
{
+ "@type": "#Northwind.Manager",
+ "FirstName": "Patricia",
+ "DirectReports": [
+ {
+ "@id": "Employees(5)"
+ },
+ {
+ "@id": "Employees(6)",
+ "LastName": "Smith"
+ },
+ {
+ "FirstName": "Suzanne",
+ "LastName": "Brown"
+ }
+ ]
+}If the nested collection is represented as a delta annotation on the navigation property, then the collection contains members to be added or changed and MAY include deleted entities for entities that are no longer part of the collection, using the delta payload format. If the deleted entity specifies a reason as deleted, then the entity is both removed from the collection and deleted, otherwise it is removed from the collection and only deleted if the relationship is contained. Non-key properties of the deleted entity are ignored. Nested collections MUST NOT contain added or deleted links. If the request contains nested delta collections, then the PATCH verb must be specified.
If a nested entity has the same id or key fields as an existing entity, the existing entity is updated according to the semantics of the PUT or PATCH request. Nested entities that have no id or key fields, or for which the id or key fields do not match existing entities, are treated as inserts. If the nested collection does not represent a containment relationship and has no navigation property binding, then such entities MUST include a context URL specifying the entity set in which the new entity is to be created. If any nested entities contain both id and key fields, they MUST identify the same entity, or the request is invalid.
Example 80: using the JSON format, a 4.01 PATCH request can specify a nested delta representation to:
Example 81: using the JSON format, a 4.01 PATCH request can specify a nested delta representation to:
{
- "@type": "#Northwind.Manager",
- "FirstName": "Patricia",
- "DirectReports@delta": [
- {
- "@removed": {
- "reason": "deleted"
- },
- "@id": "Employees(3)"
- },
- {
- "@removed": {
- "reason": "changed"
- },
- "@id": "Employees(4)"
- },
- {
- "@id": "Employees(5)"
- },
- {
- "@id": "Employees(6)",
- "LastName": "Smith"
- },
- {
- "FirstName": "Suzanne",
- "LastName": "Brown"
- }
- ]
-}Example 81: When updating an entity with a 4.01 PUT request, the target of a non-containment navigation property can be replaced if the targeted entity is specified by an entity reference (see OData-JSON, section 14), without specifying all its structural properties in PUT semantics.
{
+ "@type": "#Northwind.Manager",
+ "FirstName": "Patricia",
+ "DirectReports@delta": [
+ {
+ "@removed": {
+ "reason": "deleted"
+ },
+ "@id": "Employees(3)"
+ },
+ {
+ "@removed": {
+ "reason": "changed"
+ },
+ "@id": "Employees(4)"
+ },
+ {
+ "@id": "Employees(5)"
+ },
+ {
+ "@id": "Employees(6)",
+ "LastName": "Smith"
+ },
+ {
+ "FirstName": "Suzanne",
+ "LastName": "Brown"
+ }
+ ]
+}Example 82: When updating an entity with a 4.01 PUT request, the target of a non-containment navigation property can be replaced if the targeted entity is specified by an entity reference (see OData-JSON, section 14), without specifying all its structural properties in PUT semantics.
The following JSON payload changes the name of a category and the products belonging to it. (Compare this to OData-JSON, example 22.) The effect would be the same if the @context was omitted from the request.
Request
-PUT http://host/service/Categories(6)?$expand=Products
-Content-Type: application/json
-
-{
- "Name": "UpdatedCategory",
- "Products": [
- {
- "@context": "$metadata#$ref",
- "@id": "Products(57)"
- }
- ]
-}PUT http://host/service/Categories(6)?$expand=Products
+Content-Type: application/json
+
+{
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "@context": "$metadata#$ref",
+ "@id": "Products(57)"
+ }
+ ]
+}Response
-{
- "@context": "$metadata#Categories/$entity",
- "CategoryID": 6,
- "Name": "UpdatedCategory",
- "Products": [
- {
- "ProductID": 57,
- "Name": "Widgets"
- }
- ]
-}{
+ "@context": "$metadata#Categories/$entity",
+ "CategoryID": 6,
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "ProductID": 57,
+ "Name": "Widgets"
+ }
+ ]
+}If Products was a containment navigation property, the request and response would be the same, except that the @id would likely be relative to the category, for example, Categories(6)/Products(57).
If the targeted entity in the payload contains some structural properties, PUT resets all its other structural properties. The following alternative payload resets the product name. The effect would be the same if the @id was omitted from the request.
PUT http://host/service/Categories(6)?$expand=Products
-Content-Type: application/json
-
-{
- "Name": "UpdatedCategory",
- "Products": [
- {
- "@id": "Products(57)",
- "ProductID": 57
- }
- ]
-}{
- "@context": "$metadata#Categories/$entity",
- "CategoryID": 6,
- "Name": "UpdatedCategory",
- "Products": [
- {
- "ProductID": 57,
- "Name": null
- }
- ]
-}PUT http://host/service/Categories(6)?$expand=Products
+Content-Type: application/json
+
+{
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "@id": "Products(57)",
+ "ProductID": 57
+ }
+ ]
+}{
+ "@context": "$metadata#Categories/$entity",
+ "CategoryID": 6,
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "ProductID": 57,
+ "Name": null
+ }
+ ]
+}Clients MAY associate an id with individual nested entities in the request by using the Core.ContentID term defined in OData-VocCore. Services that respond with 200 OK SHOULD annotate the entities in the response using the same Core.ContentID value as specified in the request. Services SHOULD advertise support for deep updates, including support for returning the Core.ContentID, through the Capabilities.DeepUpdateSupport term, defined in OData-VocCap.
$expand. Instead, the values are generally read or written through URLs.
Example 82: read an entity and select a stream property
+Example 83: read an entity and select a stream property
GET http://host/service/Products(1)?$select=Thumbnailwould only include control information for the stream property, not the stream data itself
-{
- "@context": "http://host/service/$metadata#Products/$entity",
- …
- "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg",
- "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg",
- …
-}{
+ "@context": "http://host/service/$metadata#Products/$entity",
+ …
+ "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg",
+ "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg",
+ …
+}The stream data can then be requested using the media read link:
GET http://server/Thumbnail546.jpgServices SHOULD support direct property access to a stream property’s canonical URL. The response MAY be a redirect to the media read link of the stream property if the media read link is different from the canonical URL.
Example 83: directly read a stream property of an entity
+Example 84: directly read a stream property of an entity
GET http://host/service/Products(1)/Thumbnailcan return 200 OK and the stream data (see section 11.2.4.1), or a 3xx Redirect to the media read link of the stream property.
Example 84: delete the stream value using the media edit link retrieved in example 82
+Example 85: delete the stream value using the media edit link retrieved in example 83
DELETE http://server/uploads/Thumbnail546.jpgAttempting to request a stream property whose value is null results in 204 No Content.
Core.PositionalInsert term (see OData-VocCore) support inserting items at a specific location via POST requests to the collection URL using the $index system query option. The value of the $index system query option is the zero-based ordinal position where the item is to be inserted. The ordinal positions of items within the collection greater than or equal to the inserted position are increased by one. A negative ordinal number indexes from the end of the collection, with -1 representing an insert as the last item in the collection.
Example 85: Insert a new email address at the second position
-POST /service/Customers('ALFKI')/EmailAddresses?$index=1
-Content-Type: application/json
-
-{
- "value": "alfred@futterkiste.de"
-}Example 86: Insert a new email address at the second position
+POST /service/Customers('ALFKI')/EmailAddresses?$index=1
+Content-Type: application/json
+
+{
+ "value": "alfred@futterkiste.de"
+}For collections of structured type, the body of the request MUST be a full or partial representation of an instance of the collection’s structured type. Each member of the potentially filtered collection is updated using PATCH semantics. Structured types MAY include nested collections or delta collections, in which case the semantics described in Update a Collection of Entities applies.
Example 86: change the color of all beige-brown products
-PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
-Content-Type: application/json
-
-{
- "Color": "taupe"
-}Example 87: change the color of all beige-brown products
+PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
+Content-Type: application/json
+
+{
+ "Color": "taupe"
+}The response, if requested, is a collection payload containing the updated representation of each member identified by the request. If the update payload includes nested collections or nested delta collections, then they MUST be included in the response, as described in Update a Collection of Entities.
Clients should note that requesting a response may be expensive for services that could otherwise efficiently apply updates to a (possibly filtered) collection.
@@ -2819,7 +2824,7 @@DELETE request to the URL constructed by appending /$each to the resource path of the collection. The additional path segment expresses that the collection itself is not deleted.
The request resource path of the collection MAY contain type-cast or filter segments to subset the collection.
Example 87: delete all products older than 3
+Example 88: delete all products older than 3
DELETE /service/Products/$filter(Age gt 3)/$eachIf the path identifies a collection of entities and if the service returns a representation, then the response is a delta response containing a representation of a deleted entity for each deleted member.
@@ -2838,25 +2843,25 @@The namespace- or alias-qualified name of a bound operation may be appended to any URL that identifies a resource whose type matches, or is derived from, the type of the binding parameter. The resource identified by that URL is used as the binding parameter value. Only aliases defined in the metadata document of the service can be used in URLs.
Example 88: the function MostRecentOrder can be bound to any URL that identifies a SampleModel.Customer
<Function Name="MostRecentOrder" IsBound="true">
- <Parameter Name="customer" Type="SampleModel.Customer" />
- <ReturnType Type="SampleModel.Order" />
-</Function>Example 89: the function MostRecentOrder can be bound to any URL that identifies a SampleModel.Customer
<Function Name="MostRecentOrder" IsBound="true">
+ <Parameter Name="customer" Type="SampleModel.Customer" />
+ <ReturnType Type="SampleModel.Order" />
+</Function>Example 89: invoke the MostRecentOrder function with the value of the binding parameter customer being the entity identified by http://host/service/Customers(6)
Example 90: invoke the MostRecentOrder function with the value of the binding parameter customer being the entity identified by http://host/service/Customers(6)
GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()Example 90: the function Comparison can be bound to any URL that identifies a collection of entities
<Function Name="Comparison" IsBound="true">
- <Parameter Name="in" Type="Collection(Edm.EntityType)" />
- <ReturnType Type="Diff.Overview" />
-</Function>Example 91: the function Comparison can be bound to any URL that identifies a collection of entities
<Function Name="Comparison" IsBound="true">
+ <Parameter Name="in" Type="Collection(Edm.EntityType)" />
+ <ReturnType Type="Diff.Overview" />
+</Function>Example 91: invoke the Comparison function on the set of red products
Example 92: invoke the Comparison function on the set of red products
GET http://host/service/Products/$filter(Color eq 'Red')/Diff.Comparison()Example 92: invoke the MostRecentOrder function on each entity in the entity set Customers
Example 93: invoke the MostRecentOrder function on each entity in the entity set Customers
GET http://host/service/Customers/$each/SampleModel.MostRecentOrder()The client MAY specify the continue-on-error preference, in which case the service MAY continue processing actions after a failure. In this case, the service MUST, regardless of the return preference, return a response containing at least the members identified by the request for which the action failed. Such members MUST be annotated with the term Core.DataModificationException with a failedOperation value of invoke.
Example 93: given a GET request to http://host/service/Customers('ALFKI'), the service might respond with a Customer that includes the SampleEntities.MostRecentOrder function bound to the entity
{
- "@context": …,
- "CustomerID": "ALFKI",
- "CompanyName": "Alfreds Futterkiste",
- "#SampleEntities.MostRecentOrder": {
- "title": "Most Recent Order",
- "target": "Customers('ALFKI')/SampleEntities.MostRecentOrder()"
- },
- …
-}An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in OData-URL.
-Services can advertise that a function or action is not available for a particular instance by setting its value to null.
-Example 94: the SampleEntities.MostRecentOrder function is not available for customer ALFKI
Example 94: given a GET request to http://host/service/Customers('ALFKI'), the service might respond with a Customer that includes the SampleEntities.MostRecentOrder function bound to the entity
{
"@context": …,
"CustomerID": "ALFKI",
"CompanyName": "Alfreds Futterkiste",
- "#SampleEntities.MostRecentOrder": null,
- …
-}An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in OData-URL.
+Services can advertise that a function or action is not available for a particular instance by setting its value to null.
+Example 95: the SampleEntities.MostRecentOrder function is not available for customer ALFKI
{
+ "@context": …,
+ "CustomerID": "ALFKI",
+ "CompanyName": "Alfreds Futterkiste",
+ "#SampleEntities.MostRecentOrder": null,
+ …
+}If the function is composable, additional path segments may be appended to the URL that identifies the composable function (or function import) as appropriate for the type returned by the function (or function import). The last path segment determines the system query options and HTTP verbs that can be used with this this URL, e.g. if the last path segment is a multi-valued navigation property, a POST request may be used to create a new entity in the identified collection.
Example 95: add a new item to the list of items of the shopping cart returned by the composable MyShoppingCart function import
Example 96: add a new item to the list of items of the shopping cart returned by the composable MyShoppingCart function import
POST http://host/service/MyShoppingCart()/Items
…Example 96: invoke a Sales.EmployeesByManager function which takes a single ManagerID parameter via the function import EmployeesByManager
Example 97: invoke a Sales.EmployeesByManager function which takes a single ManagerID parameter via the function import EmployeesByManager
GET http://host/service/EmployeesByManager(ManagerID=3)Example 97: return all Customers whose City property returns Western when passed to the Sales.SalesRegion function
Example 98: return all Customers whose City property returns Western when passed to the Sales.SalesRegion function
GET http://host/service/Customers?
$filter=Sales.SalesRegion(City=$it/City) eq 'Western'A parameter alias can be used in place of an inline parameter value. The value for the alias is specified as a separate query option using the name of the parameter alias.
Example 98: invoke a Sales.EmployeesByManager function via the function import EmployeesByManager, passing 3 for the ManagerID parameter
Example 99: invoke a Sales.EmployeesByManager function via the function import EmployeesByManager, passing 3 for the ManagerID parameter
GET http://host/service/EmployeesByManager(ManagerID=@p1)?@p1=3Services MAY in addition allow implicit parameter aliases for function imports and for functions that are the last path segment of the URL. An implicit parameter alias is the parameter name, optionally preceded by an at (@) sign. When using implicit parameter aliases, parentheses MUST NOT be appended to the function (import) name. The value for each parameter MUST be specified as a separate query option with the name of the parameter alias. If a parameter name is identical to a system query option name (without the optional $ prefix), the parameter name MUST be prefixed with an at (@) sign.
Example 99: invoke a Sales.EmployeesByManager function via the function import EmployeesByManager, passing 3 for the ManagerID parameter using the implicit parameter alias
Example 100: invoke a Sales.EmployeesByManager function via the function import EmployeesByManager, passing 3 for the ManagerID parameter using the implicit parameter alias
GET http://host/service/EmployeesByManager?ManagerID=3Non-binding parameters annotated with the term Core.OptionalParameter defined in OData-VocCore MAY be omitted. If it is annotated and the annotation specifies a DefaultValue, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter.
204 No Content on success.
To request processing of the action only if the binding parameter value, an entity or collection of entities, is unmodified, the client includes the If-Match header with the latest known ETag value for the entity or collection of entities. The ETag value for a collection as a whole is transported in the ETag header of a collection response.
Example 100: invoke the SampleEntities.CreateOrder action using Customers('ALFKI') as the customer (or binding parameter). The values 2 for the quantity parameter and BLACKFRIDAY for the discountCode parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.
POST http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder
-If-Match: W/"MjAxOS0wMy0yMVQxMzowNVo="
-Content-Type: application/json
-
-{
- "items": [
- { "product": 4001, "quantity": 2 },
- { "product": 7062, "quantity": 1 },
- ],
- "discountCode": "BLACKFRIDAY"
-}Example 101: invoke the SampleEntities.CreateOrder action using Customers('ALFKI') as the customer (or binding parameter). The values 2 for the quantity parameter and BLACKFRIDAY for the discountCode parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.
POST http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder
+If-Match: W/"MjAxOS0wMy0yMVQxMzowNVo="
+Content-Type: application/json
+
+{
+ "items": [
+ { "product": 4001, "quantity": 2 },
+ { "product": 7062, "quantity": 1 },
+ ],
+ "discountCode": "BLACKFRIDAY"
+}Content-Type header specifying a content type of multipart/mixed and a boundary parameter as defined in RFC2046.
Example 101: multipart batch request
+Example 102: multipart batch request
POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.0
@@ -3051,7 +3056,7 @@
-Example 102: JSON batch request
+Example 103: JSON batch request
POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.01
@@ -3078,7 +3083,7 @@ 11.7.4 Referencing Returned Entities
-Entities created by an insert request or an action can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a $ character as the first segment of the request URL. Services MUST treat this segment like the URL in the Location header of the response to the request identified by the segment. If the Location header in the response to the subsequent request contains a relative URL, clients MUST be able to resolve it relative to the request’s URL even if that contains such a reference. See example 107.
+Entities created by an insert request or an action can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a $ character as the first segment of the request URL. Services MUST treat this segment like the URL in the Location header of the response to the request identified by the segment. If the Location header in the response to the subsequent request contains a relative URL, clients MUST be able to resolve it relative to the request’s URL even if that contains such a reference. See example 108.
If the $-prefixed request identifier is identical to the name of a top-level system resource ($batch, $crossjoin, $all, $entity, $root, $id, $metadata, or other system resources defined according to the OData-Version of the protocol specified in the request), then the reference to the top-level system resource is used. This collision can be avoided by e.g. using only numeric request identifiers.
Services MAY also support referencing within request bodies, in which case they SHOULD advertise this support by specifying the ReferencesInRequestBodiesSupported property in the Capabilities.BatchSupport term applied to the entity container, see OData-VocCap.
@@ -3112,25 +3117,25 @@ Absolute URI with schema, host, port, and absolute resource path.
-Example 103:
+Example 104:
GET https://host:1234/path/service/People(1) HTTP/1.1
- Absolute resource path and separate
Host header
-Example 104:
-PATCH /path/service/People(1) HTTP/1.1
-Host: myserver.mydomain.org:1234
-Content-Type: application/json
-
-{ "Name": "Peter" }
+Example 105:
+PATCH /path/service/People(1) HTTP/1.1
+Host: myserver.mydomain.org:1234
+Content-Type: application/json
+
+{ "Name": "Peter" }
- Resource path relative to the batch request URI.
-Example 105:
+Example 106:
DELETE People(1) HTTP/1.1
Services MUST support all three formats for URLs of individual requests.
@@ -3142,7 +3147,7 @@
Processors of batch requests MAY choose to disallow additional HTTP constructs in HTTP requests serialized within body parts. For example, a processor may choose to disallow chunked encoding to be used by such HTTP requests.
-Example 106: a batch request that contains the following individual requests in the order listed
+Example 107: a batch request that contains the following individual requests in the order listed
- A query request
- A change set that contains the following requests:
@@ -3208,7 +3213,7 @@
insert request or an action can be referenced in the request URL of subsequent requests within the same change set. Services MAY also support referencing across change sets, in which case they SHOULD advertise this support by specifying the ReferencesAcrossChangeSetsSupported property in the Capabilities.BatchSupport term applied to the entity container, see OData-VocCap.
-Example 107: a batch request that contains the following operations in the order listed:
+Example 108: a batch request that contains the following operations in the order listed:
A change set that contains the following requests:
- Insert a new entity (with
Content-ID = 1)
@@ -3268,54 +3273,54 @@ example 104). This gives the effective second request URL http://host/service/Customers('ALFKI')/Orders as base URI for the second Location URL, which therefore resolves to http://host/service/Customers('ALFKI')/Orders(1).
+
The second Location URL Orders(1) is relative with its base URI being the second request URL $1/Orders. To get an absolute base URI, the client must replace the $1 with the first Location URL Customers('ALFKI') and resolve the resulting URL Customers('ALFKI')/Orders(1) relative to its base URI, which is http://host/service/Customers (determined from the first request URL /service/Customers and the Host: host header as in example 105). This gives the effective second request URL http://host/service/Customers('ALFKI')/Orders as base URI for the second Location URL, which therefore resolves to http://host/service/Customers('ALFKI')/Orders(1).
11.7.7.3 Referencing an ETag
-Example 108: a batch request that contains the following operations in the order listed:
+Example 109: a batch request that contains the following operations in the order listed:
- Get an employee (with
Content-ID = 1)
- Update the salary only if the employee has not changed
-POST /service/$batch HTTP/1.1
-Host: host
-OData-Version: 4.0
-Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Length: ###
-
---batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Type: application/http
-Content-ID: 1
-
-GET /service/Employees(0) HTTP/1.1
-Host: host
-Accept: application/json
-
-
---batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Type: application/http
-Content-ID: 2
-
-PATCH /service/Employees(0) HTTP/1.1
-Host: host
-Content-Type: application/json
-Content-Length: ###
-If-Match: $1
-
-{
- "Salary": 75000
-}
---batch_36522ad7-fc75-4b56-8c71-56071383e77b--
+POST /service/$batch HTTP/1.1
+Host: host
+OData-Version: 4.0
+Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Length: ###
+
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Type: application/http
+Content-ID: 1
+
+GET /service/Employees(0) HTTP/1.1
+Host: host
+Accept: application/json
+
+
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Type: application/http
+Content-ID: 2
+
+PATCH /service/Employees(0) HTTP/1.1
+Host: host
+Content-Type: application/json
+Content-Length: ###
+If-Match: $1
+
+{
+ "Salary": 75000
+}
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b--
11.7.7.4 Referencing Response Body Values
-Example 109: a batch request that contains the following operations in the order listed:
+Example 110: a batch request that contains the following operations in the order listed:
- Get an employee (with
Content-ID = 1)
- Get all employees residing in the same building
@@ -3364,9 +3369,9 @@ Asynchronously processed batch requests can return interim results and end with a 202 Accepted as the last part of the multipart response. Therefore, the respond-async preference MUST NOT be applied to individual requests within a batch if the batch response is a multipart response.
The body of a multipart response to a JSON batch request contains one body part for each processed or accepted request. The order of the body parts is insignificant as each body part MUST contain the Content-ID header with the value of the id name/value pair of the corresponding request object.
-A response to an operation in a batch MUST be formatted exactly as it would have appeared outside of a batch as described in the corresponding subsections of chapter Data Service Requests. Relative URLs in each individual response are relative to the request URL of the corresponding individual request (see example 107). URLs in responses MUST NOT contain $-prefixed request identifiers.
+A response to an operation in a batch MUST be formatted exactly as it would have appeared outside of a batch as described in the corresponding subsections of chapter Data Service Requests. Relative URLs in each individual response are relative to the request URL of the corresponding individual request (see example 108). URLs in responses MUST NOT contain $-prefixed request identifiers.
-Example 110: referencing the batch request example 106 above, assume all the requests except the final query request succeed. In this case the response would be
+Example 111: referencing the batch request example 107 above, assume all the requests except the final query request succeed. In this case the response would be
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
@@ -3420,7 +3425,7 @@ A service MAY return interim results to an asynchronously executing batch. It does this by responding with 200 OK to a GET request to the monitor resource and including a 202 Accepted response as the last part of the multipart response. The client can use the monitor URL returned in this 202 Accepted response to continue processing the batch response.
Since a change set is executed atomically, 202 Accepted MUST NOT be returned within a change set.
-Example 111: referencing the example 106 above again, assume that
+Example 112: referencing the example 107 above again, assume that
HTTP/1.1 202 Accepted
Location: http://service-root/async-monitor-0
Retry-After: ###
diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index 913347b3..3250d324 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -1999,12 +1999,11 @@ for each category of payload by providing a *context URL template*. The
context URL template uses the following terms:
- `{context-url}` is the canonical
resource path to the `$metadata` document,
-- `{entity-set}` is the name of an entity set [OData-CSDL, section 13.2](https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#EntitySet)
+- `{entity-collection}` is the name of an entity set [OData-CSDL, section 13.2](https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#EntitySet)
or the canonical path to a collection-valued containment navigation property
(implicit entity set [OData-CSDL, section 8.4](https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#ContainmentNavigationProperty)),
-- `{single-entity}` is the name of a singleton or the canonical path to a single-valued containment navigation property,
-- `{entity}` is the canonical URL for an
-entity,
+- `{entity-singleton}` is the name of a singleton or the canonical path to a single-valued containment navigation property,
+- `{entity}` is the canonical URL for an entity within a collection,
- `{select-list}` is an optional
parenthesized comma-separated list of selected properties, instance
annotations, functions, and actions,
@@ -2015,7 +2014,7 @@ path to a structural property of the entity,
segment containing the qualified name of a derived or implemented type
prefixed with a forward slash.
-Key values in the canonical path in `{entity-set}`, `{single-entity}`, and `{entity}` are represented in canonical form
+Key values in the canonical path in `{entity-collection}`, `{entity-singleton}`, and `{entity}` are represented in canonical form
(parentheses-style) without percent-encoding.
The full grammar for the context URL is defined in
@@ -2044,11 +2043,12 @@ http://host/service/$metadata
Context URL template:
- {context-url}#{entity-set}
+ {context-url}#{entity-collection}
{context-url}#Collection({type-name})
-If all entities in the collection are members of one (named or implicit)
-entity set, the context URL fragment is the canonical path `{entity-set}` to the
+If all entities in the collection are members of one
+entity set (including implicit),
+the context URL fragment is the canonical path `{entity-collection}` to the
entity set.
::: example
@@ -2068,8 +2068,8 @@ http://host/service/$metadata#Orders(4711)/Items
```
:::
-If the entities in the response are not bound to a single entity set,
-such as from a function or action with no entity set path, a function
+If the entities in the response are not bound to a single entity set (including
+implicit), such as from a function or action with no entity set path, a function
import or action import with no specified entity set, or a navigation
property with no navigation property binding, the context URL fragment specifies
the type of the returned entity collection.
@@ -2078,13 +2078,12 @@ the type of the returned entity collection.
Context URL template:
- {context-url}#{entity-set}/$entity
- {context-url}#{single-entity}
+ {context-url}#{entity-collection}/$entity
{context-url}#{type-name}
-If a response or response part is an entity of the declared type
-of a (named or implicit) entity set, the context URL fragment is the canonical path
-`{entity-set}` to the entity set with `/$entity` appended.
+If a response or response part is an entity bound to an entity set (including implicit),
+the context URL fragment is the canonical path
+`{entity-collection}` to the entity set with `/$entity` appended.
::: example
Example 13: resource URL and corresponding context URL for named entity set.
@@ -2097,28 +2096,15 @@ http://host/service/$metadata#Customers/$entity
::: example
Example 14: resource URL and corresponding context URL for contained
-entity (implicit entity set)
+entity
```
http://host/service/Orders(4711)/Items(1)
http://host/service/$metadata#Orders(4711)/Items/$entity
```
:::
-If a response or response part is an entity of the declared type of
-a single-valued containment navigation property,
-the context URL fragment is the canonical path `{single-entity}`
-to that navigation property without `/$entity` appended.
-
-::: example
-Example 15: resource URL and corresponding context URL for
-entity targeted by a single-valued containment navigation property
-```
-http://host/service/Orders(4711)/DeliveryAddress
-http://host/service/$metadata#Orders(4711)/DeliveryAddress
-```
-:::
-
-If the entity is not bound to an entity set, such as an entity
+If the entity is within a collection, but its entity set (including implicit)
+cannot be determined, such as for an entity
returned from a function or action with no entity set path, a function
import or action import with no specified entity set, or a navigation
property with no navigation property binding, the context URL fragment specifies
@@ -2128,27 +2114,42 @@ the type `{type-name}` of the returned entity.
Context URL template:
- {context-url}#{single-entity}
+ {context-url}#{entity-singleton}
If a response or response part is a singleton, its name is the context
URL fragment.
::: example
-Example 16: resource URL and corresponding context URL
+Example 15: resource URL and corresponding context URL
```
http://host/service/MainSupplier
http://host/service/$metadata#MainSupplier
```
:::
+If a response or response part is an entity targeted by
+a single-valued containment navigation property,
+the context URL fragment is the canonical path `{entity-singleton}`
+to that navigation property without `/$entity` appended.
+
+::: example
+Example 16: resource URL and corresponding context URL for
+entity targeted by a single-valued containment navigation property
+```
+http://host/service/Orders(4711)/DeliveryAddress
+http://host/service/$metadata#Orders(4711)/DeliveryAddress
+```
+:::
+
## 10.5 Collection of Derived Entities
Context URL template:
- {context-url}#{entity-set}{/type-name}
+ {context-url}#{entity-collection}{/type-name}
-If an entity set consists exclusively of derived entities, a type-cast
-segment is added to the context URL.
+If a response or response part is a collection filtered by a type cast segment
+in the resource URL [OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes),
+the type-cast segment is added to the context URL.
::: example
Example 17: resource URL and corresponding context URL
@@ -2162,28 +2163,38 @@ http://host/service/$metadata#Customers/Model.VipCustomer
Context URL template:
- {context-url}#{entity-set}{/type-name}/$entity
+ {context-url}#{entity-collection}{/type-name}/$entity
+ {context-url}#{entity-singleton}{/type-name}
-If a response or response part is an entity of a type derived from
-the declared type of an entity set, a type-cast segment is appended to
-the entity set name.
+If a response or response part is an entity filtered by a type cast segment
+in the resource URL [OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes),
+the type-cast segment is appended to the `{entity-collection}` or `{entity-singleton}`
+and prior to appending `/$entity`, if any.
::: example
-Example 18: resource URL and corresponding context URL
+Example 18: resource URL with key predicate and corresponding context URL
```
http://host/service/Customers(2)/Model.VipCustomer
http://host/service/$metadata#Customers/Model.VipCustomer/$entity
```
:::
+::: example
+Example 19: resource URL for singleton and corresponding context URL
+```
+http://host/service/MainSupplier/Model.PreferredVendor
+http://host/service/$metadata#MainSupplier/Model.PreferredVendor
+```
+:::
+
## 10.7 Collection of Projected Entities
Context URL templates:
- {context-url}#{entity-set}{/type-name}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}
{context-url}#Collection({type-name}){select-list}
-If a result contains only a subset of properties, the parenthesized
+If a response or response part contains only a subset of properties, the parenthesized
comma-separated list of the selected defined or dynamic properties,
instance annotations, navigation properties, functions, and actions is
appended to the context URL representing the [collection of
@@ -2218,7 +2229,7 @@ entities in the collection, see system query option
[`$select`](#SystemQueryOptionselect).
::: example
-Example 19: resource URL and corresponding context URL
+Example 20: resource URL and corresponding context URL
```
http://host/service/Customers?$select=Address,Orders,Model.VipCustomer/PreferredContact
http://host/service/$metadata#Customers(Address,Orders,Model.VipCustomer/PreferredContact)
@@ -2229,18 +2240,16 @@ http://host/service/$metadata#Customers(Address,Orders,Model.VipCustomer/Preferr
Context URL templates:
- {context-url}#{entity-set}{/type-name}{select-list}/$entity
- {context-url}#{single-entity}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}/$entity
+ {context-url}#{entity-singleton}{/type-name}{select-list}
{context-url}#{type-name}{select-list}
-If an entity contains a subset of properties, the parenthesized
+If a response or response part is an entity that
+contains a subset of properties, the parenthesized
comma-separated list of the selected defined or dynamic properties,
instance annotations, navigation properties, functions, and actions is
-appended to the `{entity-set}` after an optional type-cast segment and
-prior to appending `/$entity`, or to the `{single-entity}`.
-If the response is not a subset of a
-single entity set, the `{select-list}` is instead appended to the
-`{type-name}` of the returned entity.
+appended to the `{entity-collection}` or `{entity-singleton}`
+after an optional type-cast segment and prior to appending `/$entity`, if any.
Regardless of how contained structural properties are represented in the
request URL (as paths or as select options) they are represented in the
@@ -2272,7 +2281,7 @@ returned entity, see system query option
[`$select`](#SystemQueryOptionselect).
::: example
-Example 20: resource URL and corresponding context URL
+Example 21: resource URL and corresponding context URL
```
http://host/service/Customers(1)?$select=Name,Rating
http://host/service/$metadata#Customers(Name,Rating)/$entity
@@ -2283,7 +2292,7 @@ http://host/service/$metadata#Customers(Name,Rating)/$entity
Context URL template:
- {context-url}#{entity-set}{/type-name}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}
{context-url}#Collection({type-name}){select-list}
For a 4.01 response, if a navigation property is explicitly expanded,
@@ -2314,7 +2323,7 @@ Navigation properties with expanded references are not represented in
the context URL.
::: example
-Example 21: resource URL and corresponding context URL --- select and
+Example 22: resource URL and corresponding context URL --- select and
expand
```
http://host/service/Customers?$select=Name&$expand=Address/Country
@@ -2323,7 +2332,7 @@ http://host/service/$metadata#Customers(Name,Address/Country())
:::
::: example
-Example 22: resource URL and corresponding context URL --- expand `$ref`
+Example 23: resource URL and corresponding context URL --- expand `$ref`
```
http://host/service/Customers?$expand=Orders/$ref
http://host/service/$metadata#Customers
@@ -2331,7 +2340,7 @@ http://host/service/$metadata#Customers
:::
::: example
-Example 23: resource URL and corresponding context URL --- expand with
+Example 24: resource URL and corresponding context URL --- expand with
`$levels`
```
http://host/service/Employees/Sales.Manager?$select=DirectReports
@@ -2345,8 +2354,8 @@ http://host/service/$metadata
Context URL template:
- {context-url}#{entity-set}{/type-name}{select-list}/$entity
- {context-url}#{single-entity}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}/$entity
+ {context-url}#{entity-singleton}{/type-name}{select-list}
{context-url}#{type-name}{select-list}
For a 4.01 response, if a navigation property is explicitly expanded,
@@ -2374,7 +2383,7 @@ Navigation properties with expanded references are not represented in
the context URL.
::: example
-Example 24: resource URL and corresponding context URL
+Example 25: resource URL and corresponding context URL
```
http://host/service/Employees(1)/Sales.Manager?
$expand=DirectReports($select=FirstName,LastName;$levels=4)
@@ -2393,7 +2402,7 @@ If a response is a collection of entity references, the context URL does
not contain the type of the referenced entities.
::: example
-Example 25: resource URL and corresponding context URL for a collection
+Example 26: resource URL and corresponding context URL for a collection
of entity references
```
http://host/service/Customers('ALFKI')/Orders/$ref
@@ -2411,7 +2420,7 @@ If a response is one entity reference, `$ref` is the context URL
fragment.
::: example
-Example 26: resource URL and corresponding context URL for a single
+Example 27: resource URL and corresponding context URL for a single
entity reference
```
http://host/service/Orders(10643)/Customer/$ref
@@ -2438,7 +2447,7 @@ navigation properties or operations, OData 4.01 responses MAY use the
less specific second template.
::: example
-Example 27: resource URL and corresponding context URL
+Example 28: resource URL and corresponding context URL
```
http://host/service/Customers(1)/Addresses
http://host/service/$metadata#Customers(1)/Addresses
@@ -2457,7 +2466,7 @@ URL, the context URL specifies the fully qualified type of the
collection.
::: example
-Example 28: resource URL and corresponding context URL
+Example 29: resource URL and corresponding context URL
```
http://host/service/TopFiveHobbies()
http://host/service/$metadata#Collection(Edm.String)
@@ -2475,7 +2484,7 @@ represent an individual property of an entity with a canonical URL, the
context URL specifies the fully qualified type of the result.
::: example
-Example 29: resource URL and corresponding context URL
+Example 30: resource URL and corresponding context URL
```
http://host/service/MostPopularName()
http://host/service/$metadata#Edm.String
@@ -2486,8 +2495,8 @@ http://host/service/$metadata#Edm.String
Context URL templates:
- {context-url}#{entity-set}{/type-name}{select-list}
- {context-url}#{entity-set}{/type-name}{select-list}/$entity
+ {context-url}#{entity-collection}{/type-name}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}/$entity
{context-url}#{entity}/{property-path}{select-list}
{context-url}#Collection({type-name}){select-list}
{context-url}#{type-name}{select-list}
@@ -2501,7 +2510,7 @@ operation. The context URL will correspond to one of the former
examples.
::: example
-Example 30: resource URL and corresponding context URL
+Example 31: resource URL and corresponding context URL
```
http://host/service/TopFiveCustomers()
http://host/service/$metadata#Customers
@@ -2512,7 +2521,7 @@ http://host/service/$metadata#Customers
Context URL template:
- {context-url}#{entity-set}{/type-name}{select-list}/$delta
+ {context-url}#{entity-collection}{/type-name}{select-list}/$delta
{context-url}#{entity}{select-list}/$delta
{context-url}#{entity}/{property-path}{select-list}/$delta
#$delta
@@ -2522,12 +2531,12 @@ URL of the response to the defining query, followed by `/$delta`. This
includes singletons, single-valued navigation properties, and
collection-valued navigation properties.
-If the entities are contained, then `{entity-set}` is the top-level
+If the entities are contained, then `{entity-collection}` is the top-level
entity set followed by the path to the containment navigation property
of the containing entity.
::: example
-Example 31: resource URL and corresponding context URL
+Example 32: resource URL and corresponding context URL
```
http://host/service/Customers?$deltatoken=1234
http://host/service/$metadata#Customers/$delta
@@ -2541,14 +2550,14 @@ is simply the fragment `#$delta`.
Context URL templates:
- {context-url}#{entity-set}/$deletedEntity
- {context-url}#{entity-set}/$link
- {context-url}#{entity-set}/$deletedLink
+ {context-url}#{entity-collection}/$deletedEntity
+ {context-url}#{entity-collection}/$link
+ {context-url}#{entity-collection}/$deletedLink
In addition to new or changed entities which have the canonical context
URL for an entity, a delta response can contain deleted entities, new
links, and deleted links. They are identified by the corresponding
-context URL fragment. `{entity-set}` corresponds to the set of the
+context URL fragment. `{entity-collection}` corresponds to the set of the
deleted entity, or source entity for an added or deleted link.
## 10.19 `$all` Response
@@ -2796,7 +2805,7 @@ If the property is not available, for example due to permissions, the
service responds with [`404 Not Found`](#ResponseCode404NotFound).
::: example
-Example 32:
+Example 33:
```
GET http://host/service/Products(1)/Name
```
@@ -2856,7 +2865,7 @@ If the property or operation result is not available, for example due to permiss
service responds with [`404 Not Found`](#ResponseCode404NotFound).
::: example
-Example 33:
+Example 34:
```
GET http://host/service/Products(1)/Name/$value
```
@@ -2890,7 +2899,7 @@ schema. Only aliases defined in the metadata document of the service can
be used in URLs.
::: example
-Example 34: request only the `Rating` and `ReleaseDate` for the matching
+Example 35: request only the `Rating` and `ReleaseDate` for the matching
Products
```
GET http://host/service/Products?$select=Rating,ReleaseDate
@@ -2903,7 +2912,7 @@ NOT introduce navigation properties, actions or functions not otherwise
requested.
::: example
-Example 35:
+Example 36:
```
GET http://host/service/Products?$select=*
```
@@ -2913,7 +2922,7 @@ Properties of related entities can be specified by including the
`$select` query option within the `$expand`.
::: example
-Example 36:
+Example 37:
```
GET http://host/service/Products?$expand=Category($select=Name)
```
@@ -2927,7 +2936,7 @@ an [`$expand`](#SystemQueryOptionexpand) query option, then it is
additionally represented as inline content.
::: example
-Example 37: for each category, return the `CategoryName` and the
+Example 38: for each category, return the `CategoryName` and the
`Products` navigation link
```
GET http://host/service/Categories?$select=CategoryName,Products
@@ -2938,7 +2947,7 @@ It is also possible to request all actions or functions available for
each returned entity.
::: example
-Example 38:
+Example 39:
```
GET http://host/service/Products?$select=DemoService.*
```
@@ -2988,7 +2997,7 @@ For a full description of the syntax used when building requests, see
[OData-URL, section 5.1.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionexpand).
::: example
-Example 39: for each customer entity within the Customers entity set the
+Example 40: for each customer entity within the Customers entity set the
value of all related Orders will be represented inline
```
GET http://host/service.svc/Customers?$expand=Orders
@@ -2996,7 +3005,7 @@ GET http://host/service.svc/Customers?$expand=Orders
:::
::: example
-Example 40: for each customer entity within the Customers entity set the
+Example 41: for each customer entity within the Customers entity set the
references to the related Orders will be represented inline
```
GET http://host/service.svc/Customers?$expand=Orders/$ref
@@ -3004,7 +3013,7 @@ GET http://host/service.svc/Customers?$expand=Orders/$ref
:::
::: example
-Example 41: for each customer entity within the Customers entity set the
+Example 42: for each customer entity within the Customers entity set the
media stream representing the customer photo will be represented inline
```
GET http://host/service.svc/Customers?$expand=Photo
@@ -3032,7 +3041,7 @@ Allowed system query options are
for collection-valued navigation properties.
::: example
-Example 42: for each customer entity within the `Customers` entity set,
+Example 43: for each customer entity within the `Customers` entity set,
the value of those related `Orders` whose `Amount` is greater than 100
will be represented inline
```
@@ -3041,7 +3050,7 @@ GET http://host/service.svc/Customers?$expand=Orders($filter=Amount gt 100)
:::
::: example
-Example 43: for each order within the `Orders` entity set, the following
+Example 44: for each order within the `Orders` entity set, the following
will be represented inline:
- The `Items` related to
the `Orders` identified by the resource path section of the URL and the
@@ -3053,7 +3062,7 @@ GET http://host/service.svc/Orders?$expand=Items($expand=Product),Customer
:::
::: example
-Example 44: for each customer entity in the Customers entity set, the
+Example 45: for each customer entity in the Customers entity set, the
value of all related InHouseStaff will be represented inline if the
entity is of type VipCustomer or a subtype of that. For entities that
are not of type `VipCustomer`, or any of its subtypes, that entity may
@@ -3083,7 +3092,7 @@ in cases were a circular reference would occur otherwise.
manner. Clients that want to work with 4.0 services MUST use lower case.
::: example
-Example 45: return each employee from the Employees entity set and, for
+Example 46: return each employee from the Employees entity set and, for
each employee that is a manager, return all direct reports, recursively
to four levels
```
@@ -3103,7 +3112,7 @@ result and MUST be included if `$select` is specified with the computed
property name, or star (`*`).
::: example
-Example 46: compute total price for order items (line breaks only for
+Example 47: compute total price for order items (line breaks only for
readability)
```
GET http://host/service/Customers
@@ -3139,7 +3148,7 @@ return [`501 Not Implemented`](#ResponseCode501NotImplemented).
The `$filter` system query option restricts the set of items returned.
::: example
-Example 47: return all Products whose `Price` is less than $10.00
+Example 48: return all Products whose `Price` is less than $10.00
```
GET http://host/service/Products?$filter=Price lt 10.00
```
@@ -3150,7 +3159,7 @@ The [`$count`](#SystemQueryOptioncount) segment may be used within a
count of related entities or items within a collection-valued property.
::: example
-Example 48: return all Categories with less than 10 products
+Example 49: return all Categories with less than 10 products
```
GET http://host/service/Categories?$filter=Products/$count lt 10
```
@@ -3274,7 +3283,7 @@ alias, and the query option value is the value to be used for the
specified parameter alias.
::: example
-Example 49: returns all employees whose Region property matches the
+Example 50: returns all employees whose Region property matches the
string parameter value `WA`
```
GET http://host/service.svc/Employees?$filter=Region eq @p1&@p1='WA'
@@ -3301,7 +3310,7 @@ MAY be nested within `$expand` and
`$select`, in which case they are evaluated relative to the resource context of the `$expand` or `$select`.
::: example
-Example 50: returns all employees, expands their manager, and expands
+Example 51: returns all employees, expands their manager, and expands
all direct reports with the same first name as the manager, using a
parameter alias for `$this` to pass the manager into the filter on the
expanded direct reports
@@ -3348,7 +3357,7 @@ see [OData-VocCore](#ODataVocCore).
Values of type `Edm.Stream` or any of the `Geo` types cannot be sorted.
::: example
-Example 51: return all Products ordered by release date in ascending
+Example 52: return all Products ordered by release date in ascending
order, then by rating in descending order
```
GET http://host/service/Products?$orderby=ReleaseDate asc, Rating desc
@@ -3359,7 +3368,7 @@ Related entities may be ordered by specifying `$orderby` within the
`$expand` clause.
::: example
-Example 52: return all Categories, and their Products ordered according
+Example 53: return all Categories, and their Products ordered according
to release date and in descending order of rating
```
GET http://host/service/Categories?$expand=Products($orderby=ReleaseDate asc, Rating desc)
@@ -3371,7 +3380,7 @@ returned items according to the exact count of related entities or items
within a collection-valued property.
::: example
-Example 53: return all Categories ordered by the number of Products
+Example 54: return all Categories ordered by the number of Products
within each category
```
GET http://host/service/Categories?$orderby=Products/$count
@@ -3394,7 +3403,7 @@ consists of the first $n$ instances in $A$. Otherwise, the result equals $A$.
The instances in the result are in the same order as they occur in $A$.
::: example
-Example 54: return only the first five products of the Products entity
+Example 55: return only the first five products of the Products entity
set
```
GET http://host/service/Products?$top=5
@@ -3418,7 +3427,7 @@ from the result and all remaining instances are kept in the same order as
they occur in $A$.
::: example
-Example 55: return products starting with the 6th product of the
+Example 56: return products starting with the 6th product of the
`Products` entity set
```
GET http://host/service/Products?$skip=5
@@ -3430,7 +3439,7 @@ Where [`$top`](#SystemQueryOptiontop) and `$skip` are used together,
they appear in the request.
::: example
-Example 56: return the third through seventh products of the `Products`
+Example 57: return the third through seventh products of the `Products`
entity set
```
GET http://host/service/Products?$top=5&$skip=2
@@ -3448,7 +3457,7 @@ the total count of items within a collection matching the request be
returned along with the result.
::: example
-Example 57: return, along with the results, the total number of products
+Example 58: return, along with the results, the total number of products
in the collection
```
GET http://host/service/Products?$count=true
@@ -3459,7 +3468,7 @@ The count of related entities can be requested by specifying
the `$count` query option within the `$expand` clause.
::: example
-Example 58:
+Example 59:
```
GET http://host/service/Categories?$expand=Products($count=true)
```
@@ -3491,7 +3500,7 @@ those items *matching* the specified search expression. The definition
of what it means to match is dependent upon the implementation.
::: example
-Example 59: return all Products that match the search term `bike`
+Example 60: return all Products that match the search term `bike`
```
GET http://host/service/Products?$search=bike
```
@@ -3500,7 +3509,7 @@ GET http://host/service/Products?$search=bike
The search expression can contain phrases, enclosed in double-quotes.
::: example
-Example 60: return all Products that match the phrase `mountain bike`
+Example 61: return all Products that match the phrase `mountain bike`
```
GET http://host/service/Products?$search="mountain bike"
```
@@ -3510,7 +3519,7 @@ The upper-case keyword `NOT` restricts the set of entities to those that
do not match the specified term.
::: example
-Example 61: return all Products that do not match `clothing`
+Example 62: return all Products that do not match `clothing`
```
GET http://host/service/Products?$search=NOT clothing
```
@@ -3521,7 +3530,7 @@ Multiple terms within a search expression are separated by a space
such terms must be matched.
::: example
-Example 62: return all Products that match both `mountain` and
+Example 63: return all Products that match both `mountain` and
`bike`
```
GET http://host/service/Products?$search=mountain AND bike
@@ -3532,7 +3541,7 @@ The upper-case keyword `OR` is used to return entities that satisfy
either the immediately preceding or subsequent expression.
::: example
-Example 63: return all Products that match `mountain` or
+Example 64: return all Products that match `mountain` or
`bike`
```
GET http://host/service/Products?$search=mountain OR bike
@@ -3543,7 +3552,7 @@ Parentheses within the search expression group together multiple
expressions.
::: example
-Example 64: return all Products that match `mountain` or
+Example 65: return all Products that match `mountain` or
`bike` and do not match clothing
```
GET http://host/service/Products?$search=(mountain OR bike) AND NOT clothing
@@ -3599,7 +3608,7 @@ Entities are stably addressable using their canonical URL and are not
accessible using an ordinal index.
::: example
-Example 65: the first address in a list of addresses for `MainSupplier`
+Example 66: the first address in a list of addresses for `MainSupplier`
```
GET http://host/service/MainSupplier/Addresses/0
```
@@ -3627,7 +3636,7 @@ entity is related, the service returns
[`204 No Content`](#ResponseCode204NoContent).
::: example
-Example 66: return the supplier of the product with `ID=1` in the
+Example 67: return the supplier of the product with `ID=1` in the
Products entity set
```
GET http://host/service/Products(1)/Supplier
@@ -3666,7 +3675,7 @@ exists, the service returns either
[`404 Not Found`](#ResponseCode404NotFound).
::: example
-Example 67: collection with an entity reference for each Order related
+Example 68: collection with an entity reference for each Order related
to the Product with `ID=0`
```
GET http://host/service/Products(0)/Orders/$ref
@@ -3682,7 +3691,7 @@ the URL `$entity` relative to the service root. The entity-id MUST be
specified using the system query option `$id`.
::: example
-Example 68: return the entity representation for a given entity-id
+Example 69: return the entity representation for a given entity-id
```
GET http://host/service/$entity?$id=http://host/service/Products(0)
```
@@ -3699,7 +3708,7 @@ system query options [`$select`](#SystemQueryOptionselect) and
to the `$entity` resource.
::: example
-Example 69: return the entity representation for a given entity-id and
+Example 70: return the entity representation for a given entity-id and
specify properties to return
```
GET http://host/service/$entity/Model.Customer
@@ -3729,7 +3738,7 @@ SHOULD NOT combine the system query options
The result of such a request is undefined.
::: example
-Example 70: return the number of products in the Products entity set
+Example 71: return the number of products in the Products entity set
```
GET http://host/service/Products/$count
```
@@ -3740,7 +3749,7 @@ the `/$filter` path segment to count the items in the filtered
collection.
::: example
-Example 71: return the number of products whose `Price` is less than
+Example 72: return the number of products whose `Price` is less than
$10.00
```
GET http://host/service/Products/$filter(@foo)/$count?@foo=Price lt 10.00
@@ -3752,7 +3761,7 @@ combination with the [`$filter`](#SystemQueryOptionfilter) system query
option.
::: example
-Example 72: return the number of products whose `Price` is less than
+Example 73: return the number of products whose `Price` is less than
$10.00
```
GET http://host/service/Products/$count?$filter=Price lt 10.00
@@ -3767,14 +3776,14 @@ The `/$count` suffix can also be used in path expressions within system
query options, e.g. [`$filter`](#SystemQueryOptionfilter).
::: example
-Example 73: return all customers with more than five interests
+Example 74: return all customers with more than five interests
```
GET http://host/service/Customers?$filter=Interests/$count gt 5
```
:::
::: example
-Example 74: return all categories with more than one product over $5.00
+Example 75: return all categories with more than one product over $5.00
```
GET http://host/service/Categories?$filter=Products/$filter(Price gt 5.0)/$count gt 1
```
@@ -3797,7 +3806,7 @@ In addition, format-specific abbreviations may be used, e.g. `json` for
MUST NOT be appended to the format abbreviations.
::: example
-Example 75: the request
+Example 76: the request
```
GET http://host/service/Orders?$format=application/json;metadata=full
```
@@ -3809,7 +3818,7 @@ media type including full metadata, as defined in
[OData-JSON](#ODataJSON).
::: example
-Example 76: the request
+Example 77: the request
```
GET http://host/service/Orders?$format=json
```
@@ -4235,7 +4244,7 @@ request body.
The representation for referencing related entities is format-specific.
::: example
-Example 77: using the JSON format, 4.0 clients can create a new manager
+Example 78: using the JSON format, 4.0 clients can create a new manager
entity with links to an existing manager (of managers) and to two existing employees by applying the `odata.bind`
annotation to the `Manager` and `DirectReports` navigation properties
@@ -4256,7 +4265,7 @@ annotation to the `Manager` and `DirectReports` navigation properties
:::
::: example
-Example 78: using the JSON format, 4.01 clients can create a new manager
+Example 79: using the JSON format, 4.01 clients can create a new manager
entity with links to an existing manager (of managers) and to two existing employees by including the entity-ids
within the `Manager` and `DirectReports` navigation properties
@@ -4469,7 +4478,7 @@ If a navigation property is absent from a `PUT` or `PATCH` request payload, the
or contained entity, or the collection thereof, remains unchanged by a successful update.
::: example
-Example 79: using the JSON format, a 4.01 `PATCH` request can update a
+Example 80: using the JSON format, a 4.01 `PATCH` request can update a
manager entity. Following the update, the manager has three direct
reports; two existing employees and one new employee named
`Suzanne Brown`. The `LastName` of employee 6 is updated to `Smith`.
@@ -4519,7 +4528,7 @@ entity is to be created. If any nested entities contain both id and key
fields, they MUST identify the same entity, or the request is invalid.
::: example
-Example 80: using the JSON format, a 4.01 `PATCH` request can specify a
+Example 81: using the JSON format, a 4.01 `PATCH` request can specify a
nested delta representation to:
- delete employee 3 and
@@ -4567,7 +4576,7 @@ nested delta representation to:
:::
::: example
-Example 81: When updating an entity with a 4.01 `PUT` request, the target of a
+Example 82: When updating an entity with a 4.01 `PUT` request, the target of a
non-containment navigation property can be replaced if the targeted entity is specified
by an entity reference (see [OData-JSON, section 14](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#EntityReference)), without specifying all
its structural properties in `PUT` semantics.
@@ -4894,7 +4903,7 @@ payload unless explicitly requested with [`$expand`](#SystemQueryOptionexpand).
Instead, the values are generally read or written through URLs.
::: example
-Example 82: read an entity and select a stream property
+Example 83: read an entity and select a stream property
```
GET http://host/service/Products(1)?$select=Thumbnail
@@ -4925,7 +4934,7 @@ The response MAY be a redirect to the media read link of the stream property
if the media read link is different from the canonical URL.
::: example
-Example 83: directly read a stream property of an entity
+Example 84: directly read a stream property of an entity
```
GET http://host/service/Products(1)/Thumbnail
@@ -4976,7 +4985,7 @@ attempts to set the property to null and results in an error if the
property is non-nullable.
::: example
-Example 84: delete the stream value using the media edit link retrieved in [example 82](#entityWithStreamProperty)
+Example 85: delete the stream value using the media edit link retrieved in [example 83](#entityWithStreamProperty)
```
DELETE http://server/uploads/Thumbnail546.jpg
@@ -5130,7 +5139,7 @@ ordinal number indexes from the end of the collection, with -1
representing an insert as the last item in the collection.
::: example
-Example 85: Insert a new email address at the second position
+Example 86: Insert a new email address at the second position
```json
POST /service/Customers('ALFKI')/EmailAddresses?$index=1
@@ -5292,7 +5301,7 @@ semantics described in [Update a Collection of
Entities](#UpdateaCollectionofEntities) applies.
::: example
-Example 86: change the color of all beige-brown products
+Example 87: change the color of all beige-brown products
```json
PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
@@ -5338,7 +5347,7 @@ The request resource path of the collection MAY contain type-cast or
filter segments to subset the collection.
::: example
-Example 87: delete all products older than 3
+Example 88: delete all products older than 3
```
DELETE /service/Products/$filter(Age gt 3)/$each
@@ -5390,7 +5399,7 @@ by that URL is used as the *binding parameter value*. Only aliases
defined in the metadata document of the service can be used in URLs.
::: example
-Example 88: the function `MostRecentOrder` can be bound to any URL that
+Example 89: the function `MostRecentOrder` can be bound to any URL that
identifies a `SampleModel.Customer`
```xml
@@ -5401,7 +5410,7 @@ identifies a `SampleModel.Customer`
:::
::: example
-Example 89: invoke the `MostRecentOrder` function with the value of the
+Example 90: invoke the `MostRecentOrder` function with the value of the
binding parameter `customer` being the entity identified by
`http://host/service/Customers(6)`
```
@@ -5410,7 +5419,7 @@ GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()
:::
::: example
-Example 90: the function `Comparison` can be bound to any URL that
+Example 91: the function `Comparison` can be bound to any URL that
identifies a collection of entities
```xml
@@ -5421,7 +5430,7 @@ identifies a collection of entities
:::
::: example
-Example 91: invoke the `Comparison` function on the set of red products
+Example 92: invoke the `Comparison` function on the set of red products
```
GET http://host/service/Products/$filter(Color eq 'Red')/Diff.Comparison()
```
@@ -5444,7 +5453,7 @@ result type of the bound operation. If the bound operation returns a
collection, the response is a collection of collections.
::: example
-Example 92: invoke the `MostRecentOrder` function on each entity in the
+Example 93: invoke the `MostRecentOrder` function on each entity in the
entity set `Customers`
```
GET http://host/service/Customers/$each/SampleModel.MostRecentOrder()
@@ -5472,7 +5481,7 @@ or entity collection within the payload. The representation of an action
or function depends on the [format](#Formats).
::: example
-Example 93: given a `GET` request to
+Example 94: given a `GET` request to
`http://host/service/Customers('ALFKI')`, the service might respond with
a Customer that includes the `SampleEntities.MostRecentOrder` function
bound to the entity
@@ -5499,7 +5508,7 @@ Services can advertise that a function or action is not available for a
particular instance by setting its value to null.
::: example
-Example 94: the `SampleEntities.MostRecentOrder` function is not
+Example 95: the `SampleEntities.MostRecentOrder` function is not
available for customer `ALFKI`
```json
{
@@ -5583,7 +5592,7 @@ segment is a multi-valued navigation property, a `POST` request may be
used to create a new entity in the identified collection.
::: example
-Example 95: add a new item to the list of items of the shopping cart
+Example 96: add a new item to the list of items of the shopping cart
returned by the composable `MyShoppingCart` function import
```
POST http://host/service/MyShoppingCart()/Items
@@ -5632,7 +5641,7 @@ Each parameter value is represented as a name/value pair in the format
and `Value` is the parameter value.
::: example
-Example 96: invoke a `Sales.EmployeesByManager` function which takes a
+Example 97: invoke a `Sales.EmployeesByManager` function which takes a
single `ManagerID` parameter via the function import
`EmployeesByManager`
```
@@ -5641,7 +5650,7 @@ GET http://host/service/EmployeesByManager(ManagerID=3)
:::
::: example
-Example 97: return all Customers whose `City` property returns
+Example 98: return all Customers whose `City` property returns
`Western` when passed to the `Sales.SalesRegion` function
```
GET http://host/service/Customers?
@@ -5654,7 +5663,7 @@ parameter value. The value for the alias is specified as a separate
query option using the name of the parameter alias.
::: example
-Example 98: invoke a `Sales.EmployeesByManager` function via the
+Example 99: invoke a `Sales.EmployeesByManager` function via the
function import `EmployeesByManager`, passing 3 for the `ManagerID`
parameter
```
@@ -5674,7 +5683,7 @@ optional `$` prefix), the parameter name MUST be prefixed with an at
(`@`) sign.
::: example
-Example 99: invoke a `Sales.EmployeesByManager` function via the
+Example 100: invoke a `Sales.EmployeesByManager` function via the
function import `EmployeesByManager`, passing 3 for the `ManagerID`
parameter using the implicit parameter alias
```
@@ -5814,7 +5823,7 @@ collection as a whole is transported in the [`ETag`](#HeaderETag) header of a
collection response.
::: example
-Example 100: invoke the `SampleEntities.CreateOrder` action using
+Example 101: invoke the `SampleEntities.CreateOrder` action using
`Customers('ALFKI')` as the customer (or binding parameter). The values
`2` for the `quantity` parameter and `BLACKFRIDAY` for the
`discountCode` parameter are passed in the body of the request. Invoke
@@ -5961,7 +5970,7 @@ format](#MultipartBatchFormat) MUST contain a
[RFC2046](#rfc2046).
::: example
-Example 101: multipart batch request
+Example 102: multipart batch request
```
POST /service/$batch HTTP/1.1
Host: odata.org
@@ -5976,7 +5985,7 @@ A batch request using the JSON batch format MUST contain a
`Content-Type` header specifying a content type of `application/json`.
::: example
-Example 102: JSON batch request
+Example 103: JSON batch request
```
POST /service/$batch HTTP/1.1
Host: odata.org
@@ -6031,7 +6040,7 @@ the request URL. Services MUST treat this segment like the URL in the
[`Location`](#HeaderLocation) header of the response to the request identified by the segment.
If the `Location` header in the response to the subsequent request contains a relative URL,
clients MUST be able to resolve it relative to the request's URL even if
-that contains such a reference. See [example 107](#batchcontentid).
+that contains such a reference. See [example 108](#batchcontentid).
If the `$`-prefixed request identifier is identical to the name of a
top-level system resource (`$batch`, `$crossjoin`, `$all`, `$entity`,
@@ -6132,7 +6141,7 @@ set can use one of the following three formats:
- Absolute URI with schema, host, port, and absolute resource path.
::: example
-Example 103:
+Example 104:
```
GET https://host:1234/path/service/People(1) HTTP/1.1
```
@@ -6141,7 +6150,7 @@ GET https://host:1234/path/service/People(1) HTTP/1.1
- Absolute resource path and separate `Host` header
::: example
-Example 104:
+Example 105:
```json
PATCH /path/service/People(1) HTTP/1.1
Host: myserver.mydomain.org:1234
@@ -6154,7 +6163,7 @@ Content-Type: application/json
- Resource path relative to the batch request URI.
::: example
-Example 105:
+Example 106:
```
DELETE People(1) HTTP/1.1
```
@@ -6179,7 +6188,7 @@ processor may choose to disallow chunked encoding to be used by such
HTTP requests.
::: example
-Example 106: a batch request that contains the following individual
+Example 107: a batch request that contains the following individual
requests in the order listed
1. A query request
@@ -6258,7 +6267,7 @@ which case they SHOULD advertise this support by specifying the
term applied to the entity container, see [OData-VocCap](#ODataVocCap).
::: example
-Example 107: a batch request that contains the following operations in
+Example 108: a batch request that contains the following operations in
the order listed:
A change set that contains the following requests:
@@ -6330,7 +6339,7 @@ request URL `$1/Orders`. To get an absolute base URI, the client must replace th
resulting URL `Customers('ALFKI')/Orders(1)` relative to its base URI, which is
`http://host/service/Customers` (determined from the
first request URL `/service/Customers` and the `Host: host` header
-as in [example 104](#batchhost)). This gives the effective second request URL
+as in [example 105](#batchhost)). This gives the effective second request URL
`http://host/service/Customers('ALFKI')/Orders` as base URI for the second `Location`
URL, which therefore resolves to `http://host/service/Customers('ALFKI')/Orders(1)`.
:::
@@ -6338,7 +6347,7 @@ URL, which therefore resolves to `http://host/service/Customers('ALFKI')/Orders(
#### 11.7.7.3 Referencing an ETag
::: example
-Example 108: a batch request that contains the following operations in
+Example 109: a batch request that contains the following operations in
the order listed:
- Get an employee (with `Content-ID = 1`)
@@ -6379,7 +6388,7 @@ If-Match: $1
#### 11.7.7.4 Referencing Response Body Values
::: example
-Example 109: a batch request that contains the following operations in
+Example 110: a batch request that contains the following operations in
the order listed:
- Get an employee (with `Content-ID = 1`)
@@ -6472,11 +6481,11 @@ A response to an operation in a batch MUST be formatted exactly as it
would have appeared outside of a batch as described in the corresponding
subsections of chapter [Data Service Requests](#DataServiceRequests).
Relative URLs in each individual response are relative to the request
-URL of the corresponding individual request (see [example 107](#batchcontentid)).
+URL of the corresponding individual request (see [example 108](#batchcontentid)).
URLs in responses MUST NOT contain `$`-prefixed request identifiers.
::: example
-Example 110: referencing the batch request [example 106](#batchRequest) above, assume all
+Example 111: referencing the batch request [example 107](#batchRequest) above, assume all
the requests except the final query request succeed. In this case the
response would be
```
@@ -6552,7 +6561,7 @@ Since a change set is executed atomically,
a change set.
::: example
-Example 111: referencing the [example 106](#batchRequest) above again, assume that
+Example 112: referencing the [example 107](#batchRequest) above again, assume that
```
HTTP/1.1 202 Accepted
Location: http://service-root/async-monitor-0
diff --git a/odata-protocol/10 Context URL.md b/odata-protocol/10 Context URL.md
index d408024f..9840f3c3 100644
--- a/odata-protocol/10 Context URL.md
+++ b/odata-protocol/10 Context URL.md
@@ -22,12 +22,11 @@ for each category of payload by providing a *context URL template*. The
context URL template uses the following terms:
- `{context-url}` is the canonical
resource path to the `$metadata` document,
-- `{entity-set}` is the name of an entity set [#OData-CSDL#EntitySet]
+- `{entity-collection}` is the name of an entity set [#OData-CSDL#EntitySet]
or the canonical path to a collection-valued containment navigation property
(implicit entity set [#OData-CSDL#ContainmentNavigationProperty]),
-- `{single-entity}` is the name of a singleton or the canonical path to a single-valued containment navigation property,
-- `{entity}` is the canonical URL for an
-entity,
+- `{entity-singleton}` is the name of a singleton or the canonical path to a single-valued containment navigation property,
+- `{entity}` is the canonical URL for an entity within a collection,
- `{select-list}` is an optional
parenthesized comma-separated list of selected properties, instance
annotations, functions, and actions,
@@ -38,7 +37,7 @@ path to a structural property of the entity,
segment containing the qualified name of a derived or implemented type
prefixed with a forward slash.
-Key values in the canonical path in `{entity-set}`, `{single-entity}`, and `{entity}` are represented in canonical form
+Key values in the canonical path in `{entity-collection}`, `{entity-singleton}`, and `{entity}` are represented in canonical form
(parentheses-style) without percent-encoding.
The full grammar for the context URL is defined in
@@ -67,11 +66,12 @@ http://host/service/$metadata
Context URL template:
- {context-url}#{entity-set}
+ {context-url}#{entity-collection}
{context-url}#Collection({type-name})
-If all entities in the collection are members of one (named or implicit)
-entity set, the context URL fragment is the canonical path `{entity-set}` to the
+If all entities in the collection are members of one
+entity set (including implicit),
+the context URL fragment is the canonical path `{entity-collection}` to the
entity set.
::: example
@@ -91,8 +91,8 @@ http://host/service/$metadata#Orders(4711)/Items
```
:::
-If the entities in the response are not bound to a single entity set,
-such as from a function or action with no entity set path, a function
+If the entities in the response are not bound to a single entity set (including
+implicit), such as from a function or action with no entity set path, a function
import or action import with no specified entity set, or a navigation
property with no navigation property binding, the context URL fragment specifies
the type of the returned entity collection.
@@ -101,13 +101,12 @@ the type of the returned entity collection.
Context URL template:
- {context-url}#{entity-set}/$entity
- {context-url}#{single-entity}
+ {context-url}#{entity-collection}/$entity
{context-url}#{type-name}
-If a response or response part is an entity of the declared type
-of a (named or implicit) entity set, the context URL fragment is the canonical path
-`{entity-set}` to the entity set with `/$entity` appended.
+If a response or response part is an entity bound to an entity set (including implicit),
+the context URL fragment is the canonical path
+`{entity-collection}` to the entity set with `/$entity` appended.
::: example
Example ##ex: resource URL and corresponding context URL for named entity set.
@@ -120,28 +119,15 @@ http://host/service/$metadata#Customers/$entity
::: example
Example ##ex: resource URL and corresponding context URL for contained
-entity (implicit entity set)
+entity
```
http://host/service/Orders(4711)/Items(1)
http://host/service/$metadata#Orders(4711)/Items/$entity
```
:::
-If a response or response part is an entity of the declared type of
-a single-valued containment navigation property,
-the context URL fragment is the canonical path `{single-entity}`
-to that navigation property without `/$entity` appended.
-
-::: example
-Example ##ex: resource URL and corresponding context URL for
-entity targeted by a single-valued containment navigation property
-```
-http://host/service/Orders(4711)/DeliveryAddress
-http://host/service/$metadata#Orders(4711)/DeliveryAddress
-```
-:::
-
-If the entity is not bound to an entity set, such as an entity
+If the entity is within a collection, but its entity set (including implicit)
+cannot be determined, such as for an entity
returned from a function or action with no entity set path, a function
import or action import with no specified entity set, or a navigation
property with no navigation property binding, the context URL fragment specifies
@@ -151,7 +137,7 @@ the type `{type-name}` of the returned entity.
Context URL template:
- {context-url}#{single-entity}
+ {context-url}#{entity-singleton}
If a response or response part is a singleton, its name is the context
URL fragment.
@@ -164,14 +150,29 @@ http://host/service/$metadata#MainSupplier
```
:::
+If a response or response part is an entity targeted by
+a single-valued containment navigation property,
+the context URL fragment is the canonical path `{entity-singleton}`
+to that navigation property without `/$entity` appended.
+
+::: example
+Example ##ex: resource URL and corresponding context URL for
+entity targeted by a single-valued containment navigation property
+```
+http://host/service/Orders(4711)/DeliveryAddress
+http://host/service/$metadata#Orders(4711)/DeliveryAddress
+```
+:::
+
## ##subsec Collection of Derived Entities
Context URL template:
- {context-url}#{entity-set}{/type-name}
+ {context-url}#{entity-collection}{/type-name}
-If an entity set consists exclusively of derived entities, a type-cast
-segment is added to the context URL.
+If a response or response part is a collection filtered by a type cast segment
+in the resource URL [#OData-URL#AddressingDerivedTypes],
+the type-cast segment is added to the context URL.
::: example
Example ##ex: resource URL and corresponding context URL
@@ -185,28 +186,38 @@ http://host/service/$metadata#Customers/Model.VipCustomer
Context URL template:
- {context-url}#{entity-set}{/type-name}/$entity
+ {context-url}#{entity-collection}{/type-name}/$entity
+ {context-url}#{entity-singleton}{/type-name}
-If a response or response part is an entity of a type derived from
-the declared type of an entity set, a type-cast segment is appended to
-the entity set name.
+If a response or response part is an entity filtered by a type cast segment
+in the resource URL [#OData-URL#AddressingDerivedTypes],
+the type-cast segment is appended to the `{entity-collection}` or `{entity-singleton}`
+and prior to appending `/$entity`, if any.
::: example
-Example ##ex: resource URL and corresponding context URL
+Example ##ex: resource URL with key predicate and corresponding context URL
```
http://host/service/Customers(2)/Model.VipCustomer
http://host/service/$metadata#Customers/Model.VipCustomer/$entity
```
:::
+::: example
+Example ##ex: resource URL for singleton and corresponding context URL
+```
+http://host/service/MainSupplier/Model.PreferredVendor
+http://host/service/$metadata#MainSupplier/Model.PreferredVendor
+```
+:::
+
## ##subsec Collection of Projected Entities
Context URL templates:
- {context-url}#{entity-set}{/type-name}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}
{context-url}#Collection({type-name}){select-list}
-If a result contains only a subset of properties, the parenthesized
+If a response or response part contains only a subset of properties, the parenthesized
comma-separated list of the selected defined or dynamic properties,
instance annotations, navigation properties, functions, and actions is
appended to the context URL representing the [collection of
@@ -252,18 +263,16 @@ http://host/service/$metadata#Customers(Address,Orders,Model.VipCustomer/Preferr
Context URL templates:
- {context-url}#{entity-set}{/type-name}{select-list}/$entity
- {context-url}#{single-entity}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}/$entity
+ {context-url}#{entity-singleton}{/type-name}{select-list}
{context-url}#{type-name}{select-list}
-If an entity contains a subset of properties, the parenthesized
+If a response or response part is an entity that
+contains a subset of properties, the parenthesized
comma-separated list of the selected defined or dynamic properties,
instance annotations, navigation properties, functions, and actions is
-appended to the `{entity-set}` after an optional type-cast segment and
-prior to appending `/$entity`, or to the `{single-entity}`.
-If the response is not a subset of a
-single entity set, the `{select-list}` is instead appended to the
-`{type-name}` of the returned entity.
+appended to the `{entity-collection}` or `{entity-singleton}`
+after an optional type-cast segment and prior to appending `/$entity`, if any.
Regardless of how contained structural properties are represented in the
request URL (as paths or as select options) they are represented in the
@@ -306,7 +315,7 @@ http://host/service/$metadata#Customers(Name,Rating)/$entity
Context URL template:
- {context-url}#{entity-set}{/type-name}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}
{context-url}#Collection({type-name}){select-list}
For a 4.01 response, if a navigation property is explicitly expanded,
@@ -368,8 +377,8 @@ http://host/service/$metadata
Context URL template:
- {context-url}#{entity-set}{/type-name}{select-list}/$entity
- {context-url}#{single-entity}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}/$entity
+ {context-url}#{entity-singleton}{/type-name}{select-list}
{context-url}#{type-name}{select-list}
For a 4.01 response, if a navigation property is explicitly expanded,
@@ -509,8 +518,8 @@ http://host/service/$metadata#Edm.String
Context URL templates:
- {context-url}#{entity-set}{/type-name}{select-list}
- {context-url}#{entity-set}{/type-name}{select-list}/$entity
+ {context-url}#{entity-collection}{/type-name}{select-list}
+ {context-url}#{entity-collection}{/type-name}{select-list}/$entity
{context-url}#{entity}/{property-path}{select-list}
{context-url}#Collection({type-name}){select-list}
{context-url}#{type-name}{select-list}
@@ -535,7 +544,7 @@ http://host/service/$metadata#Customers
Context URL template:
- {context-url}#{entity-set}{/type-name}{select-list}/$delta
+ {context-url}#{entity-collection}{/type-name}{select-list}/$delta
{context-url}#{entity}{select-list}/$delta
{context-url}#{entity}/{property-path}{select-list}/$delta
#$delta
@@ -545,7 +554,7 @@ URL of the response to the defining query, followed by `/$delta`. This
includes singletons, single-valued navigation properties, and
collection-valued navigation properties.
-If the entities are contained, then `{entity-set}` is the top-level
+If the entities are contained, then `{entity-collection}` is the top-level
entity set followed by the path to the containment navigation property
of the containing entity.
@@ -564,14 +573,14 @@ is simply the fragment `#$delta`.
Context URL templates:
- {context-url}#{entity-set}/$deletedEntity
- {context-url}#{entity-set}/$link
- {context-url}#{entity-set}/$deletedLink
+ {context-url}#{entity-collection}/$deletedEntity
+ {context-url}#{entity-collection}/$link
+ {context-url}#{entity-collection}/$deletedLink
In addition to new or changed entities which have the canonical context
URL for an entity, a delta response can contain deleted entities, new
links, and deleted links. They are identified by the corresponding
-context URL fragment. `{entity-set}` corresponds to the set of the
+context URL fragment. `{entity-collection}` corresponds to the set of the
deleted entity, or source entity for an added or deleted link.
## ##subsec `$all` Response