From d3177e0b009ab58818d56a4ed3912eaf0ea6f67e Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 6 Nov 2024 18:30:07 +0100 Subject: [PATCH 1/8] Allow nulls in returned collections of entities (#2023) Fixes #1983 --- docs/odata-csdl-json/odata-csdl-json.html | 16 ++++++++++------ docs/odata-csdl-json/odata-csdl-json.md | 6 ++---- docs/odata-csdl-xml/odata-csdl-xml.html | 16 ++++++++++------ docs/odata-csdl-xml/odata-csdl-xml.md | 6 ++---- odata-csdl/1 Introduction.md | 1 + odata-csdl/12 Action and Function.md | 10 ++-------- 6 files changed, 27 insertions(+), 28 deletions(-) diff --git a/docs/odata-csdl-json/odata-csdl-json.html b/docs/odata-csdl-json/odata-csdl-json.html index e05c7694..ae26a175 100644 --- a/docs/odata-csdl-json/odata-csdl-json.html +++ b/docs/odata-csdl-json/odata-csdl-json.html @@ -464,26 +464,31 @@

348 +Section 12.8 +Returned collections of entities may contain null values +1983 + + Section 14.3.13 Constant Geo values in annotations 654 - + Section 14.3.14 Constant Stream values in annotations 654 - + Section 14.4.1.2 New path evaluation rules for annotations targeting annotations and external targeting via container 575 - + Section 14.4.7 Nested If without else part in collections 326 - + Section 17 Additional conformance clauses for version 4.02 @@ -2011,8 +2016,7 @@

$Type and $Nullable

The value of $Nullable is one of the Boolean literals true or false. Absence of the member means false.

-

If the return type is a collection of entity types, the $Nullable member has no meaning and MUST NOT be specified.

-

For other collection-valued return types the result will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values.

+

For collection-valued return types the result will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values.

For single-valued return types the value true means that the action or function MAY return a single null value. The value false means that the action or function will never return a null value and instead will fail with an error response if it cannot compute a result.

Annotation Core.IsDelta

diff --git a/docs/odata-csdl-json/odata-csdl-json.md b/docs/odata-csdl-json/odata-csdl-json.md index a4cf256b..d4a61451 100644 --- a/docs/odata-csdl-json/odata-csdl-json.md +++ b/docs/odata-csdl-json/odata-csdl-json.md @@ -268,6 +268,7 @@ Section | Feature / Change | Issue [Section 3.4.5](#SRID)| SRID value `variable` is deprecated| [1935](https://github.com/oasis-tcs/odata-specs/issues/1935) [Section 4](#CSDLJSONDocument) | Additional `$Version` value `4.02` | [Section 12](#ActionandFunction) | Actions and functions can take, and return, delta payloads | [348](https://github.com/oasis-tcs/odata-specs/issues/348) +[Section 12.8](#ReturnType) | Returned collections of entities may contain `null` values | [1983](https://github.com/oasis-tcs/odata-specs/issues/1983) [Section 14.3.13](#GeoValues) | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.3.14](#StreamValues) | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [575](https://github.com/oasis-tcs/odata-specs/issues/575) @@ -2895,10 +2896,7 @@ Absence of the `$Type` member means the type is `Edm.String`. The value of `$Nullable` is one of the Boolean literals `true` or `false`. Absence of the member means `false`. -If the return type is a collection of entity types, the `$Nullable` -member has no meaning and MUST NOT be specified. - -For other collection-valued return types the result will always be a +For collection-valued return types the result will always be a collection that MAY be empty. In this case `$Nullable` applies to items of the collection and specifies whether the collection MAY contain `null` values. diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html index 14978ace..e934cf6b 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.html +++ b/docs/odata-csdl-xml/odata-csdl-xml.html @@ -468,26 +468,31 @@

348 +Section 12.8 +Returned collections of entities may contain null values +1983 + + Section 14.3.13 Constant Geo values in annotations 654 - + Section 14.3.14 Constant Stream values in annotations 654 - + Section 14.4.1.2 New path evaluation rules for annotations targeting annotations and external targeting via container 575 - + Section 14.4.7 Nested If without else part in collections 326 - + Section 17 Additional conformance clauses for version 4.02 @@ -1897,8 +1902,7 @@

Attribute TypeFor collection-valued return types the value of Type is the character sequence Collection( followed by the qualified name of the return item type, followed by a closing parenthesis ).

Attribute Nullable

The value of Nullable is one of the Boolean literals true or false. Absence of the attribute means true.

-

If the return type is a collection of entity types, the Nullable attribute has no meaning and MUST NOT be specified.

-

For other collection-valued return types the result will always be a collection that MAY be empty. In this case the Nullable attribute applies to items of the collection and specifies whether the collection MAY contain null values.

+

For collection-valued return types the result will always be a collection that MAY be empty. In this case the Nullable attribute applies to items of the collection and specifies whether the collection MAY contain null values.

For single-valued return types the value true means that the action or function MAY return a single null value. The value false means that the action or function will never return a null value and instead will fail with an error response if it cannot compute a result.

Annotation Core.IsDelta

diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md index 1e4fa24a..12d4e497 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.md +++ b/docs/odata-csdl-xml/odata-csdl-xml.md @@ -269,6 +269,7 @@ Section | Feature / Change | Issue [Section 4](#CSDLXMLDocument) | Additional `Version` value `4.02` | [Section 13](#EntityContainer)| All children of `edm:EntityContainer` are optional| [464](https://github.com/oasis-tcs/odata-specs/issues/464) [Section 12](#ActionandFunction) | Actions and functions can take, and return, delta payloads | [348](https://github.com/oasis-tcs/odata-specs/issues/348) +[Section 12.8](#ReturnType) | Returned collections of entities may contain `null` values | [1983](https://github.com/oasis-tcs/odata-specs/issues/1983) [Section 14.3.13](#GeoValues) | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.3.14](#StreamValues) | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [575](https://github.com/oasis-tcs/odata-specs/issues/575) @@ -2772,10 +2773,7 @@ type, followed by a closing parenthesis `)`. The value of `Nullable` is one of the Boolean literals `true` or `false`. Absence of the attribute means `true`. -If the return type is a collection of entity types, the `Nullable` -attribute has no meaning and MUST NOT be specified. - -For other collection-valued return types the result will always be a +For collection-valued return types the result will always be a collection that MAY be empty. In this case the `Nullable` attribute applies to items of the collection and specifies whether the collection MAY contain `null` values. diff --git a/odata-csdl/1 Introduction.md b/odata-csdl/1 Introduction.md index 9bdb1481..3aa65bc7 100644 --- a/odata-csdl/1 Introduction.md +++ b/odata-csdl/1 Introduction.md @@ -47,6 +47,7 @@ All children of `edm:EntityContainer` are optional| [464](https://github.com/oasis-tcs/odata-specs/issues/464) : [Section ##ActionandFunction] | Actions and functions can take, and return, delta payloads | [348](https://github.com/oasis-tcs/odata-specs/issues/348) +[Section ##ReturnType] | Returned collections of entities may contain `null` values | [1983](https://github.com/oasis-tcs/odata-specs/issues/1983) [Section ##GeoValues] | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section ##StreamValues] | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section ##PathEvaluation]| diff --git a/odata-csdl/12 Action and Function.md b/odata-csdl/12 Action and Function.md index deea8a82..23358fb3 100644 --- a/odata-csdl/12 Action and Function.md +++ b/odata-csdl/12 Action and Function.md @@ -276,10 +276,7 @@ Absence of the `$Type` member means the type is `Edm.String`. The value of `$Nullable` is one of the Boolean literals `true` or `false`. Absence of the member means `false`. -If the return type is a collection of entity types, the `$Nullable` -member has no meaning and MUST NOT be specified. - -For other collection-valued return types the result will always be a +For collection-valued return types the result will always be a collection that MAY be empty. In this case `$Nullable` applies to items of the collection and specifies whether the collection MAY contain `null` values. @@ -314,10 +311,7 @@ type, followed by a closing parenthesis `)`. The value of `Nullable` is one of the Boolean literals `true` or `false`. Absence of the attribute means `true`. -If the return type is a collection of entity types, the `Nullable` -attribute has no meaning and MUST NOT be specified. - -For other collection-valued return types the result will always be a +For collection-valued return types the result will always be a collection that MAY be empty. In this case the `Nullable` attribute applies to items of the collection and specifies whether the collection MAY contain `null` values. From 5096493c2808de6042b8d0edf0f56b25ef727670 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Wed, 6 Nov 2024 18:35:34 +0100 Subject: [PATCH 2/8] Use deep links in cross-spec references (#2014) The [OData-Protocol] spec references the two [OData-CSDL] specs (JSON and XML format) as two entries with separate hyperlinks. This is useful for text like https://github.com/oasis-tcs/odata-specs/blob/9439daa138217848097520383d302985ac47666c/odata-protocol/1%20Introduction.md?plain=1#L16-L20 All other specs reference the two [OData-CSDL] specs as one, see https://github.com/oasis-tcs/odata-specs/compare/HEAD..9439daa138217848097520383d302985ac47666c#diff-db5ad1be4d39d16383ddb159ad2e1168888539f3a62b9bdd79b7e72189e446bb. --------- Co-authored-by: Ralf Handl --- docs/odata-csdl-json/odata-csdl-json.html | 44 +++++----- docs/odata-csdl-json/odata-csdl-json.md | 50 ++++++----- docs/odata-csdl-xml/odata-csdl-xml.html | 28 +++--- docs/odata-csdl-xml/odata-csdl-xml.md | 32 +++---- .../odata-data-aggregation-ext.html | 6 +- .../odata-data-aggregation-ext.md | 6 +- docs/odata-json-format/odata-json-format.html | 63 ++++++------- docs/odata-json-format/odata-json-format.md | 70 +++++++-------- docs/odata-protocol/odata-protocol.html | 85 +++++++++--------- docs/odata-protocol/odata-protocol.md | 88 ++++++++++--------- .../odata-temporal-ext.html | 12 +-- docs/odata-temporal-ext/odata-temporal-ext.md | 12 +-- .../odata-url-conventions.html | 40 ++++----- .../odata-url-conventions.md | 50 +++++------ odata-csdl/1 Introduction.md | 2 +- odata-csdl/14 Vocabulary and Annotation.md | 26 +++--- odata-csdl/4 CSDL Document.md | 4 +- odata-csdl/5 Schema.md | 6 +- odata-csdl/7 Structural Property.md | 4 +- odata-csdl/9 Complex Type.md | 2 +- odata-csdl/Appendix.md | 6 +- .../4 Cross-Joins and Aggregation.md | 2 +- .../5 Vocabulary for Data Aggregation.md | 2 +- odata-data-aggregation-ext/8 Conformance.md | 2 +- odata-json-format/10 Media Entity.md | 4 +- odata-json-format/15 Delta Payload.md | 4 +- odata-json-format/16 Bound Function.md | 6 +- .../19 Batch Requests and Responses.md | 10 +-- odata-json-format/20 Instance Annotations.md | 4 +- odata-json-format/23 Conformance.md | 2 +- odata-json-format/4 Common Characteristics.md | 28 +++--- odata-json-format/5 Service Document.md | 7 +- odata-json-format/7 Structural Property.md | 3 +- odata-json-format/Appendix.md | 2 +- odata-protocol/1 Introduction.md | 8 +- odata-protocol/10 Context URL.md | 4 +- odata-protocol/11 Data Service Requests.md | 16 ++-- odata-protocol/11.4 Data Modification.md | 11 +-- odata-protocol/11.5 Operations.md | 10 +-- odata-protocol/11.7 Batch Requests.md | 2 +- odata-protocol/12 Conformance.md | 30 +++---- odata-protocol/8 Header Fields.md | 4 +- odata-protocol/Appendix.md | 3 +- .../4.3 Modifying Temporal Data.md | 10 +-- odata-temporal-ext/Appendix.md | 2 +- odata-url-conventions/1 Introduction.md | 2 +- odata-url-conventions/4 Resource Path.md | 20 ++--- odata-url-conventions/5 Query Options.md | 28 +++--- odata-vocabularies/Appendix.md | 2 +- 49 files changed, 432 insertions(+), 432 deletions(-) diff --git a/docs/odata-csdl-json/odata-csdl-json.html b/docs/odata-csdl-json/odata-csdl-json.html index ae26a175..e4dfd831 100644 --- a/docs/odata-csdl-json/odata-csdl-json.html +++ b/docs/odata-csdl-json/odata-csdl-json.html @@ -818,7 +818,7 @@

3.4.1 MaxLengthType Facet Members

$MaxLength

The value of $MaxLength is a positive integer.

-

Note: OData-CSDL-XML defines a symbolic value max that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the service or omit the member entirely.

+

Note: OData-CSDLXML, section 3.4.1 defines a symbolic value max that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the service or omit the member entirely.

@@ -1014,7 +1014,7 @@

4.1 Reference

A reference to an external CSDL document allows to bring part of the referenced document’s content into the scope of the referencing document.

A reference MUST specify a URI that uniquely identifies the referenced document, so two references MUST NOT specify the same URI. The URI SHOULD be a URL that locates the referenced document. If the URI is not dereferencable it SHOULD identify a well-known schema. The URI MAY be absolute or relative URI; relative URLs are relative to the URL of the document containing the reference, or relative to a base URL specified in a format-specific way.

A reference MAY be annotated.

-

The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined OData-Protocol, SHOULD be used when retrieving the referenced schema document.

+

The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined in OData-Protocol, section 11.2.12, SHOULD be used when retrieving the referenced schema document.

$Reference

The value of $Reference is an object that contains one member per referenced CSDL document. The name of the pair is a URI for the referenced document. The URI MAY be relative to the document containing the $Reference. The value of each member is a reference object.

@@ -1295,7 +1295,7 @@

6.3 O

An entity type MAY indicate that it is open and allows clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type.

An entity type derived from an open entity type MUST indicate that it is also open.

-

Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol.

+

Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol, section 3.

$OpenType

The value of $OpenType is one of the Boolean literals true or false. Absence of the member means false.

@@ -1304,7 +1304,7 @@

$OpenType

6.4 Media Entity Type

 -

An entity type that does not specify a base type MAY indicate that it is a media entity type. Media entities are entities that represent a media stream, such as a photo. Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just additional structured information attached to the stream. Use a normal entity with one or more properties of type Edm.Stream if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see OData-Protocol.

+

An entity type that does not specify a base type MAY indicate that it is a media entity type. Media entities are entities that represent a media stream, such as a photo. Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just additional structured information attached to the stream. Use a normal entity with one or more properties of type Edm.Stream if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see OData-Protocol, section 11.2.3.

An entity type derived from a media entity type MUST indicate that it is also a media entity type.

Media entity types MAY specify a list of acceptable media types using an annotation with term Core.AcceptableMediaTypes, see OData-VocCore.

@@ -1335,7 +1335,7 @@

6.5 Key

  • Edm.String
  • Edm.TimeOfDay
    • -

    Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in OData-Protocol) MUST be language independent.

    +

    Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in OData-Protocol, section 4.1) MUST be language independent.

    A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable single-valued complex properties, recursively.

    In OData 4.01 the key properties of a directly related entity type MAY also be part of the key if the navigation property is single-valued and not nullable. This includes navigation properties of non-nullable single-valued complex properties (recursively) of the entity type. If a key property of a related entity type is part of the key, all key properties of the related entity type MUST also be part of the key.

    If the key property is a property of a complex property (recursively) or of a directly related entity type, the key MUST specify an alias for that property that MUST be a simple identifier and MUST be unique within the set of aliases, structural and navigation properties of the declaring entity type and any of its base types.

    @@ -1490,7 +1490,7 @@

    7.3 Default

    If no value is specified, the client SHOULD NOT assume a default value.

    $DefaultValue

    -

    The value of $DefaultValue is the type-specific JSON representation of the default value of the property, see OData-JSON. For properties of type Edm.Decimal and Edm.Int64 the representation depends on the media type parameter IEEE754Compatible.

    +

    The value of $DefaultValue is the type-specific JSON representation of the default value of the property, see OData-JSON, section 7.1. For properties of type Edm.Decimal and Edm.Int64 the representation depends on the media type parameter IEEE754Compatible.

    @@ -1583,7 +1583,7 @@

    OData-URL.

    +

    Instances of the structured type that declares the navigation property, either directly or indirectly via a property of complex type, contain the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see OData-URL, section 4.3.2.

    Entity types used in collection-valued containment navigation properties MUST have a key defined.

    For items of an ordered collection of complex types (those annotated with the Core.Ordered term defined in OData-VocCore the canonical URL of the item is the canonical URL of the collection appended with a segment containing the zero-based ordinal of the item. Items within in an unordered collection of complex types do not have a canonical URL. Services that support unordered collections of complex types declaring a containment navigation property, either directly or indirectly via a property of complex type, MUST specify the URL for the navigation link within a payload representing that item, according to format-specific rules.

    OData 4.0 responses MUST NOT specify a complex type declaring a containment navigation property as the type of a collection-valued property.

    @@ -1751,7 +1751,7 @@

    9.

    A complex type MAY indicate that it is open and allows clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type.

    A complex type derived from an open complex type MUST indicate that it is also open.

    -

    Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData‑Protocol.

    +

    Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol, section 3.

    $OpenType

    The value of $OpenType is one of the Boolean literals true or false. Absence of the member means false.

    @@ -2335,7 +2335,7 @@

    annotation applies a term to a model element and defines how to calculate a value for the applied term.

    Metadata annotations are terms applied to model elements. Behaviors or constraints described by a metadata annotation must be consistent with the annotated model element. Such annotations define additional behaviors or constraints on the model element, such as a service, entity type, property, function, action, or parameter. For example, a metadata annotation may define ranges of valid values for a particular property. Metadata annotations are applied in CSDL documents describing or referencing an entity model.

    -

    Instance annotations are terms applied to a particular instance within an OData payload, such as described in OData-JSON. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the annotation specified at the metadata level. Annotations that apply across instances should be specified as metadata annotations.

    +

    Instance annotations are terms applied to a particular instance within an OData payload, such as described in OData-JSON, section 20. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the annotation specified at the metadata level. Annotations that apply across instances should be specified as metadata annotations.

    A vocabulary is a schema containing a set of terms where each term is a named metadata extension. Anyone can define a vocabulary (a set of terms) that is scenario-specific or company-specific; more commonly used terms can be published as shared vocabularies such as the OData Core vocabulary OData-VocCore.

    A term can be used to:

      @@ -2408,8 +2408,8 @@

      $Nullable

      For single-valued terms the value true means that annotations may have the null value.

      For collection-valued terms the annotation value will always be a collection that MAY be empty. In this case $Nullable applies to items of the collection and specifies whether the collection MAY contain null values.

      $DefaultValue

      -

      The value of $DefaultValue is the type-specific JSON representation of the default value of the term, see OData-JSON.

      -

      Note: the $DefaultValue member is purely for documentation and isomorphy to OData-CSDLXML. Annotations in CSDL JSON documents MUST always specify an explicit value.

      +

      The value of $DefaultValue is the type-specific JSON representation of the default value of the term, see OData-JSON, section 7.1.

      +

      Note: the $DefaultValue member is purely for documentation and isomorphy to OData-CSDLXML, section 7.3. Annotations in CSDL JSON documents MUST always specify an explicit value.

      14.1.1 Specialized Term

      @@ -2935,7 +2935,7 @@

      14.3.12 Time of D

      14.3.13 Geo Values
      -

      Values are represented as GeoJSON, see OData-JSON.

      +

      Values are represented as GeoJSON, see RFC7946.

      Example 58:

      @@ -2946,7 +2946,7 @@

      14.3.13 Geo Values

      14.3.14 Stream Values

      -

      Constant values of type Edm.Stream are represented according to OData-JSON and MUST be accompanied by the mediaContentType control information to indicate how the stream value is to be interpreted.

      +

      Constant values of type Edm.Stream are represented according to OData-JSON, section 9 and MUST be accompanied by the mediaContentType control information to indicate how the stream value is to be interpreted.

      The annotation (property) being assigned a stream value MUST be annotated with term Core.MediaType and the media type of the stream as its value.

      @@ -2977,7 +2977,7 @@

      1

      14.4.1.1 Path Syntax

       -

      Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see OData-URL.

      +

      Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see OData-URL, section 5.1.1.15.

      A path MUST be composed of zero or more path segments joined together by forward slashes (/).

      Paths starting with a forward slash (/) are absolute paths, and the first path segment MUST be the qualified name of a model element, e.g. an entity container. The remaining path after the second forward slash is interpreted relative to that model element.

      @@ -3024,7 +3024,7 @@

      14.4.1.1 Path S 
      …/Items@Core.Description
      …/Items/@Core.Description

      -

      An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see OData-URL. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, not relative to the instance identified by the preceding path part.

      +

      An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see OData-URL, section 4.3.1. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, not relative to the instance identified by the preceding path part.

      Example 67: instance path with entity set and key predicate

      /self.container/SettingsCollection('FeatureXxx')/IsAvailable
      @@ -3237,7 +3237,7 @@

      OData-URL.

      +

      The And and Or operators require two operand expressions that evaluate to Boolean values. The Not operator requires a single operand expression that evaluates to a Boolean value. For details on null handling for comparison operators see OData-URL, section 5.1.1.1.

      The other comparison operators require two operand expressions that evaluate to comparable values.

      $And and $Or

      @@ -3349,7 +3349,7 @@

      $Eq, 14.4.3 Arithmetic Operators

      -

      Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL.

      +

      Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL, section 5.1.1.2.

      @@ -3479,7 +3479,7 @@

      $Apply and 14.4.4.1 Canonical Functions

      -

      All canonical functions defined in OData-URL can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL.

      +

      All canonical functions defined in OData-URL, section 5.1.1.4 can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL, section 5.1.1.4.

      For example, the odata.concat client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or enumeration type. It returns a value of type Edm.String that is the concatenation of the literal representations of the results of the argument expressions. Values of primitive types other than Edm.String are represented according to the appropriate alternative in the primitiveValue rule of OData-ABNF, i.e. Edm.Binary as binaryValue, Edm.Boolean as booleanValue etc.

      Example 77:

      @@ -3602,7 +3602,7 @@

      14.4.5 Cast

      -

      The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the cast canonical function defined in OData-URL.

      +

      The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the cast canonical function defined in OData-URL, section 5.1.1.10.1.

      $Cast

      Cast expressions are represented as an object with a member $Cast whose value is an annotation expression, a member $Type whose value is a string containing the qualified type name, and optionally a member $Collection with a value of true.

      @@ -3790,7 +3790,7 @@

      14.4.12 Record

      For collection-valued properties the absence of a property value expression is equivalent to specifying an empty collection as its value.

      Record expressions are represented as objects with one member per property value expression. The member name is the property name, and the member value is the property value expression.

      -

      The type of a record expression is represented as the type control information, see OData-JSON.

      +

      The type of a record expression is represented as the type control information, see OData-JSON, section 4.6.3.

      It MAY contain annotations for itself and its members. Annotations for record members are prefixed with the member name.

      @@ -4283,6 +4283,8 @@
      RFC6570
      RFC7493

      The I-JSON Message Format“, RFC 7493, DOI 10.17487/RFC7493, March 2015.
      https://www.rfc-editor.org/info/rfc7493.

      +
      RFC7946
      +

      Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, “The GeoJSON Format”, RFC 7946, DOI 10.17487/RFC7946, August 2016. https://www.rfc-editor.org/info/rfc7946.

      RFC8174

      Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
      https://www.rfc-editor.org/info/rfc8174.

      @@ -4482,7 +4484,7 @@

      C.1 Speci
    • Jens Ittel (SAP SE)
    • Patric Ksinsik (SAP SE)
      • -

      The contributions of the OASIS OData Technical Committee members, enumerated in ODataProtocol, are gratefully acknowledged.

      +

      The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

      C.2 Participants

      diff --git a/docs/odata-csdl-json/odata-csdl-json.md b/docs/odata-csdl-json/odata-csdl-json.md index d4a61451..6acf0845 100644 --- a/docs/odata-csdl-json/odata-csdl-json.md +++ b/docs/odata-csdl-json/odata-csdl-json.md @@ -673,7 +673,7 @@ length. The value of `$MaxLength` is a positive integer. -Note: [OData-CSDL-XML](#ODataCSDL) defines a symbolic +Note: [OData-CSDLXML, section 3.4.1](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#MaxLength) defines a symbolic value `max` that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the @@ -993,8 +993,8 @@ The annotation, defined in [OData-VocCore](#ODataVocCore), MAY be used to indicate a particular version of the referenced document. If the [`Core.SchemaVersion`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion) -annotation is present, the `$schemaversion` system query option, defined -[OData-Protocol](#ODataProtocol), SHOULD be used when retrieving the +annotation is present, the `$schemaversion` system query option, defined in +[OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion), SHOULD be used when retrieving the referenced schema document. ::: {.varjson .rep} @@ -1500,7 +1500,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel). ::: {.varjson .rep} ### `$OpenType` @@ -1521,7 +1521,7 @@ entity with one or more properties of type `Edm.Stream` if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 11.2.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#RequestingtheMediaStreamofaMediaEntityusingvalue). An entity type derived from a media entity type MUST indicate that it is also a media entity type. @@ -1582,7 +1582,7 @@ on one of these primitive types: Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in -[OData-Protocol](#ODataProtocol)) MUST be language independent. +[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences)) MUST be language independent. A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable @@ -1865,7 +1865,7 @@ If no value is specified, the client SHOULD NOT assume a default value. The value of `$DefaultValue` is the type-specific JSON representation of the default value of the property, see -[OData-JSON](#ODataJSON). For properties of type +[OData-JSON, section 7.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue). For properties of type `Edm.Decimal` and `Edm.Int64` the representation depends on the media type parameter [`IEEE754Compatible`](#ControllingtheRepresentationofNumbers). @@ -2072,7 +2072,7 @@ the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see -[OData-URL](#ODataURL). +[OData-URL, section 4.3.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURLforContainedEntities). Entity types used in collection-valued containment navigation properties MUST have a [key](#Key) defined. @@ -2394,7 +2394,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData‑Protocol](#ODataProtocol). +[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel). ::: {.varjson .rep} ### `$OpenType` @@ -3541,7 +3541,7 @@ Metadata annotations are applied in CSDL documents describing or referencing an entity model. *Instance annotations* are terms applied to a particular instance within -an OData payload, such as described in [OData-JSON](#ODataJSON). An +an OData payload, such as described in [OData-JSON, section 20](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InstanceAnnotations). An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. @@ -3683,10 +3683,10 @@ of the collection and specifies whether the collection MAY contain The value of `$DefaultValue` is the type-specific JSON representation of the default value of the term, see -[OData-JSON](#ODataJSON). +[OData-JSON, section 7.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue). Note: the `$DefaultValue` member is purely for documentation and -isomorphy to [OData-CSDLXML](#ODataCSDL). Annotations in +isomorphy to [OData-CSDLXML, section 7.3](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#DefaultValue). Annotations in CSDL JSON documents MUST always specify an explicit value. ::: @@ -4203,7 +4203,7 @@ Example 57: ### 14.3.13 Geo Values ::: {.varjson .rep} -Values are represented as GeoJSON, see [OData-JSON](#ODataJSON). +Values are represented as GeoJSON, see [RFC7946](#rfc7946). ::: ::: {.varjson .example} @@ -4218,7 +4218,7 @@ Example 58: ### 14.3.14 Stream Values ::: {.varjson .rep} -Constant values of type `Edm.Stream` are represented according to [OData-JSON](#ODataJSON) and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted. +Constant values of type `Edm.Stream` are represented according to [OData-JSON, section 9](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#StreamProperty) and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted. ::: @@ -4266,7 +4266,7 @@ than the `Edm.*Path` types. #### 14.4.1.1 Path Syntax Model paths and instance paths share a common syntax which is derived -from the path expression syntax of URLs, see [OData-URL](#ODataURL). +from the path expression syntax of URLs, see [OData-URL, section 5.1.1.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#PathExpressions). A path MUST be composed of zero or more path segments joined together by forward slashes (`/`). @@ -4402,7 +4402,7 @@ vs. term cast addressing an annotation on the resource addressed by the navigati An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see -[OData-URL](#ODataURL). The key values are either primitive literals or +[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, *not* relative to the instance identified by the preceding path @@ -4774,7 +4774,7 @@ they MAY be used anywhere instead of a Boolean expression. The `And` and `Or` operators require two operand expressions that evaluate to Boolean values. The `Not` operator requires a single operand expression that evaluates to a Boolean value. For details on null -handling for comparison operators see [OData-URL](#ODataURL). +handling for comparison operators see [OData-URL, section 5.1.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LogicalOperators). The other comparison operators require two operand expressions that evaluate to comparable values. @@ -4912,7 +4912,7 @@ to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in -[OData-URL](#ODataURL). +[OData-URL, section 5.1.1.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ArithmeticOperators). Operator|Description --------|----------- @@ -5045,10 +5045,10 @@ specification and its future versions. #### 14.4.4.1 Canonical Functions -All canonical functions defined in [OData-URL](#ODataURL) can be used as +All canonical functions defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions) can be used as client-side functions, qualified with the namespace `odata`. The semantics of these client-side functions is identical to their -counterpart function defined in [OData-URL](#ODataURL). +counterpart function defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions). For example, the `odata.concat` client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or @@ -5230,7 +5230,7 @@ Example 80: The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the `cast` canonical function defined in -[OData-URL](#ODataURL). +[OData-URL, section 5.1.1.10.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#cast). ::: {.varjson .rep} ### `$Cast` @@ -5558,7 +5558,7 @@ property value expression. The member name is the property name, and the member value is the property value expression. The type of a record expression is represented as the `type` control -information, see [OData-JSON](#ODataJSON). +information, see [OData-JSON, section 4.6.3](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationtypeodatatype). It MAY contain [annotations](#Annotation) for itself and its members. Annotations for record members are prefixed with the member name. @@ -6153,6 +6153,10 @@ https://www.rfc-editor.org/info/rfc6570. _The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015_. https://www.rfc-editor.org/info/rfc7493. +###### [RFC7946]{id=rfc7946} +_Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10.17487/RFC7946, August 2016_. +https://www.rfc-editor.org/info/rfc7946. + ###### [RFC8174]{id=rfc8174} _Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_. https://www.rfc-editor.org/info/rfc8174. @@ -6314,7 +6318,7 @@ especially the contributions of - Patric Ksinsik (SAP SE) The contributions of the OASIS OData Technical Committee members, -enumerated in [ODataProtocol](#ODataProtocol), are gratefully +enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. ## C.2 Participants diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html index e934cf6b..3c57b6db 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.html +++ b/docs/odata-csdl-xml/odata-csdl-xml.html @@ -994,7 +994,7 @@

      4.1 Reference

      A reference to an external CSDL document allows to bring part of the referenced document’s content into the scope of the referencing document.

      A reference MUST specify a URI that uniquely identifies the referenced document, so two references MUST NOT specify the same URI. The URI SHOULD be a URL that locates the referenced document. If the URI is not dereferencable it SHOULD identify a well-known schema. The URI MAY be absolute or relative URI; relative URLs are relative to the URL of the document containing the reference, or relative to a base URL specified in a format-specific way.

      A reference MAY be annotated.

      -

      The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined OData-Protocol, SHOULD be used when retrieving the referenced schema document.

      +

      The Core.SchemaVersion annotation, defined in OData-VocCore, MAY be used to indicate a particular version of the referenced document. If the Core.SchemaVersion annotation is present, the $schemaversion system query option, defined in OData-Protocol, section 11.2.12, SHOULD be used when retrieving the referenced schema document.

      Element edmx:Reference

      The edmx:Reference element specifies external CSDL documents referenced by the referencing document. The child elements edmx:Include and edmx:IncludeAnnotations specify which parts of the referenced document are available for use in the referencing document.

      @@ -1238,7 +1238,7 @@

      6.3 O

      An entity type MAY indicate that it is open and allows clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type.

      An entity type derived from an open entity type MUST indicate that it is also open.

      -

      Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol.

      +

      Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol, section 3.

      Attribute OpenType

      The value of OpenType is one of the Boolean literals true or false. Absence of the attribute means false.

      @@ -1247,7 +1247,7 @@

      Attribute

      6.4 Media Entity Type

       -

      An entity type that does not specify a base type MAY indicate that it is a media entity type. Media entities are entities that represent a media stream, such as a photo. Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just additional structured information attached to the stream. Use a normal entity with one or more properties of type Edm.Stream if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see OData-Protocol.

      +

      An entity type that does not specify a base type MAY indicate that it is a media entity type. Media entities are entities that represent a media stream, such as a photo. Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just additional structured information attached to the stream. Use a normal entity with one or more properties of type Edm.Stream if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see OData-Protocol, section 11.2.3.

      An entity type derived from a media entity type MUST indicate that it is also a media entity type.

      Media entity types MAY specify a list of acceptable media types using an annotation with term Core.AcceptableMediaTypes, see OData-VocCore.

      @@ -1278,7 +1278,7 @@

      6.5 Key

    • Edm.String
    • Edm.TimeOfDay
      • -

      Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in OData-Protocol) MUST be language independent.

      +

      Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in OData-Protocol, section 4.1) MUST be language independent.

      A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable single-valued complex properties, recursively.

      In OData 4.01 the key properties of a directly related entity type MAY also be part of the key if the navigation property is single-valued and not nullable. This includes navigation properties of non-nullable single-valued complex properties (recursively) of the entity type. If a key property of a related entity type is part of the key, all key properties of the related entity type MUST also be part of the key.

      If the key property is a property of a complex property (recursively) or of a directly related entity type, the key MUST specify an alias for that property that MUST be a simple identifier and MUST be unique within the set of aliases, structural and navigation properties of the declaring entity type and any of its base types.

      @@ -1486,7 +1486,7 @@

      OData-URL.

      +

      Instances of the structured type that declares the navigation property, either directly or indirectly via a property of complex type, contain the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see OData-URL, section 4.3.2.

      Entity types used in collection-valued containment navigation properties MUST have a key defined.

      For items of an ordered collection of complex types (those annotated with the Core.Ordered term defined in OData-VocCore the canonical URL of the item is the canonical URL of the collection appended with a segment containing the zero-based ordinal of the item. Items within in an unordered collection of complex types do not have a canonical URL. Services that support unordered collections of complex types declaring a containment navigation property, either directly or indirectly via a property of complex type, MUST specify the URL for the navigation link within a payload representing that item, according to format-specific rules.

      OData 4.0 responses MUST NOT specify a complex type declaring a containment navigation property as the type of a collection-valued property.

      @@ -1637,7 +1637,7 @@

      9.

      A complex type MAY indicate that it is open and allows clients to add properties dynamically to instances of the type by specifying uniquely named property values in the payload used to insert or update an instance of the type.

      A complex type derived from an open complex type MUST indicate that it is also open.

      -

      Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData‑Protocol.

      +

      Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see OData-Protocol, section 3.

      Attribute OpenType

      The value of OpenType is one of the Boolean literals true or false. Absence of the attribute means false.

      @@ -2163,7 +2163,7 @@

      annotation applies a term to a model element and defines how to calculate a value for the applied term.

      Metadata annotations are terms applied to model elements. Behaviors or constraints described by a metadata annotation must be consistent with the annotated model element. Such annotations define additional behaviors or constraints on the model element, such as a service, entity type, property, function, action, or parameter. For example, a metadata annotation may define ranges of valid values for a particular property. Metadata annotations are applied in CSDL documents describing or referencing an entity model.

      -

      Instance annotations are terms applied to a particular instance within an OData payload, such as described in OData-JSON. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the annotation specified at the metadata level. Annotations that apply across instances should be specified as metadata annotations.

      +

      Instance annotations are terms applied to a particular instance within an OData payload, such as described in OData-JSON, section 20. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. Where the same annotation is defined at both the metadata and instance level, the instance-level annotation overrides the annotation specified at the metadata level. Annotations that apply across instances should be specified as metadata annotations.

      A vocabulary is a schema containing a set of terms where each term is a named metadata extension. Anyone can define a vocabulary (a set of terms) that is scenario-specific or company-specific; more commonly used terms can be published as shared vocabularies such as the OData Core vocabulary OData-VocCore.

      A term can be used to:

        @@ -2870,7 +2870,7 @@

        1

        14.4.1.1 Path Syntax

         -

        Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see OData-URL.

        +

        Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see OData-URL, section 5.1.1.15.

        A path MUST be composed of zero or more path segments joined together by forward slashes (/).

        Paths starting with a forward slash (/) are absolute paths, and the first path segment MUST be the qualified name of a model element, e.g. an entity container. The remaining path after the second forward slash is interpreted relative to that model element.

        @@ -2917,7 +2917,7 @@

        14.4.1.1 Path S 
        …/Items@Core.Description
        …/Items/@Core.Description

        -

        An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see OData-URL. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, not relative to the instance identified by the preceding path part.

        +

        An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see OData-URL, section 4.3.1. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, not relative to the instance identified by the preceding path part.

        Example 67: instance path with entity set and key predicate

        /self.container/SettingsCollection('FeatureXxx')/IsAvailable
        @@ -3132,7 +3132,7 @@

        OData-URL.

        +

        The And and Or operators require two operand expressions that evaluate to Boolean values. The Not operator requires a single operand expression that evaluates to a Boolean value. For details on null handling for comparison operators see OData-URL, section 5.1.1.1.

        The other comparison operators require two operand expressions that evaluate to comparable values.

        Expressions edm:And and edm:Or

        @@ -3198,7 +3198,7 @@

        Expressions ed

        14.4.3 Arithmetic Operators

         -

        Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL.

        +

        Annotations MAY use the following arithmetic expressions which evaluate to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in OData-URL, section 5.1.1.2.

      @@ -3292,7 +3292,7 @@

      Attribute

      14.4.4.1 Canonical Functions

       -

      All canonical functions defined in OData-URL can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL.

      +

      All canonical functions defined in OData-URL, section 5.1.1.4 can be used as client-side functions, qualified with the namespace odata. The semantics of these client-side functions is identical to their counterpart function defined in OData-URL, section 5.1.1.4.

      For example, the odata.concat client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or enumeration type. It returns a value of type Edm.String that is the concatenation of the literal representations of the results of the argument expressions. Values of primitive types other than Edm.String are represented according to the appropriate alternative in the primitiveValue rule of OData-ABNF, i.e. Edm.Binary as binaryValue, Edm.Boolean as booleanValue etc.

      Example 77:

      @@ -3371,7 +3371,7 @@

      14.4.5 Cast

      -

      The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the cast canonical function defined in OData-URL.

      +

      The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the cast canonical function defined in OData-URL, section 5.1.1.10.1.

      Expression edm:Cast

      The edm:Cast element MUST contain the Type attribute and MUST contain exactly one expression.

      @@ -4194,7 +4194,7 @@

      C.1 Special Thanks

      -

      The contributions of the OASIS OData Technical Committee members, enumerated in ODataProtocol, are gratefully acknowledged.

      +

      The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

      C.2 Participants

      diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md index 12d4e497..a8a554ec 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.md +++ b/docs/odata-csdl-xml/odata-csdl-xml.md @@ -928,8 +928,8 @@ The annotation, defined in [OData-VocCore](#ODataVocCore), MAY be used to indicate a particular version of the referenced document. If the [`Core.SchemaVersion`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion) -annotation is present, the `$schemaversion` system query option, defined -[OData-Protocol](#ODataProtocol), SHOULD be used when retrieving the +annotation is present, the `$schemaversion` system query option, defined in +[OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion), SHOULD be used when retrieving the referenced schema document. @@ -1418,7 +1418,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel). ::: {.varxml .rep} @@ -1439,7 +1439,7 @@ entity with one or more properties of type `Edm.Stream` if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 11.2.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#RequestingtheMediaStreamofaMediaEntityusingvalue). An entity type derived from a media entity type MUST indicate that it is also a media entity type. @@ -1500,7 +1500,7 @@ on one of these primitive types: Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in -[OData-Protocol](#ODataProtocol)) MUST be language independent. +[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences)) MUST be language independent. A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable @@ -1956,7 +1956,7 @@ the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see -[OData-URL](#ODataURL). +[OData-URL, section 4.3.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURLforContainedEntities). Entity types used in collection-valued containment navigation properties MUST have a [key](#Key) defined. @@ -2272,7 +2272,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData‑Protocol](#ODataProtocol). +[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel). ::: {.varxml .rep} @@ -3347,7 +3347,7 @@ Metadata annotations are applied in CSDL documents describing or referencing an entity model. *Instance annotations* are terms applied to a particular instance within -an OData payload, such as described in [OData-JSON](#ODataJSON). An +an OData payload, such as described in [OData-JSON, section 20](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InstanceAnnotations). An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. @@ -4197,7 +4197,7 @@ than the `Edm.*Path` types. #### 14.4.1.1 Path Syntax Model paths and instance paths share a common syntax which is derived -from the path expression syntax of URLs, see [OData-URL](#ODataURL). +from the path expression syntax of URLs, see [OData-URL, section 5.1.1.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#PathExpressions). A path MUST be composed of zero or more path segments joined together by forward slashes (`/`). @@ -4333,7 +4333,7 @@ vs. term cast addressing an annotation on the resource addressed by the navigati An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see -[OData-URL](#ODataURL). The key values are either primitive literals or +[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, *not* relative to the instance identified by the preceding path @@ -4712,7 +4712,7 @@ they MAY be used anywhere instead of a Boolean expression. The `And` and `Or` operators require two operand expressions that evaluate to Boolean values. The `Not` operator requires a single operand expression that evaluates to a Boolean value. For details on null -handling for comparison operators see [OData-URL](#ODataURL). +handling for comparison operators see [OData-URL, section 5.1.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LogicalOperators). The other comparison operators require two operand expressions that evaluate to comparable values. @@ -4801,7 +4801,7 @@ to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in -[OData-URL](#ODataURL). +[OData-URL, section 5.1.1.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ArithmeticOperators). Operator|Description --------|----------- @@ -4897,10 +4897,10 @@ specification and its future versions. #### 14.4.4.1 Canonical Functions -All canonical functions defined in [OData-URL](#ODataURL) can be used as +All canonical functions defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions) can be used as client-side functions, qualified with the namespace `odata`. The semantics of these client-side functions is identical to their -counterpart function defined in [OData-URL](#ODataURL). +counterpart function defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions). For example, the `odata.concat` client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or @@ -5038,7 +5038,7 @@ Example 80: The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the `cast` canonical function defined in -[OData-URL](#ODataURL). +[OData-URL, section 5.1.1.10.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#cast). @@ -6042,7 +6042,7 @@ https://www.ogc.org/standard/sfa/. The contributions of the OASIS OData Technical Committee members, -enumerated in [ODataProtocol](#ODataProtocol), are gratefully +enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. ## C.2 Participants diff --git a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html index bf4590bc..a84c280a 100644 --- a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html +++ b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html @@ -2628,7 +2628,7 @@

      4 Cross-Joins and Aggregation

      OData supports querying related entities through defining navigation properties in the data model. These navigation paths help guide simple consumers in understanding and navigating relationships.

      -

      In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource $crossjoin instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See OData-URL for details.

      +

      In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource $crossjoin instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See OData-URL, section 4.15 for details.

      Where useful navigations exist it is beneficial to expose those as explicit navigation properties in the model, but the ability to pose queries that span entity sets not related by an association provides a mechanism for advanced consumers to use more flexible join conditions.

      Example 47: if Sale had a string property ProductID instead of the navigation property Product, a “join” between Sales and Products could be accessed via the $crossjoin resource

      @@ -2674,7 +2674,7 @@

      5.1 Aggregation Capabilities

       -

      The term ApplySupported can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see example 50). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of $apply even if they do not specify the OpenType attribute, see OData-CSDL. The term has a complex type with the following properties:

      +

      The term ApplySupported can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see example 50). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of $apply even if they do not specify the OpenType attribute, see OData-CSDL, section 6.3. The term has a complex type with the following properties:

      • The Transformations collection lists all supported set transformations. Allowed values are the names of the standard transformations introduced in sections 3 and 6, and namespace-qualified names identifying a service-defined bindable function. If Transformations is omitted the server supports all transformations defined by this specification.
      • The CustomAggregationMethods collection lists supported custom aggregation methods. Allowed values are namespace-qualified names identifying service-specific aggregation methods. If omitted, no custom aggregation methods are supported.
        • @@ -4922,7 +4922,7 @@

        B.1 Special Thanks

        -

        The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, are gratefully acknowledged.

        +

        The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

      B.2 Participants

      diff --git a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md index 773993b5..8f691ab1 100644 --- a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md +++ b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md @@ -2234,7 +2234,7 @@ The normative ABNF construction rules for this specification are defined in [ODa OData supports querying related entities through defining navigation properties in the data model. These navigation paths help guide simple consumers in understanding and navigating relationships. -In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource `$crossjoin` instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See [OData-URL](#ODataURL) for details. +In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource `$crossjoin` instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See [OData-URL, section 4.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets) for details. Where useful navigations exist it is beneficial to expose those as explicit navigation properties in the model, but the ability to pose queries that span entity sets not related by an association provides a mechanism for advanced consumers to use more flexible join conditions. @@ -2293,7 +2293,7 @@ The following terms are defined in the vocabulary for data aggregation [OData-Vo ## 5.1 Aggregation Capabilities -The term `ApplySupported` can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see [example 50](#containerrooted)). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of `$apply` even if they do not specify the `OpenType` attribute, see [OData-CSDL](#ODataCSDL). The term has a complex type with the following properties: +The term `ApplySupported` can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see [example 50](#containerrooted)). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of `$apply` even if they do not specify the `OpenType` attribute, see [OData-CSDL, section 6.3](https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#OpenEntityType). The term has a complex type with the following properties: - The `Transformations` collection lists all supported set transformations. Allowed values are the names of the standard transformations introduced in sections 3 and 6, and namespace-qualified names identifying a service-defined bindable function. If `Transformations` is omitted the server supports all transformations defined by this specification. - The `CustomAggregationMethods` collection lists supported custom aggregation methods. Allowed values are namespace-qualified names identifying service-specific aggregation methods. If omitted, no custom aggregation methods are supported. - `Rollup` specifies whether the service supports no rollup, only a single rollup hierarchy, or multiple rollup hierarchies in a [`groupby`](#Transformationgroupby) transformation. If omitted, multiple rollup hierarchies are supported. @@ -5012,7 +5012,7 @@ https://www.rfc-editor.org/info/rfc8174. ## B.1 Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol), are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. ## B.2 Participants diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 66603c79..243ac6f8 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -578,7 +578,7 @@

      4.2 Message Bod

      4.3 URLs in Message Bodies

       -

      URLs represented as a string within a JSON payload, including batch requests, must follow standard OData encoding rules as defined in OData-URL.

      +

      URLs represented as a string within a JSON payload, including batch requests, must follow standard OData encoding rules as defined in OData-URL, section 2.1.

      For relative URLs this means that colons (:) in the path part, especially within key values, MUST be percent-encoded to avoid confusion with the scheme separator. Colons within the query part, i.e. after the question mark character (?), need not be percent-encoded.

      @@ -654,10 +654,10 @@

      4.6.1 Control Information: context (odata.context)

       -

      The context control information returns the context URL (see OData-Protocol) for the payload. This URL can be absolute or relative. The fragment portion of the context URL MUST NOT be percent-encoded.

      +

      The context control information returns the context URL (see OData-Protocol, section 10) for the payload. This URL can be absolute or relative. The fragment portion of the context URL MUST NOT be percent-encoded.

      The context control information is not returned if metadata=none is requested. Otherwise it MUST be the first property of any JSON response that allows this control information (this excludes for example error responses).

      The context control information MUST also be included in requests and responses for entities whose entity set cannot be determined from the context URL of the collection.

      -

      For more information on the format of the context URL, see OData-Protocol.

      +

      For more information on the format of the context URL, see OData-Protocol, section 10.

      Request payloads MAY include a context URL as a base URL for relative URLs in the request payload.

      Example 4:

      @@ -672,14 +672,14 @@

      4.6.2 Control Information: metadataEtag (odata.metadataEtag)

      The metadataEtag control information MAY appear in a response in order to specify the entity tag (ETag) that can be used to determine the version of the metadata of the response. If an ETag is returned when requesting the metadata document, then the service SHOULD set the metadataEtag control information to the metadata document’s ETag in all responses when using metadata=minimal or metadata=full. If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the metadataEtag control information in any responses.

      -

      For details on how ETags are used, see OData-Protocol.

      +

      For details on how ETags are used, see OData-Protocol, section 11.4.1.1.

      4.6.3 Control Information: type (odata.type)

      The type control information specifies the type of a JSON object or name/value pair. Its value is a URI that identifies the type of the property or object. For built-in primitive types the value is the unqualified name of the primitive type. For payloads described by an OData-Version header with a value of 4.0, this name MUST be prefixed with the hash symbol (#); for non-OData 4.0 payloads, built-in primitive type values SHOULD be represented without the hash symbol, but consumers of 4.01 or greater payloads MUST support values with or without the hash symbol. For all other types, the URI may be absolute or relative to the type of the containing object. The root type may be absolute or relative to the root context URL.

      -

      If the URI references a metadata document (that is, it’s not just a fragment), it MAY refer to a specific version of that metadata document using the $schemaversion system query option defined in OData-Protocol.

      -

      For non-built in primitive types, the URI contains the namespace-qualified or alias-qualified type, specified as a URI fragment. For properties that represent a collection of values, the fragment is the namespace-qualified or alias-qualified element type enclosed in parentheses and prefixed with Collection. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDLJSON or OData-CSDLXML.

      +

      If the URI references a metadata document (that is, it’s not just a fragment), it MAY refer to a specific version of that metadata document using the $schemaversion system query option defined in OData-Protocol, section 11.2.12.

      +

      For non-built in primitive types, the URI contains the namespace-qualified or alias-qualified type, specified as a URI fragment. For properties that represent a collection of values, the fragment is the namespace-qualified or alias-qualified element type enclosed in parentheses and prefixed with Collection. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDL.

      The type control information MUST appear in requests and in responses with minimal or full metadata, if the type cannot be heuristically determined, as described below, and one of the following is true:

      • The type is derived from the type specified for the (collection of) entities or (collection of) complex type instances, or
        • @@ -694,7 +694,7 @@

        IEEE754Compatible format parameter etc. If a property appears in JSON string format, it should be treated as a string value unless the property is known (from the metadata document) to have a different type.

      The type control information can be absent in properties nested in an instance of type Edm.Untyped. In particular, individual primitive values within a collection cannot have type control information.

      -

      For more information on namespace- and alias-qualified names, see OData-CSDLJSON or OData-CSDLXML.

      +

      For more information on namespace- and alias-qualified names, see OData-CSDL.

      Example 5: entity of type Model.VipCustomer defined in the metadata document of the same service with a dynamic property of type Edm.Date

      {
@@ -740,7 +740,7 @@ 
 
-
      The id control information contains the entity-id, see OData-Protocol. By convention the entity-id is identical to the canonical URL of the entity, as defined in OData-URL.
      
+
      The id control information contains the entity-id, see OData-Protocol, section 4.1. By convention the entity-id is identical to the canonical URL of the entity, as defined in OData-URL, section 4.3.1.
      
 
      The id control information MUST appear in responses if metadata=full is requested, or if metadata=minimal is requested and any of a non-transient entity’s key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity after
      
 
 
      Note that the entity-id MUST be invariant across languages, so if key values are language dependent then the id MUST be included if it does not match convention for the localized key values. If the id is represented, it MAY be a relative URL.
      
-
      If the entity is transient (see OData-Protocol), the id control information MUST appear in OData 4.0 payloads and have the null value. In 4.01 or greater payloads transient entities need not have the id control information, and clients receiving such payloads MUST treat entities with neither id control information nor a full set of key properties as transient entities. In 4.02 payloads transient entities MAY have the id control information with a non-null URI value, for example to allow solving a circular dependency by injecting an entity reference instead of repeating the transient entity. The URI value SHOULD follow the pattern odata:transient:{some-generated-identifier-unique-within-the-response}, and if the transient entity cannot be re-read its readLink control information SHOULD have the null value.
      
+
      If the entity is transient (see OData-Protocol, section 4.3), the id control information MUST appear in OData 4.0 payloads and have the null value. In 4.01 or greater payloads transient entities need not have the id control information, and clients receiving such payloads MUST treat entities with neither id control information nor a full set of key properties as transient entities. In 4.02 payloads transient entities MAY have the id control information with a non-null URI value, for example to allow solving a circular dependency by injecting an entity reference instead of repeating the transient entity. The URI value SHOULD follow the pattern odata:transient:{some-generated-identifier-unique-within-the-response}, and if the transient entity cannot be re-read its readLink control information SHOULD have the null value.
      
 
      The id control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification.
      -

      The editLink control information contains the edit URL of the entity; see OData-Protocol.

      -

      The readLink control information contains the read URL of the entity or collection; see OData-Protocol.

      +

      The editLink control information contains the edit URL of the entity; see OData-Protocol, section 4.2.

      +

      The readLink control information contains the read URL of the entity or collection; see OData-Protocol, section 4.2.

      The editLink and readLink control information is ignored in request payloads and not written in responses if metadata=none is requested.

      The default value of both the edit URL and read URL is the entity’s entity-id appended with a cast segment to the type of the entity if its type is derived from the declared type of the entity set. If neither the editLink nor the readLink control information is present in an entity, the client uses this default value for the edit URL.

      For updatable entities:

      @@ -778,7 +778,7 @@

      4.6.10 Control Information: etag (odata.etag)

      The etag control information MAY be applied to an entity or collection in a response. The value of the control information is an entity tag (ETag) which is an opaque string value that can be used in a subsequent request to determine if the value of the entity or collection has changed.

      -

      For details on how ETags are used, see OData-Protocol.

      +

      For details on how ETags are used, see OData-Protocol, section 11.4.1.1.

      The etag control information is ignored in request payloads for single entities and not written in responses if metadata=none is requested.

      @@ -854,7 +854,7 @@

      5 Se

      A service document in JSON is represented as a single JSON object with at least the context control information and a property value.

      The value of the context control information MUST be the URL of the metadata document, without any fragment part.

      -

      The value of the value property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of true for the attribute IncludeInServiceDocument and each singleton exposed by the service, see OData-CSDLJSON or OData-CSDLXML.

      +

      The value of the value property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of true for the attribute IncludeInServiceDocument and each singleton exposed by the service, see OData-CSDL.

      Each element MUST be a JSON object with at least two name/value pairs, one with name name containing the name of the entity set, function import, or singleton, and one with name url containing the URL of the entity set, which may be an absolute or a relative URL. It MAY contain a name/value pair with name title containing a human-readable, language-dependent title for the object.

      JSON objects representing an entity set MAY contain an additional name/value pair with name kind and a value of EntitySet. If the kind name/value pair is not present, the object MUST represent an entity set.

      JSON objects representing a function import MUST contain the kind name/value pair with a value of FunctionImport.

      @@ -904,7 +904,7 @@

      6 Entity

      An entity is serialized as a JSON object. It MAY contain context, type, or deltaLink control information.

      Each property to be transmitted is represented as a name/value pair within the object. The order properties appear within the object is considered insignificant.

      -

      An entity in a payload may be a complete entity, a projected entity (see System Query Option $select in OData-Protocol), or a partial entity update (see Update an Entity in OData-Protocol).

      +

      An entity in a payload may be a complete entity, a projected entity (see OData-Protocol, section 11.2.5.1), or a partial entity update (see OData-Protocol, section 11.4.3).

      An entity representation can be (modified and) round-tripped to the service directly. The context URL is used in requests only as a base for relative URLs.

      Example 10: entity with metadata=minimal

      @@ -1058,9 +1058,10 @@

      7.5 Untyped

      Untyped values are the only place where a collection can directly contain a collection, or a collection can contain a mix of primitive values, structural values, and collections.

      All children of an untyped property are assumed to be untyped unless they are annotated with the type control information, in which case they MUST conform to the type described by the control information.

      A primitive value within an untyped collection is interpreted as an Edm.Boolean, Edm.String, or Edm.Decimal value, depending on the JavaScript type.

      -

      Collections directly contained within an untyped collection are themselves untyped.

      +

      Collections directly contained within an untyped collection are themselves untyped.

      +

      8 Navigation Property

       @@ -1228,7 +1229,7 @@

      9 Strea
    • Stream properties requested with $select or included in the default selection are represented by media* control information.
    • Stream properties requested with $expand or implicitly expanded are represented as a property with its value.
      • -

      See OData-Protocol for details on the system query options $select and $expand.

      +

      See OData-Protocol, section 11.2.5.1 for details on the system query options $select and $expand.

      Depending on the metadata level, the stream property MAY be annotated to provide the read link, edit link, media type, and ETag of the media stream through their media* control information.

      If the actual stream data is included inline, the control information mediaContentType MUST be present to indicate how the included stream property value is represented. Stream property values of media type application/json or one of its subtypes, optionally with format parameters, are represented as native JSON. Values of top-level type text with an explicit or default charset of utf-8 or us-ascii, for example text/plain, are represented as a string, with JSON string escaping rules applied. Included stream data of other media types is represented as a base64url-encoded string value, see RFC4648, section 5.

      If the included stream property has no value, the non-existing stream data is represented as null and the control information mediaContentType is not necessary.

      @@ -1269,7 +1270,7 @@

      10 Media Entity

      11 Individual Property or Operation Response

      An individual property or operation response is represented as a JSON object.

      -

      A single-valued property or operation response that has the null value does not have a representation; see OData-Protocol.

      +

      A single-valued property or operation response that has the null value does not have a representation; see OData-Protocol, section 9.1.4.

      A property or operation response that is of a primitive type is represented as an object with a single name/value pair, whose name is value and whose value is a primitive value.

      A property or operation response that is of complex type is represented as a complex value.

      A property or operation response that is of a collection type is represented as an object with a single name/value pair whose name is value. Its value is the JSON representation of a collection of complex type values or collection of primitive values.

      @@ -1351,7 +1352,7 @@

      14 Entity Reference

      -

      An entity reference (see OData-Protocol) MAY take the place of an entity in a JSON payload, based on the client request. It is serialized as a JSON object that MUST contain the id of the referenced entity and MAY contain the type control information and instance annotations, but no additional properties or control information.

      +

      An entity reference (see OData-Protocol, section 4.1) MAY take the place of an entity in a JSON payload, based on the client request. It is serialized as a JSON object that MUST contain the id of the referenced entity and MAY contain the type control information and instance annotations, but no additional properties or control information.

      A collection of entity references is represented as a collection of entities, with entity reference representations instead of entity representations as items in the array value of the value name/value pair.

      The outermost JSON object in a response MUST contain a context control information and MAY contain count, nextLink, or deltaLink control information.

      @@ -1447,7 +1448,7 @@

      15.1

      15.2 Added/Changed Entity

      Added or changed entities within a delta payload are represented as entities. All entities within a delta response payload MUST include the control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity.

      -

      When using a delta payload in an update request, an alternate key (see Alternate Keys in OData-URL) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

      +

      When using a delta payload in an update request, an alternate key (see OData-URL, section 4.3.5) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

      Any entity in an update request that has neither the id control information, nor the primary or alternate key values of an existing entity, are treated as an added entity.

      Added entities MUST include all available selected properties and MAY include additional, unselected properties. Collection-valued properties are treated as atomic values; any collection-valued properties returned from a delta request MUST contain all current values for that collection.

      Changed entities MUST include all available selected properties that have changed, and MAY include additional properties.

      @@ -1479,7 +1480,7 @@

      15.3 Del

      In OData 4.01 payloads the deleted-entity object MUST include the following properties, regardless of the specified metadata value. For ordered payloads, this control information MUST follow the payload ordering constraints.

      • Control information removed, whose value is an object that MAY contain a property named reason. If present, the value of reason MUST be either deleted if the entity was deleted (destroyed), or changed if the entity was removed from membership in the result either due to change in value such that the entity no longer matches the defining query or because the entity was removed from the collection. The object MAY include annotations, and clients SHOULD NOT error due to the presence of additional properties that MAY be defined by future versions of this specification.

        • -

      • Control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an update request, an alternate key (see Alternate Keys in OData-URL) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

        • +

      • Control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an update request, an alternate key (see OData-URL, section 4.3.5) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

      For full metadata the context control information MUST be included. It also MUST be included if the entity set of the deleted entity cannot be determined from the surrounding context.

      The deleted-entity object MAY include additional properties of the entity, as well as annotations, and MAY include related entities, related deleted entities, or a delta or full representation of a related collection of entities, to represent related entities that have been modified or deleted.

      @@ -1911,7 +1912,7 @@

      16 Bound Function

       -

      A bound function is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDLJSON or OData-CSDLXML A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule qualifiedFunctionName in OData-ABNF.

      +

      A bound function is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDL. A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule qualifiedFunctionName in OData-ABNF.

      A function that is bound to a single structured type MAY be advertised within the JSON object representing that structured type.

      Functions that are bound to a collection MAY be advertised within the JSON object containing the collection. If the collection is the top-level response, the function advertisement name/value pair is placed next to the value name/value pair representing the collection. If the collection is nested within an instance of a structured type, then in 4.01 payloads the name of the function advertisement is prepended with the name of the collection-valued property and is placed next to the collection-valued property, expanded navigation property, or navigationLink control information, if present. 4.0 payloads MUST NOT advertise functions prefixed with property names.

      If the function is available, the value of the advertisement is an object. OData 4.01 services MAY advertise the non-availability of the function with the value null.

      @@ -1967,7 +1968,7 @@

      16 Bound

      17 Bound Action

       -

      A bound action is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDLJSON or OData-CSDLXML

      +

      A bound action is advertised via a name/value pair where the name is a hash (#) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see OData-CSDL.

      An action that is bound to a single structured type is advertised within the JSON object representing that structured type.

      Actions that are bound to a collection MAY be advertised within the JSON object containing the collection. If the collection is the top-level response, the action advertisement name/value pair is placed next to the value name/value pair representing the collection. If the collection is nested within an instance of a structured type, then in 4.01 payloads the name of the action advertisement is prepended with the name of the collection-valued property and is placed next to the name/value pair representing the collection-valued property, expanded navigation property, or navigationLink control information, if present. 4.0 payloads MUST NOT advertise actions prefixed with property names.

      If the action is available, the value of the advertisement is an object. OData 4.01 services MAY advertise the non-availability of the action with the value null.

      @@ -2113,16 +2114,16 @@

      19.1 Batch

      A JSON batch request body consists of a single JSON object that MUST contain the name/value pair requests and MAY contain annotations. It does not contain the context control information.

      The value of requests is an array of request objects, each representing an individual request. Note: an individual request MUST NOT itself be a batch request.

      A request object MUST contain the name/value pairs id, method and url, and it MAY contain the name/value pairs atomicityGroup, dependsOn, if, headers, and body.

      -

      The value of id is a string containing the request identifier of the individual request, see OData-Protocol. It MUST NOT be identical to the value of any other request identifier nor any atomicityGroup within the batch request.

      -

      Note: the id name/value pair corresponds to the Content-ID header in the multipart batch format specified in OData-Protocol.

      +

      The value of id is a string containing the request identifier of the individual request, see OData-Protocol, section 11.7.3. It MUST NOT be identical to the value of any other request identifier nor any atomicityGroup within the batch request.

      +

      Note: the id name/value pair corresponds to the Content-ID header in the multipart batch format specified in OData-Protocol, section 11.7.7.1.

      The value of method is a string that MUST contain one of the literals delete, get, patch, post, or put. These literals are case-insensitive.

      The value of url is a string containing the individual request URL. The URL MAY be an absolute path (starting with a forward slash /) which is appended to scheme, host, and port of the batch request URL, or a relative path (not starting with a forward slash /).

      If the first segment of a relative path starts with a $ character and is not 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 this first segment is replaced with the URL of the entity created by or returned from a preceding request whose id value is identical to the value of the first segment with the leading $ character removed. The id of this request MUST be specified in the dependsOn name/value pair.

      Otherwise, the relative path is resolved relative to the batch request URL (i.e. relative to the service root).

      The value of atomicityGroup is a string whose content MUST NOT be identical to any value of id within the batch request, and which MUST satisfy the rule request-id in OData-ABNF. All request objects with the same value for atomicityGroup MUST be adjacent in the requests array. These requests are processed as an atomic operation and MUST either all succeed, or all fail.

      -

      Note: the atomicity group is a generalization of the change set in the multipart batch format specified in OData-Protocol.

      +

      Note: the atomicity group is a generalization of the change set in the multipart batch format specified in OData-Protocol, section 11.7.7.1.

      The value of dependsOn is an array of strings whose values MUST be values of either id or atomicityGroup of preceding request objects; forward references are not allowed. If a request depends on another request that is part of a different atomicity group, the atomicity group MUST be listed in dependsOn. In the absence of the optional if member a request that depends on other requests or atomicity groups is only executed if those requests were executed successfully, i.e. with a 2xx response code. If one of the requests it depends on has failed, the dependent request is not executed and a response with status code of 424 Failed Dependency is returned for it as part of the batch response.

      -

      The if member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see OData-URL) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows

      +

      The if member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see OData-URL, section 5.1.1) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows

      • $<content-id>/$succeeded to check if the referenced request has succeeded
      • $<content-id> to reference the response body of the referenced request
        • @@ -2316,7 +2317,7 @@

        19.6 Bat

        A JSON batch response body consists of a single JSON object that MUST contain the name/value pair responses and MAY contain annotations. It does not contain the context control information.

        The value of responses is an array of response objects, each representing an individual response.

        A JSON batch response MAY be a partial result containing the nextLink control information. This allows services to chunk results into manageable pieces, or to return results for already processed requests and continue processing the remaining individual requests while waiting for the client to fire a GET request to the next link.

        -

        In a response to a batch request using the multipart format defined in OData-Protocol the response objects MUST appear in the same order as required for multipart batch responses because the Content-ID header is not required outside of change sets. Response objects corresponding to requests that specify a Content-ID header MUST contain the id name/value pair, and the value of id MUST be the value of the Content-ID header of the corresponding request. This is necessarily the case for requests contained within a change set. Responses to requests within a change set MUST contain the atomicityGroup name/value pair with a value common within a change set and unique across change sets.

        +

        In a response to a batch request using the multipart format defined in OData-Protocol, section 11.7.7 the response objects MUST appear in the same order as required for multipart batch responses because the Content-ID header is not required outside of change sets. Response objects corresponding to requests that specify a Content-ID header MUST contain the id name/value pair, and the value of id MUST be the value of the Content-ID header of the corresponding request. This is necessarily the case for requests contained within a change set. Responses to requests within a change set MUST contain the atomicityGroup name/value pair with a value common within a change set and unique across change sets.

        In a response to a batch request using the JSON batch request format specified in the preceding section the response objects MAY appear in any order, and each response object MUST contain the id name/value pair with the same value as in the corresponding request object. If the corresponding request object contains the atomicityGroup name/value pair, it MUST also be present in the response object with the same value.

        If any response within an atomicity group returns a failure code, all requests within that atomicity group are considered failed, regardless of their individual returned status code. The service MAY return 424 Failed Dependency for statements within an atomicity group that fail or are not attempted due to other failures within the same atomicity group.

        A response object MUST contain the name/value pair status whose value is a number representing the HTTP status code of the response to the individual request.

        @@ -2450,7 +2451,7 @@

        20 Instance Annotations

        Annotations are an extensibility mechanism that allows services and clients to include information other than the raw data in the request or response.

        -

        Annotations are name/value pairs that have an at (@) and a dot (.) as part of the name. The part after the “at” sign (@) is the annotation identifier. It consists of the namespace or alias of the schema that defines the term, followed by a dot (.), followed by the name of the term, optionally followed by a hash (#) and a qualifier. The namespace or alias MUST be defined in the metadata document, see OData-CSDLJSON or OData-CSDLXML

        +

        Annotations are name/value pairs that have an at (@) and a dot (.) as part of the name. The part after the “at” sign (@) is the annotation identifier. It consists of the namespace or alias of the schema that defines the term, followed by a dot (.), followed by the name of the term, optionally followed by a hash (#) and a qualifier. The namespace or alias MUST be defined in the metadata document, see OData-CSDL.

        The annotation identifier odata is reserved for future extensions of the protocol and format. Instance annotations MUST have a namespace or alias that is different from odata.

        Annotations can be applied to any name/value pair in a JSON payload that represents a value of any type from the entity data model. Clients should never error due to an unexpected annotation in a JSON payload.

        Annotations are always expressed as name/value pairs. For entity data model constructs represented as JSON objects the annotation name/value pairs are placed within the object; for constructs represented as JSON arrays or primitives, including null, they are placed next to the annotated model construct and have the name of the annotated property before the @. An annotation in the latter format can also take the place of an absent property. When annotating a payload that represents a single primitive or collection value, the annotations for the value appear next to the value property and are not prefixed with a property name.

        @@ -2534,7 +2535,7 @@

        21.1 Err

        21.2 In-Stream Error

        In the case that a service encounters an error after sending a success status to the client, the service MUST leave the response malformed. This can be achieved by immediately stopping response serialization and thus omitting (among others) the end-object character of the top-level JSON object in the response.

        -

        Services MAY include the header OData-Error as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see OData-Protocol.

        +

        Services MAY include the header OData-Error as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see OData-Protocol, section 8.3.5.

        The value of the OData-Error trailing header is an OData error object as defined in the preceding chapter, represented in a header-appropriate way:

      C.2 Participants

      diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index 231c3291..e91a3a14 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -600,7 +600,7 @@ order of objects within an array in JSON responses. ## 4.3 URLs in Message Bodies URLs represented as a string within a JSON payload, including [batch -requests](#BatchRequest), must follow standard OData encoding rules as defined in [OData-URL](#ODataURL). +requests](#BatchRequest), must follow standard OData encoding rules as defined in [OData-URL, section 2.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#URLParsing). For [relative URLs](#RelativeURLs) this means that colons (`:`) in the path part, especially within key values, MUST be percent-encoded to avoid confusion with the @@ -760,7 +760,7 @@ stop processing and MUST NOT signal an error. ### 4.6.1 Control Information: `context` (`odata.context`) The `context` control information -returns the context URL (see [OData-Protocol](#ODataProtocol)) for the +returns the context URL (see [OData-Protocol, section 10](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL)) for the payload. This URL can be absolute or [relative](#RelativeURLs). The fragment portion of the context URL MUST NOT be percent-encoded. @@ -774,7 +774,7 @@ entity set cannot be determined from the context URL of the collection. For more information on the format of the context URL, see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 10](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL). Request payloads MAY include a context URL as a base URL for [relative URLs](#RelativeURLs) in the request payload. @@ -805,7 +805,7 @@ If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the `metadataEtag` control information in any responses. -For details on how ETags are used, see [OData-Protocol](#ODataProtocol). +For details on how ETags are used, see [OData-Protocol, section 11.4.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts). ### 4.6.3 Control Information: `type` (`odata.type`) @@ -826,7 +826,7 @@ The root `type` may be absolute or relative to the root If the URI references a metadata document (that is, it's not just a fragment), it MAY refer to a specific version of that metadata document using the `$schemaversion` system query option -defined in [OData-Protocol](#ODataProtocol). +defined in [OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion). For non-built in primitive types, the URI contains the namespace-qualified or alias-qualified type, specified as a URI @@ -835,8 +835,7 @@ fragment is the namespace-qualified or alias-qualified element type enclosed in parentheses and prefixed with `Collection`. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see -[OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL). +[OData-CSDL](#ODataCSDL). The `type` control information MUST appear in requests and in responses with [minimal](#metadataminimalodatametadataminimal) or @@ -878,8 +877,7 @@ The `type` control information can be absent in properties nested in an instance In particular, individual primitive values within a collection cannot have `type` control information. For more information on namespace- and alias-qualified names, see -[OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL). +[OData-CSDL](#ODataCSDL). ::: example Example 5: entity of type @@ -950,9 +948,9 @@ control information. ### 4.6.8 Control Information: `id` (`odata.id`) The `id` control information contains the entity-id, see -[OData-Protocol](#ODataProtocol). By convention the entity-id is +[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences). By convention the entity-id is identical to the canonical URL of the entity, as defined in -[OData-URL](#ODataURL). +[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The `id` control information MUST appear in responses if [`metadata=full`](#metadatafullodatametadatafull) @@ -972,7 +970,7 @@ if it does not match convention for the localized key values. If the `id` is represented, it MAY be a [relative URL](#RelativeURLs). -If the entity is transient (see [OData-Protocol](#ODataProtocol)), the +If the entity is transient (see [OData-Protocol, section 4.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#TransientEntities)), the `id` control information MUST appear in OData 4.0 payloads and have the `null` value. In 4.01 or greater payloads transient entities need not have the `id` control information, and @@ -991,10 +989,10 @@ of this specification. ### 4.6.9 Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`) The `editLink` control information contains -the edit [URL](URLsinMessageBodies) of the entity; see [OData-Protocol](#ODataProtocol). +the edit [URL](URLsinMessageBodies) of the entity; see [OData-Protocol, section 4.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ReadURLsandEditURLs). The `readLink` control information contains the read URL of -the entity or collection; see [OData-Protocol](#ODataProtocol). +the entity or collection; see [OData-Protocol, section 4.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ReadURLsandEditURLs). The `editLink` and `readLink` control information is ignored in request payloads and not written in responses if @@ -1048,7 +1046,7 @@ value of the control information is an entity tag (ETag) which is an opaque string value that can be used in a subsequent request to determine if the value of the entity or collection has changed. -For details on how ETags are used, see [OData-Protocol](#ODataProtocol). +For details on how ETags are used, see [OData-Protocol, section 11.4.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts). The `etag` control information is ignored in request payloads for single entities and not written in responses if @@ -1211,7 +1209,7 @@ The value of the `value` property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of `true` for the attribute `IncludeInServiceDocument` and each singleton exposed by the -service, see [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL). +service, see [OData-CSDL](#ODataCSDL). Each element MUST be a JSON object with at least two name/value pairs, one with name `name` containing the name of the entity set, @@ -1300,9 +1298,8 @@ represented as a name/value pair within the object. The order properties appear within the object is considered insignificant. An entity in a payload may be a complete entity, a projected entity (see -_System Query Option_ `$select` in -[OData-Protocol](#ODataProtocol)), or a partial entity update (see -_Update an Entity_ in [OData-Protocol](#ODataProtocol)). +[OData-Protocol, section 11.2.5.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionselect)), or a partial entity update (see +[OData-Protocol, section 11.4.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity)). An entity representation can be (modified and) round-tripped to the service directly. The [context @@ -1557,6 +1554,7 @@ A primitive value within an untyped collection is interpreted as an `Edm.Boolean depending on the JavaScript type. Collections directly contained within an untyped collection are themselves untyped. + ------- # 8 Navigation Property @@ -1823,7 +1821,7 @@ Instead stream property data is generally read and edited via URLs. [`media*`](#ControlInformationmediaodatamedia) control information. - Stream properties requested with `$expand` or implicitly expanded are represented as a property with its value. -See [OData-Protocol](#ODataProtocol) for details on the system query options `$select` and `$expand`. +See [OData-Protocol, section 11.2.5.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionselect) for details on the system query options `$select` and `$expand`. Depending on the [metadata level](#ControllingtheAmountofControlInformationinResponses), the stream property MAY be annotated to provide the read link, edit @@ -1898,7 +1896,7 @@ object. A single-valued property or operation response that has the `null` value does not have a representation; see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 9.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ResponseCode204NoContent). A property or operation response that is of a primitive type is represented as an object with a single name/value pair, whose name is @@ -2058,7 +2056,7 @@ Example 31: # 14 Entity Reference -An entity reference (see [OData-Protocol](#ODataProtocol)) MAY take the +An entity reference (see [OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences)) MAY take the place of an entity in a JSON payload, based on the client request. It is serialized as a JSON object that MUST contain the [id](#ControlInformationidodataid) of the referenced entity and MAY contain the [`type`](#ControlInformationtypeodatatype) @@ -2203,7 +2201,7 @@ Added or changed entities within a delta payload are represented as the control information [`id`](#ControlInformationidodataid) or all of the entity's primary key fields. The `id` control information MUST appear if any of the entity's primary key fields are omitted from the response _or_ the entity-id is not identical to the canonical URL of the entity. -When using a delta payload in an [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see _Alternate Keys_ in [OData-URL](#ODataURL)) +When using a delta payload in an [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see [OData-URL, section 4.3.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AlternateKeys)) MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the `id` control information and other primary key fields. @@ -2295,7 +2293,7 @@ For ordered payloads, this control information MUST follow the [payload ordering or all of the entity's primary key fields. The `id` control information MUST appear if any of the entity's primary key fields are omitted from the response _or_ the entity-id is not identical to the canonical - URL of the entity. When using a delta payload in an [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see _Alternate Keys_ in [OData-URL](#ODataURL)) + URL of the entity. When using a delta payload in an [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see [OData-URL, section 4.3.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AlternateKeys)) MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the `id` control information and other primary key fields. @@ -2829,8 +2827,7 @@ A bound function is advertised via a name/value pair where the name is a hash (`#`) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL) A +service, see [OData-CSDL](#ODataCSDL). A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule @@ -2947,8 +2944,7 @@ A bound action is advertised via a name/value pair where the name is a hash (`#`) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL) +service, see [OData-CSDL](#ODataCSDL). An action that is bound to a single structured type is advertised within the JSON object representing that structured type. @@ -3203,13 +3199,13 @@ name/value pairs `atomicityGroup`, `dependsOn`, `if`, `headers`, and `body`. The value of `id` is a string containing the request identifier of the individual request, see -[OData-Protocol](#ODataProtocol). It MUST NOT be identical to the value +[OData-Protocol, section 11.7.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#IdentifyingIndividualRequests). It MUST NOT be identical to the value of any other request identifier nor any `atomicityGroup` within the batch request. Note: the `id` name/value pair corresponds to the `Content-ID` header in the multipart batch format specified -in [OData-Protocol](#ODataProtocol). +in [OData-Protocol, section 11.7.7.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchRequestBody). The value of `method` is a string that MUST contain one of the literals `delete`, `get`, `patch`, `post`, or `put`. @@ -3244,7 +3240,7 @@ request, and which MUST satisfy the rule `request-id` in operation and MUST either all succeed, or all fail. Note: the atomicity group is a generalization of the change set in the -multipart batch format specified in [OData-Protocol](#ODataProtocol). +multipart batch format specified in [OData-Protocol, section 11.7.7.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchRequestBody). The value of `dependsOn` is an array of strings whose values MUST be values of either `id` or `atomicityGroup` @@ -3260,7 +3256,7 @@ dependent request is not executed and a response with status code of The `if` member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see -[OData-URL](#ODataURL)) that evaluates to a Boolean value. +[OData-URL, section 5.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CommonExpressionSyntax)) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows - `$/$succeeded` @@ -3531,7 +3527,7 @@ processing the remaining individual requests while waiting for the client to fire a `GET` request to the next link. In a response to a batch request using the multipart format defined in -[OData-Protocol](#ODataProtocol) the response objects +[OData-Protocol, section 11.7.7](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchFormat) the response objects MUST appear in the same order as required for multipart batch responses because the `Content-ID` header is not required outside of change sets. Response objects corresponding to requests that specify a `Content-ID` header MUST contain the @@ -3768,7 +3764,7 @@ dot (`.`) as part of the name. The part after the "at" sign namespace or alias of the schema that defines the term, followed by a dot (`.`), followed by the name of the term, optionally followed by a hash (`#`) and a qualifier. The namespace or alias MUST be defined in the -metadata document, see [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) +metadata document, see [OData-CSDL](#ODataCSDL). The annotation identifier `odata` is reserved for future extensions of the protocol and format. Instance annotations MUST have a @@ -3934,7 +3930,7 @@ JSON object in the response. Services MAY include the header `OData-Error` as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 8.3.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#HeaderODataError). The value of the `OData-Error` trailing header is an OData error object as defined in the preceding chapter, represented in a @@ -4073,7 +4069,7 @@ In order to be a conforming producer of the OData JSON format, a client or servi In addition, in order to conform to the OData JSON format, a service: -11. MUST comply with one of the conformance levels defined in [OData-Protocol](#ODataProtocol) +11. MUST comply with one of the conformance levels defined in [OData-Protocol, section 12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Conformance) 12. MUST support the `application/json` media type in the `Accept` header ([section 3](#RequestingtheJSONFormat)) 13. MUST return well-formed JSON payloads 14. MUST support `odata.metadata=full` ([section 3.1.2](#metadatafullodatametadatafull)) @@ -4194,7 +4190,7 @@ For JSON-relevant security implications please cf. at least the relevant subsect ## C.1 Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. ## C.2 Participants diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 83fc639c..35d02a8b 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -549,7 +549,7 @@

      1 Introduction

      The Open Data Protocol (OData) enables the creation of REST-based data services which allow resources, identified using Uniform Resource Locators (URLs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages. This specification defines the core semantics and the behavioral aspects of the protocol.

      The OData-URL specification defines a set of rules for constructing URLs to identify the data and metadata exposed by an OData service as well as a set of reserved URL query options.

      The OData-CSDLJSON specification defines a JSON representation of the entity data model exposed by an OData service.

      -

      The OData-CSDLXML specification defines an XML representation of the entity data model exposed by an OData service.

      +

      The OData-CSDLXML specification defines an XML representation of the entity data model exposed by an OData service.

      The OData-JSON document specifies the JSON format of the resource representations that are exchanged using OData.

      1.1 Changes from Earlier Versions

      @@ -704,7 +704,7 @@

      3 Data Model

      Operations allow the execution of custom logic on parts of a data model. Functions are operations that do not have side effects and may support further composition, for example, with additional filter operations, functions or an action. Actions are operations that allow side effects, such as data modification, and cannot be further composed in order to avoid non-deterministic behavior. Actions and functions are either bound to a type, enabling them to be called as members of an instance of that type, or unbound, in which case they are called as static operations. Action imports and function imports enable unbound actions and functions to be called from the service root.

      Singletons are named entities which can be accessed as direct children of the entity container. A singleton may also be a member of an entity set.

      An OData resource is anything in the model that can be addressed (an entity set, entity, property, or operation).

      -

      Refer to OData-CSDLJSON or OData-CSDLXML for more information on the OData entity data model.

      +

      Refer to OData-CSDLJSON or OData-CSDLXML for more information on the OData entity data model.

      3.1 Annotations

       @@ -729,7 +729,7 @@

      4 Service Mod

      4.1 Entity-Ids and Entity References

      Whereas entities within an entity set are uniquely identified by their key values, entities are also uniquely identified by a durable, opaque, globally unique entity-id. The entity-id MUST be an IRI as defined in RFC3987 and MAY be expressed in payloads, headers, and URLs as a relative reference as appropriate. While the client MUST be prepared to accept any IRI, services MUST use valid URIs in this version of the specification since there is currently no lossless representation of an IRI in the EntityId header.

      -

      Services are strongly encouraged to use the canonical URL for an entity as defined in OData-URL as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the Core.DereferenceableIDs term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource $entity provides a general mechanism for resolving an entity-id into an entity representation.

      +

      Services are strongly encouraged to use the canonical URL for an entity as defined in OData-URL, section 4.3.1 as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the Core.DereferenceableIDs term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource $entity provides a general mechanism for resolving an entity-id into an entity representation.

      Services that use the standard URL conventions for entity-ids annotate their entity container with the term Core.ConventionalIDs, see OData-VocCore.

      Entity references refer to an entity using the entity’s entity-id.

      @@ -739,7 +739,7 @@

      OData-URL for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention and must use the links specified in the payload according to the appropriate format as the two URLs may be different from one another, or one or both of them may differ from convention.

      +

      Services are strongly encouraged to use the canonical URL for an entity as defined in OData-URL, section 4.3.1 for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention and must use the links specified in the payload according to the appropriate format as the two URLs may be different from one another, or one or both of them may differ from convention.

      4.3 Transient Entities

      @@ -868,7 +868,7 @@

      media entity or stream property, in which case the Content-Type header SHOULD be present.

      The specified format MAY include format parameters. Clients MUST be prepared for the service to return custom format parameters not defined in OData and SHOULD NOT expect that such format parameters can be ignored. Custom format parameters MUST NOT start with odata and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload.

      -

      See OData-JSON for format-specific details about format parameters within the Content-Type header.

      +

      See OData-JSON, section 4.1 for format-specific details about format parameters within the Content-Type header.

      8.1.2 Header Content-Encoding

      @@ -1158,7 +1158,7 @@

      8.3.5 Header OData-Error

      A response with an in-stream error MAY include an OData-Error trailing header if the transport protocol supports trailing headers (e.g. HTTP/1.1 with chunked transfer encoding, or HTTP/2).

      -

      The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport in a header, see e.g. OData-JSON.

      +

      The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport in a header, see e.g. OData-JSON, section 21.2.

      8.3.6 Header Preference-Applied

      @@ -1593,14 +1593,14 @@

      10.19 $

      Context URL template:

      {context-url}#Collection(Edm.EntityType)
      -

      Responses to requests to the virtual collection $all (see OData-URL) use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton.

      +

      Responses to requests to the virtual collection $all (see OData-URL, section 4.16) use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton.

      10.20 $crossjoin Response

      Context URL template:

      {context-url}#Collection(Edm.ComplexType)
      -

      Responses to requests to the virtual collections $crossjoin(…) (see OData-URL) use the built-in abstract complex type. Single instances in these responses do not have a context URL.

      +

      Responses to requests to the virtual collections $crossjoin(…) (see OData-URL, section 4.15) use the built-in abstract complex type. Single instances in these responses do not have a context URL.

      @@ -1661,7 +1661,7 @@

      data model that describes the data and operations exposed by an OData service.

      OData-CSDLJSON describes a JSON representation for OData metadata documents and provides a JSON schema to validate their contents. The media type of the JSON representation of an OData metadata document is application/json.

      -

      OData-CSDLXML describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is application/xml.

      +

      OData-CSDLXML describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is application/xml.

      OData services can expose a metadata document that describes the data model exposed by the service. The metadata document URL MUST be the root URL of the service with $metadata appended. To retrieve this document the client issues a GET request to the metadata document URL.

      If a request for metadata does not specify a format preference (via Accept header or $format) then the XML representation MUST be returned.

      @@ -1704,7 +1704,7 @@

      11.2.2 Requesting Individual Entities

      To retrieve an individual entity, the client makes a GET request to a URL that identifies the entity, e.g. its read URL.

      -

      The read URL can be obtained from a response payload containing that instance, for example as a readLink or editLink in an OData-JSON payload. In addition, services MAY support conventions for constructing a read URL using the entity’s key value(s), as described in OData-URL.

      +

      The read URL can be obtained from a response payload containing that instance, for example as a readLink or editLink in an OData-JSON, section 4.6.9 payload. In addition, services MAY support conventions for constructing a read URL using the entity’s key value(s), as described in OData-URL, section 4.3.1.

      The set of structural or navigation properties to return may be specified through $select or $expand system query options.

      Clients MUST be prepared to receive additional properties in an entity or complex type instance that are not advertised in metadata, even for types not marked as open.

      Properties that are not available are not returned. If their unavailability is due to permissions, the Core.Permissions annotation, defined in OData-VocCore MUST be returned for the property with a value of None. If the omit-values preference is applied, Core.Permissions or another specific annotation that explains the reason MUST be returned for every unavailable property.

      @@ -1724,7 +1724,7 @@

      OData-URL for details.

      +

      See OData-URL, section 4.6 for details.

      If the property is single-valued and has the null value, the service responds with 204 No Content.

      If the property is not available, for example due to permissions, the service responds with 404 Not Found.

      @@ -1740,7 +1740,7 @@

      11.2.4.2 Requesting a Raw Value using $value

       -

      To retrieve the raw value of a primitive property or operation result, the client sends a GET request to the raw value URL. See the OData-URL document for details.

      +

      To retrieve the raw value of a primitive property or operation result, the client sends a GET request to the raw value URL. See OData-URL, section 4.7 for details.

      The Content-Type of the response is determined using the Accept header and the $format system query option.

      The default format for Edm.Binary is the format specified by the Core.MediaType annotation (see OData-VocCore) if this annotation is present. If not annotated, the format cannot be predicted by the client.

      The default format for Edm.Geo types is text/plain using the WKT (well-known text) format, see rules fullCollectionLiteral, fullLineStringLiteral, fullMultiPointLiteral, fullMultiLineStringLiteral, fullMultiPolygonLiteral, fullPointLiteral, and fullPolygonLiteral in OData-ABNF.

      @@ -1812,7 +1812,7 @@

      11.2.5.2.1 Expand Options

      -

      The 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.

      +

      The 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, section 5.1.3.

      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 41: 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

      @@ -2200,12 +2200,12 @@

      OData-JSON.

      +

      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, section 3.1.2.

      Example 75: 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.

      +

      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, section 3.1.1.

      In metadata document requests, the values application/xml and application/json, along with their subtypes and parameterized variants, as well as the format-specific abbreviations xml and json, are reserved for this specification.

      @@ -2569,7 +2569,7 @@

      11.

      11.4.6 Modifying Relationships between Entities

       -

      Relationships between entities are represented by navigation properties as described in Data Model. URL conventions for navigation properties are described in OData-URL.

      +

      Relationships between entities are represented by navigation properties as described in Data Model. URL conventions for navigation properties are described in OData-URL, section 4.3.3.

      11.4.6.1 Add a Reference to a Collection-Valued Navigation Property

       @@ -2581,7 +2581,7 @@

      11.4.6.2 Remove a Reference to an Entity

      A successful DELETE request to the URL that represents a reference to a related entity removes the relationship to that entity.

      -

      In OData 4.0, the entity reference to be removed within a collection-valued navigation property is the URL that represents the collection of related references, with the reference to be removed identified by the $id query option. OData 4.01 services additionally support using the URL that represents the reference of the collection member to be removed, identified by key, as described in OData-URL.

      +

      In OData 4.0, the entity reference to be removed within a collection-valued navigation property is the URL that represents the collection of related references, with the reference to be removed identified by the $id query option. OData 4.01 services additionally support using the URL that represents the reference of the collection member to be removed, identified by key, as described in OData-URL, section 4.4.

      For single-valued navigation properties, the $id query option MUST NOT be specified.

      The DELETE request MUST NOT violate any integrity constraints in the data model.

      On successful completion, the response MUST be 204 No Content and contain an empty body.

      @@ -2591,7 +2591,7 @@

      A successful PUT request to a single-valued navigation property’s reference resource changes the related entity. The request body MUST contain a single entity reference that identifies the existing entity to be related. See the appropriate format document for details.

      On successful completion, the response MUST be 204 No Content and contain an empty body.

      -

      Alternatively, a relationship MAY be updated as part of an update to the source entity by including the required binding information for the new target entity. This binding information is format-specific, see OData-JSON for details.

      +

      Alternatively, a relationship MAY be updated as part of an update to the source entity by including the required binding information for the new target entity. This binding information is format-specific, see OData-JSON, section 15.4 for details.

      If the single-valued navigation property is used in the key definition of an entity type, it cannot be changed and the request MUST fail with 405 Method Not Allowed or an other appropriate error.

      @@ -2680,7 +2680,7 @@

      11.4.9 Managing Values and Properties Directly

       -

      Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows properties to be individually modified. See OData-URL for details on addressing individual properties.

      +

      Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows properties to be individually modified. See OData-URL, section 4.6 for details on addressing individual properties.

      11.4.9.1 Update a Primitive Property

       @@ -2790,7 +2790,7 @@

      11.4.14 Update Members of a Collection

      Members of a collection can be updated by submitting a PATCH request to the URL constructed by appending /$each to the resource path of the collection. The additional path segment expresses that the request body describes an update to each member of the collection, not an update to the collection itself.

      -

      The resource path of the collection MAY contain type-cast or filter segments to subset the collection, see OData-URL.

      +

      The resource path of the collection MAY contain type-cast or filter segments to subset the collection, see OData-URL, section 4.11 and OData-URL, section 4.12.

      For primitive-typed collections the body of the request MUST be a primitive value. Each member of the potentially filtered collection is updated to the specified primitive value.

      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.

      @@ -2825,7 +2825,7 @@

      11.5 Operations

       -

      Custom operations (Actions and Functions) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See Action, ActionImport, Function, and FunctionImport in OData-CSDLJSON or OData-CSDLXML.

      +

      Custom operations (Actions and Functions) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See Action, ActionImport, Function, and FunctionImport in OData-CSDLJSON or OData-CSDLXML.

      11.5.1 Binding an Operation to a Resource

       @@ -2884,7 +2884,7 @@

      … }

      -

      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.

      +

      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, section 4.5.

      Services can advertise that a function or action is not available for a particular instance by setting its value to null.

      Example 93: the SampleEntities.MostRecentOrder function is not available for customer ALFKI

      @@ -2922,7 +2922,7 @@

      204 No Content.

      If a single-valued function with a non-nullable return type has no result, the service returns 4xx. For functions that return a single entity 404 Not Found is the appropriate response code.

      For a composable function the processing is stopped when the function result requires a 4xx response, and continues otherwise.

      -

      Function imports preceded by the $root literal MAY be used in the $filter or $orderby system query options, see OData-URL.

      +

      Function imports preceded by the $root literal MAY be used in the $filter or $orderby system query options, see OData-URL, section 5.1.2 and OData-URL, section 5.1.5.

      11.5.4.1.1 Inline Parameter Syntax
       @@ -2955,7 +2955,7 @@

      The same function name may be used multiple times within a schema, each with a different set of parameters. For unbound overloads the combination of the function name and the unordered set of parameter names MUST identify a particular function overload. For bound overloads the combination of the function name, the binding parameter type, and the unordered set of names of the non-binding parameters MUST identify a particular function overload.

      All unbound overloads MUST have the same return type. Also, all bound overloads with a given binding parameter type MUST have the same return type.

      -

      If the function is bound and the binding parameter type is part of an inheritance hierarchy, the function overload is selected based on the type of the URL segment preceding the function name. A type-cast segment can be used to select a function defined on a particular type in the hierarchy, see OData-URL.

      +

      If the function is bound and the binding parameter type is part of an inheritance hierarchy, the function overload is selected based on the type of the URL segment preceding the function name. A type-cast segment can be used to select a function defined on a particular type in the hierarchy, see OData-URL, section 4.11.

      Non-binding parameters MAY be marked as optional by annotating them with the term Core.OptionalParameter defined in OData-VocCore. All parameters marked as optional MUST come after any parameters not marked as optional.

      A function overload is selected if

        @@ -3002,7 +3002,7 @@

        11.5.5.2 Action Overload Resolution

        The same action name may be used multiple times within a schema provided there is at most one unbound overload, and each bound overload specifies a different binding parameter type.

        -

        If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, see OData-URL.

        +

        If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, see OData-URL, section 4.11.

      @@ -3027,7 +3027,7 @@

      11.7 Bat

      Batch requests allow grouping multiple individual requests into a single HTTP request payload. An individual request in the context of a batch request is a Metadata Request, Data Request, Data Modification Request, Action invocation request, or Function invocation request.

      Batch requests are submitted as a single HTTP POST request to the batch endpoint of a service, located at the URL $batch relative to the service root.

      Individual requests within a batch request are evaluated according to the same semantics used when the request appears outside the context of a batch request.

      -

      A batch request is represented using either the multipart batch format defined in this document or the JSON batch format defined in OData-JSON.

      +

      A batch request is represented using either the multipart batch format defined in this document or the JSON batch format defined in OData-JSON, section 19.

      If the set of request headers of a batch request are valid the service MUST return a 200 OK HTTP response code to indicate that the batch request was accepted for processing, even if the processing is yet to be completed. The individual requests within the body of the batch request may be processed as soon as they are received, this enables clients to stream batch requests, and batch implementations to stream the results.

      If the service receives a batch request with an invalid set of headers it MUST return a 4xx response code and perform no further processing of the batch request.

      @@ -3516,12 +3516,12 @@

      section 6 and all subsections)
    • MUST successfully parse the request according to OData-ABNF for any supported system query options and follow the specification or fail the request
      • -
    • MUST expose only data types defined in OData-CSDLXML
      • +
    • MUST expose only data types defined in OData-CSDLXML
    • MUST NOT require clients to understand any metadata or instance annotations (section 6.4), custom headers (section 6.5), or custom content (section 6.2) in the payload in order to correctly consume the service
    • MUST NOT violate any OData update semantics (section 11.4 and all subsections)
    • MUST NOT violate any other OData-defined semantics
    • SHOULD support $expand (section 11.2.5.2)
      • -
    • SHOULD publish metadata at $metadata according to OData-CSDLXML and MAY publish metadata according to OData-CSDLJSON (section 11.1.2)
      • +
    • SHOULD publish metadata at $metadata according to OData-CSDLXML and MAY publish metadata according to OData-CSDLJSON (section 11.1.2)
    • MUST support prefixed variants of supported headers and preference values
    • MUST support enumeration and duration literals in URLs with the type prefix
      • @@ -3532,7 +3532,7 @@

      -
    • MUST include edit links (explicitly or implicitly) for all updatable or deletable resources according to OData-JSON
      • +
    • MUST include edit links (explicitly or implicitly) for all updatable or deletable resources according to OData-JSON, section 4.6.9
    • MUST support POST of new entities to insertable entity sets (section 11.4.1.5)
    • MUST support POST of new related entities to updatable navigation properties (section 11.4.2)
    • MUST support POST to $ref to add an existing entity to an updatable related collection (section 11.4.6.1)
      • @@ -3558,7 +3558,7 @@

      OData 4.0 Minimal Conformance Level
    • MUST successfully parse the request according to OData-ABNF and follow the specification or fail the request
    • MUST support $select (section 11.2.5.1)
      • -
    • MUST support casting to a derived type according to OData-URL if derived types are present in the model
      • +
    • MUST support casting to a derived type according to OData-URL, section 4.11 if derived types are present in the model
    • MUST support $top (section 11.2.6.3)
    • MUST support /$value on media entities (section 11.1.2) and individual properties (section 11.2.4.2)
    • MUST support $filter (section 11.2.6.1) @@ -3569,7 +3569,7 @@

      section 11.2.6.1.2) and MUST fail the request for any unsupported canonical functions

    • SHOULD support $filter on expanded entities (section 11.2.5.2.1)
      • -
    • SHOULD publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
      • +
    • SHOULD publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
    • SHOULD support the OData-JSON format
    • SHOULD consider supporting basic authentication as defined in RFC7617 over HTTPS for the highest level of interoperability with generic clients
    • SHOULD support the $search system query option (section 11.2.6.6)
      • @@ -3587,7 +3587,7 @@

    • MUST conform to at least the OData 4.0 Intermediate Conformance Level
      • -
    • MUST publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
      • +
    • MUST publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
    • MUST support the OData-JSON format
    • MUST support the /$count segment on navigation and collection properties (section 11.2.10)
    • MUST support the lambda operators any and all on navigation- and and collection-valued properties (OData-URL, section 5.1.1.13)
      • @@ -3607,11 +3607,11 @@

      section 11.2.6.6) -
    • MUST support batch requests according to the multipart format (section 11.7 and all subsections) and MAY support batch requests according to the JSON Batch format defined in OData-JSON
      • -
    • MUST support the resource path conventions defined in OData-URL
      • +
    • MUST support batch requests according to the multipart format (section 11.7 and all subsections) and MAY support batch requests according to the JSON Batch format defined in OData-JSON, section 19
      • +
    • MUST support the resource path conventions defined in OData-URL, section 4
    • SHOULD support asynchronous requests (section 11.6)
    • SHOULD support Delta change tracking (section 11.3)
      • -
    • SHOULD support cross-join queries defined in OData-URL
      • +
    • SHOULD support cross-join queries defined in OData-URL, section 4.15
    • MAY support the $compute system query option (section 11.2.5.3)

      • @@ -3648,12 +3648,12 @@

      -
    • MUST also support canonical URL conventions (described in OData-URL) or include URLs in payload
      • +
    • MUST also support canonical URL conventions (described in OData-URL, section 4.3.1) or include URLs in payload
    • MAY support the count of a filtered collection in a common expression
    • MAY support equal and non-equal structural comparison
      • -
    • SHOULD publish metadata at $metadata according to both OData-CSDLXML and OData-CSDLJSON (section 11.1.2)
      • +
    • SHOULD publish metadata at $metadata according to both OData-CSDLXML and OData-CSDLJSON (section 11.1.2)
    • SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case
    • SHOULD return the Core.ODataVersions annotation
    • SHOULD report capabilities through the Capabilities vocabulary
      • @@ -3712,7 +3712,7 @@

      OData-CSDLJSON (section 11.1.2) -
    • MUST support batch requests according both to the multipart format (section 11.7 and all subsections) and the JSON Batch format defined in OData-JSON
      • +
    • MUST support batch requests according both to the multipart format (section 11.7 and all subsections) and the JSON Batch format defined in OData-JSON, section 19
    • SHOULD support filtering a collection using a /$filter path segment
    • SHOULD support nested parameter alias assignments in $select and $expand
    • MAY support case-insensitive comparison of identifiers in URLs and request payloads if no exact match is found, using the same lookup sequence as for default namespaces with a case-insensitive comparison
      • @@ -3727,7 +3727,7 @@

    • MUST specify the OData-MaxVersion header in requests (section 8.2.7)
    • MUST specify OData-Version (section 8.1.5) and Content-Type (section 8.1.1) in any request with a payload
      • -
    • MUST be a conforming consumer of OData as defined in OData-JSON
      • +
    • MUST be a conforming consumer of OData as defined in OData-JSON, section 23
    • MUST follow redirects (section 9.1.5)
    • MUST correctly handle next links (section 11.2.6.7)
    • MUST support instances returning properties and navigation properties not specified in metadata (section 11.2)
      • @@ -3739,8 +3739,8 @@

      MAY request entity references in place of entities previously returned in the response (section 11.2.8)
    • MAY support deleted entities, link entities, deleted link entities in a delta response (section 11.3)
    • MAY support asynchronous responses (section 11.6)
      • -
    • MAY support metadata=minimal in a JSON response (see OData-JSON)
      • -
    • MAY support streaming in a JSON response (see OData-JSON)
      • +
    • MAY support metadata=minimal in a JSON response (see OData-JSON, section 3.1.1)
      • +
    • MAY support streaming in a JSON response (see OData-JSON, section 4.5)

      • In addition, interoperable OData 4.01 clients

        @@ -3768,9 +3768,10 @@
        OData-ABNF
        OData-Aggregation

        OData Extension for Data Aggregation Version 4.02.
        See link in “Related work” section on cover page.

        -
        OData-CSDL
        +
        OData-CSDLJSON

        OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02.
        See link in “Related work” section on cover page.

        +
        OData-CSDLXML

        OData Common Schema Definition Language (CSDL) XML Representation Version 4.02.
        See link in “Related work” section on cover page.

        OData-JSON
        diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index 049d318e..88e7ac8d 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -344,7 +344,7 @@ service as well as a set of reserved URL query options. The [OData-CSDLJSON](#ODataCSDL) specification defines a JSON representation of the entity data model exposed by an OData service. -The [OData-CSDLXML](#ODataCSDL) specification defines an XML +The [OData-CSDLXML](#ODataCSDLXML) specification defines an XML representation of the entity data model exposed by an OData service. The [OData-JSON](#ODataJSON) document specifies the JSON format of the @@ -526,7 +526,7 @@ set. An OData *resource* is anything in the model that can be addressed (an entity set, entity, property, or operation). -Refer to [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) for +Refer to [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDLXML) for more information on the OData entity data model. ## 3.1 Annotations @@ -585,7 +585,7 @@ of the specification since there is currently no lossless representation of an IRI in the [`EntityId`](#HeaderODataEntityId) header. Services are strongly encouraged to use the canonical URL for an entity -as defined in [OData-URL](#ODataURL) as its entity-id, but clients cannot assume +as defined in [OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL) as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the [`Core.DereferenceableIDs`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DereferenceableIDs) term is applied to the entity container, nor can the client assume any @@ -612,7 +612,7 @@ The edit URL of a property is the edit URL of the entity with appended segment(s) containing the path to the property. Services are strongly encouraged to use the canonical URL for an entity -as defined in [OData-URL](#ODataURL) for both the read URL and the edit URL of an +as defined in [OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL) for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention @@ -923,7 +923,7 @@ ignored. Custom format parameters MUST NOT start with `odata` and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload. -See [OData-JSON](#ODataJSON) for format-specific details about format +See [OData-JSON, section 4.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#HeaderContentType) for format-specific details about format parameters within the `Content-Type` header. ### 8.1.2 Header `Content-Encoding` @@ -1734,7 +1734,7 @@ HTTP/2). The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport -in a header, see e.g. [OData-JSON](#ODataJSON). +in a header, see e.g. [OData-JSON, section 21.2](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InStreamError). ### 8.3.6 Header `Preference-Applied` @@ -2546,7 +2546,7 @@ Context URL template: {context-url}#Collection(Edm.EntityType) Responses to requests to the virtual collection `$all` (see -[OData-URL](#ODataURL)) use the built-in abstract entity type. Each +[OData-URL, section 4.16](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingAllEntitiesinaService)) use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton. @@ -2557,7 +2557,7 @@ Context URL template: {context-url}#Collection(Edm.ComplexType) Responses to requests to the virtual collections `$crossjoin(…)` (see -[OData-URL](#ODataURL)) use the built-in abstract complex type. Single +[OData-URL, section 4.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets)) use the built-in abstract complex type. Single instances in these responses do not have a context URL. @@ -2629,7 +2629,7 @@ metadata documents and provides a JSON schema to validate their contents. The media type of the JSON representation of an OData metadata document is `application/json`. -[OData-CSDLXML](#ODataCSDL) describes an XML representation for OData +[OData-CSDLXML](#ODataCSDLXML) describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is `application/xml`. @@ -2713,9 +2713,9 @@ URL that identifies the entity, e.g. its read URL. The read URL can be obtained from a response payload containing that instance, for example as a `readLink` or `editLink` in an -[OData-JSON](#ODataJSON) payload. In addition, services +[OData-JSON, section 4.6.9](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink) payload. In addition, services MAY support conventions for constructing a read URL using the entity's -key value(s), as described in [OData-URL](#ODataURL). +key value(s), as described in [OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The set of structural or navigation properties to return may be specified through [`$select`](#SystemQueryOptionselect) or @@ -2775,7 +2775,7 @@ the property name appended. For complex typed properties, the path can be further extended with the name of an individual property of the complex type. -See [OData-URL](#ODataURL) for details. +See [OData-URL, section 4.6](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaProperty) for details. If the property is single-valued and has the `null` value, the service responds with [`204 No Content`](#ResponseCode204NoContent). @@ -2805,7 +2805,7 @@ system query option. #### 11.2.4.2 Requesting a Raw Value using `$value` To retrieve the raw value of a primitive property or operation result, the client sends -a `GET` request to the raw value URL. See the [OData-URL](#ODataURL) document for details. +a `GET` request to the raw value URL. See [OData-URL, section 4.7](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaRawValue) for details. The `Content-Type` of the response is determined using the `Accept` header and the [`$format`](#SystemQueryOptionformat) system query @@ -3004,7 +3004,7 @@ GET http://host/service.svc/Customers?$expand=Photo The 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](#ODataURL). +[OData-URL, section 5.1.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionexpand). Allowed system query options are [`$compute`](#SystemQueryOptioncompute), @@ -3794,7 +3794,7 @@ 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](#ODataJSON). +[OData-JSON, section 3.1.2](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadatafullodatametadatafull). ::: example Example 75: the request @@ -3806,7 +3806,7 @@ 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](#ODataJSON). +[OData-JSON, section 3.1.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadataminimalodatametadataminimal). In [metadata document requests](#MetadataDocumentRequest), the values `application/xml` and `application/json`, along with their subtypes and @@ -4737,7 +4737,7 @@ deleted, the dependent entity is also deleted. Relationships between entities are represented by navigation properties as described in [Data Model](#DataModel). URL conventions for navigation -properties are described in [OData-URL](#ODataURL). +properties are described in [OData-URL, section 4.3.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#URLsforRelatedEntitieswithReferentialConstraints). #### 11.4.6.1 Add a Reference to a Collection-Valued Navigation Property @@ -4763,7 +4763,7 @@ collection of related references, with the reference to be removed identified by the [`$id`](#ResolvinganEntityId) query option. OData 4.01 services additionally support using the URL that represents the reference of the collection member to be removed, identified by key, as -described in [OData-URL](#ODataURL). +described in [OData-URL, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingReferencesbetweenEntities). For single-valued navigation properties, the [`$id`](#ResolvinganEntityId) query option MUST NOT be specified. @@ -4787,7 +4787,7 @@ On successful completion, the response MUST be Alternatively, a relationship MAY be updated as part of an update to the source entity by including the required binding information for the new target entity. This binding information is format-specific, see -[OData-JSON](#ODataJSON) for details. +[OData-JSON, section 15.4](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#RelatedEntities) for details. If the single-valued navigation property is used in the key definition of an entity type, it cannot be changed and the request MUST fail with @@ -4980,7 +4980,7 @@ Attempting to request a stream property whose value is null results in Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows -properties to be individually modified. See [OData-URL](#ODataURL) for +properties to be individually modified. See [OData-URL, section 4.6](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaProperty) for details on addressing individual properties. #### 11.4.9.1 Update a Primitive Property @@ -5265,7 +5265,8 @@ describes an update to each member of the collection, not an update to the collection itself. The resource path of the collection MAY contain type-cast or filter -segments to subset the collection, see [OData-URL](#ODataURL). +segments to subset the collection, see [OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes) and +[OData-URL, section 4.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaSubsetofaCollection). For primitive-typed collections the body of the request MUST be a primitive value. Each member of the potentially filtered collection is @@ -5362,7 +5363,7 @@ Custom operations ([Actions](#Actions) and [Functions](#Functions)) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See `Action`, `ActionImport`, `Function`, and `FunctionImport` in -[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL). +[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDLXML). ### 11.5.1 Binding an Operation to a Resource @@ -5481,7 +5482,7 @@ bound to the entity 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](#ODataURL). +[OData-URL, section 4.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingOperations). Services can advertise that a function or action is not available for a particular instance by setting its value to null. @@ -5608,7 +5609,7 @@ result requires a `4xx` response, and continues otherwise. Function imports preceded by the `$root` literal MAY be used in the [`$filter`](#SystemQueryOptionfilter) or [`$orderby`](#SystemQueryOptionorderby) system query options, see -[OData-URL](#ODataURL). +[OData-URL, section 5.1.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionfilter) and [OData-URL, section 5.1.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionorderby). ##### 11.5.4.1.1 Inline Parameter Syntax @@ -5696,7 +5697,7 @@ If the function is bound and the binding parameter type is part of an inheritance hierarchy, the function overload is selected based on the type of the URL segment preceding the function name. A type-cast segment can be used to select a function defined on a particular type in the -hierarchy, see [OData-URL](#ODataURL). +hierarchy, see [OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes). Non-binding parameters MAY be marked as optional by annotating them with the term @@ -5832,7 +5833,7 @@ If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, -see [OData-URL](#ODataURL). +see [OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes). ## 11.6 Asynchronous Requests @@ -5927,7 +5928,7 @@ a batch request. A batch request is represented using either the [multipart batch format](#MultipartBatchFormat) defined in this document or the JSON -batch format defined in [OData-JSON](#ODataJSON). +batch format defined in [OData-JSON, section 19](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses). If the set of request headers of a batch request are valid the service MUST return a [`200 OK`](#ResponseCode200OK) HTTP response code to @@ -6686,7 +6687,7 @@ request 7. MUST successfully parse the request according to [OData-ABNF](#ODataABNF) for any supported system query options and follow the specification or fail the request -8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDL) +8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDLXML) 9. MUST NOT require clients to understand any metadata or instance annotations ([section 6.4](#VocabularyExtensibility)), custom headers ([section 6.5](#HeaderFieldExtensibility)), or custom content ([section 6.2](#PayloadExtensibility)) in the payload in order to correctly consume the @@ -6696,7 +6697,7 @@ service 11. MUST NOT violate any other OData-defined semantics 12. SHOULD support `$expand` ([section 11.2.5.2](#SystemQueryOptionexpand)) 13. SHOULD publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) and MAY publish metadata according to +[OData-CSDLXML](#ODataCSDLXML) and MAY publish metadata according to [OData-CSDLJSON](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) 14. MUST support prefixed variants of supported headers and preference values @@ -6714,7 +6715,7 @@ final response to an asynchronous request To be considered an *Updatable OData Service*, the service additionally: 18. MUST include edit links (explicitly or implicitly) for all -updatable or deletable resources according to [OData-JSON](#ODataJSON) +updatable or deletable resources according to [OData-JSON, section 4.6.9](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink) 19. MUST support `POST` of new entities to insertable entity sets ([section 11.4.1.5](#ReturningResultsfromDataModificationRequests)) 20. MUST support `POST` of new related entities to updatable navigation @@ -6755,7 +6756,7 @@ Level](#OData40MinimalConformanceLevel) follow the specification or fail the request 3. MUST support `$select` ([section 11.2.5.1](#SystemQueryOptionselect)) 4. MUST support casting to a derived type according to -[OData-URL](#ODataURL) if derived types are present in the model +[OData-URL, section 4.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes) if derived types are present in the model 5. MUST support `$top` ([section 11.2.6.3](#SystemQueryOptiontop)) 6. MUST support `/$value` on media entities ([section 11.1.2](#MetadataDocumentRequest)) and individual properties ([section 11.2.4.2](#RequestingaRawValueusingvalue)) 7. MUST support `$filter` ([section 11.2.6.1](#SystemQueryOptionfilter)) @@ -6769,7 +6770,7 @@ operations MUST fail the request for any unsupported canonical functions 5. SHOULD support `$filter` on expanded entities ([section 11.2.5.2.1](#ExpandOptions)) 8. SHOULD publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) +[OData-CSDLXML](#ODataCSDLXML) ([section 11.1.2](#MetadataDocumentRequest)) 9. SHOULD support the [OData-JSON](#ODataJSON) format 10. SHOULD consider supporting basic authentication as defined in [RFC7617](#rfc7617) over HTTPS for the highest level of interoperability @@ -6792,7 +6793,7 @@ In order to conform to the OData Advanced Conformance Level, a service: 1. MUST conform to at least the [OData 4.0 Intermediate Conformance Level](#OData40IntermediateConformanceLevel) 2. MUST publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) +[OData-CSDLXML](#ODataCSDLXML) ([section 11.1.2](#MetadataDocumentRequest)) 3. MUST support the [OData-JSON](#ODataJSON) format 4. MUST support the `/$count` segment on navigation and collection properties ([section 11.2.10](#RequestingtheNumberofItemsinaCollection)) @@ -6817,13 +6818,13 @@ properties 10. MUST support the `$search` system query option ([section 11.2.6.6](#SystemQueryOptionsearch)) 11. MUST support batch requests according to the multipart format ([section 11.7](#BatchRequests) and all subsections) and MAY support batch requests -according to the JSON Batch format defined in [OData-JSON](#ODataJSON) +according to the JSON Batch format defined in [OData-JSON, section 19](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses) 12. MUST support the resource path conventions defined in -[OData-URL](#ODataURL) +[OData-URL, section 4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ResourcePath) 13. SHOULD support asynchronous requests ([section 11.6](#AsynchronousRequests)) 14. SHOULD support Delta change tracking ([section 11.3](#RequestingChanges)) -15. SHOULD support cross-join queries defined in [OData-URL](#ODataURL) +15. SHOULD support cross-join queries defined in [OData-URL, section 4.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets) 16. MAY support the `$compute` system query option ([section 11.2.5.3](#SystemQueryOptioncompute)) ## 12.2 OData 4.01 Service Conformance Levels @@ -6884,12 +6885,12 @@ with a maximum cardinality of one 11. SHOULD support negative indexes for the substring function 12. MAY support Key-As-Segment URL convention 1. MUST also support canonical URL conventions (described in -[OData-URL](#ODataURL)) or include URLs in payload +[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL)) or include URLs in payload 13. MAY support the count of a filtered collection in a common expression 14. MAY support equal and non-equal structural comparison 10. SHOULD publish metadata at `$metadata` according to both -[OData-CSDLXML](#ODataCSDL) and [OData-CSDLJSON](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) +[OData-CSDLXML](#ODataCSDLXML) and [OData-CSDLJSON](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) 11. SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case @@ -6971,7 +6972,7 @@ properties [OData-CSDLJSON](#ODataCSDL) ([section 11.1.2](#MetadataDocumentRequest)) 7. MUST support batch requests according both to the multipart format ([section 11.7](#BatchRequests) and all subsections) and the JSON Batch format defined in -[OData-JSON](#ODataJSON) +[OData-JSON, section 19](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses) 8. SHOULD support filtering a collection using a `/$filter` path segment 9. SHOULD support nested parameter alias assignments in @@ -6994,7 +6995,7 @@ To be generally interoperable, OData clients 2. MUST specify `OData-Version` ([section 8.1.5](#HeaderODataVersion)) and `Content-Type` ([section 8.1.1](#HeaderContentType)) in any request with a payload 3. MUST be a conforming consumer of OData as defined in -[OData-JSON](#ODataJSON) +[OData-JSON, section 23](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#Conformance) 4. MUST follow redirects ([section 9.1.5](#ResponseCode3xxRedirection)) 5. MUST correctly handle next links ([section 11.2.6.7](#ServerDrivenPaging)) 6. MUST support instances returning properties and navigation @@ -7014,9 +7015,9 @@ returned in the response ([section 11.2.8](#RequestingEntityReferences)) in a delta response ([section 11.3](#RequestingChanges)) 14. MAY support asynchronous responses ([section 11.6](#AsynchronousRequests)) 15. MAY support `metadata=minimal` in a JSON response (see -[OData-JSON](#ODataJSON)) +[OData-JSON, section 3.1.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadataminimalodatametadataminimal)) 16. MAY support `streaming` in a JSON response (see -[OData-JSON](#ODataJSON)) +[OData-JSON, section 4.5](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PayloadOrderingConstraints)) In addition, interoperable OData 4.01 clients @@ -7054,10 +7055,11 @@ See link in "[Related work](#RelatedWork)" section on cover page. _OData Extension for Data Aggregation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. -###### [OData-CSDL]{id=ODataCSDL} +###### [OData-CSDLJSON]{id=ODataCSDL} _OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-CSDLXML]{id=ODataCSDLXML} _OData Common Schema Definition Language (CSDL) XML Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. diff --git a/docs/odata-temporal-ext/odata-temporal-ext.html b/docs/odata-temporal-ext/odata-temporal-ext.html index e5101e38..9891561a 100644 --- a/docs/odata-temporal-ext/odata-temporal-ext.html +++ b/docs/odata-temporal-ext/odata-temporal-ext.html @@ -1929,7 +1929,7 @@

        Changes to a temporal object over a period of application time can affect multiple time slices. For timeline entity sets this can in principle be achieved by constructing batch requests with multiple operations on individual time slices. This puts burden on the client, and it also makes it harder for services to check whether the request represents a consistent change of the temporal data.

        Both can be avoided by providing convenience operations expressing the intent of the modification and leaving the actual time slice manipulation to the service. These operations can then also be used with snapshot entity sets that do not allow direct manipulation of time slices.

        -

        These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data OData-VocTemporal. Implementations SHOULD consider the preferences return=representation and return=minimal as specified invOData-Protocol. The convenience operations are atomic (all or nothing): they either succeed and produce the result described below, or they fail and do not change the temporal objects.

        +

        These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data OData-VocTemporal. Implementations SHOULD consider the preferences return=representation and return=minimal as specified in OData-Protocol, section 8.2.8.7. The convenience operations are atomic (all or nothing): they either succeed and produce the result described below, or they fail and do not change the temporal objects.

        All actions define a collection of entities as their binding parameter. This collection can be

        • A snapshot entity set
          • @@ -1949,7 +1949,7 @@

          OData-Protocol. +
        • Then all fully included time slices (including ones created in the previous step) are updated following the rules for updating entities specified in OData-Protocol, section 11.4.3.
        • Gaps between selected time slices in the period to update are not affected.

      On success it returns the created or updated time slices.

      @@ -2215,9 +2215,9 @@

    • copying the property values of the preceding time slice (except for computed properties),
    • setting the period boundaries to close the gap, and then
      • -
    • updating the new time slice following the rules for updating entities specified in OData-Protocol.
      • +
    • updating the new time slice following the rules for updating entities specified in OData-Protocol, section 11.4.3.
      • -

      If no preceding time slice exists, the time slice is created following the rules for creating entities specified in OData-Protocol.

      +

      If no preceding time slice exists, the time slice is created following the rules for creating entities specified in OData-Protocol, section 11.4.2.

      On success it returns the created or updated time slices.

      @@ -2396,7 +2396,7 @@

      OData-Protocol. +
    • Then all fully included time slices (including ones created in the previous step) are deleted following the rules for deleting entities specified in OData-Protocol, section 11.4.5.

      • On success it returns the deleted time slices.

      @@ -2488,7 +2488,7 @@

      B.1 Special Thanks

      -

      The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol are gratefully acknowledged.

      +

      The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

      Special thanks to Andrew Eisenberg, whose contributions in the early stages of the OData TC were invaluable to getting this extension specification on track.

      diff --git a/docs/odata-temporal-ext/odata-temporal-ext.md b/docs/odata-temporal-ext/odata-temporal-ext.md index 680d0dfe..a3dc7892 100644 --- a/docs/odata-temporal-ext/odata-temporal-ext.md +++ b/docs/odata-temporal-ext/odata-temporal-ext.md @@ -2008,7 +2008,7 @@ slices. These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data [OData-VocTemporal](#ODataVocTemporal). Implementations SHOULD consider the preferences `return=representation` -and `return=minimal` as specified inv[OData-Protocol](#ODataProtocol). +and `return=minimal` as specified in [OData-Protocol, section 8.2.8.7](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Preferencereturnrepresentationandreturnminimal). The convenience operations are atomic (all or nothing): they either succeed and produce the result described below, or they fail and do not change the temporal objects. @@ -2062,7 +2062,7 @@ This works identical to the SQL statement UPDATE FOR PORTION OF: slice's period. 4. Then all fully included time slices (including ones created in the previous step) are updated following the rules for updating entities - specified in [OData-Protocol](#ODataProtocol). + specified in [OData-Protocol, section 11.4.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity). 5. Gaps between selected time slices in the period to update are not affected. On success it returns the created or updated time slices. @@ -2255,10 +2255,10 @@ Step 5 is (except for computed properties), 2. setting the period boundaries to close the gap, and then 3. updating the new time slice following the rules for updating - entities specified in [OData-Protocol](#ODataProtocol). + entities specified in [OData-Protocol, section 11.4.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity). If no preceding time slice exists, the time slice is created following - the rules for creating entities specified in [OData-Protocol](#ODataProtocol). + the rules for creating entities specified in [OData-Protocol, section 11.4.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#CreateanEntity). On success it returns the created or updated time slices. @@ -2404,7 +2404,7 @@ This works identical to the SQL statement DELETE FOR PORTION OF: slices, one with non-overlapping, and one with fully included period. 4. Then all fully included time slices (including ones created in the previous step) are deleted following the rules for deleting entities - specified in [OData-Protocol](#ODataProtocol). + specified in [OData-Protocol, section 11.4.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DeleteanEntity). On success it returns the deleted time slices. @@ -2519,7 +2519,7 @@ _ISO/IEC 9075-2:2011 Information technology - Database languages - SQL - Part 2: ## B.1 Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully acknowledged. Special thanks to Andrew Eisenberg, whose contributions in the early stages of the OData TC were invaluable to getting this extension specification on track. diff --git a/docs/odata-url-conventions/odata-url-conventions.html b/docs/odata-url-conventions/odata-url-conventions.html index 12226e4d..147e9a2b 100644 --- a/docs/odata-url-conventions/odata-url-conventions.html +++ b/docs/odata-url-conventions/odata-url-conventions.html @@ -559,7 +559,7 @@

      2.2 URL Syntax

      3 Service Root URL

       -

      The service root URL identifies the root of an OData service. A GET request to this URL returns the format-specific service document, see OData-JSON.

      +

      The service root URL identifies the root of an OData service. A GET request to this URL returns the format-specific service document, see OData-JSON, section 5.

      The service root URL MUST terminate in a forward slash.

      The service document enables simple hypermedia-driven clients to enumerate and explore the resources published by the OData service.

      @@ -575,7 +575,7 @@

      4 Resource Pa

      4.1 Addressing the Model for a Service

       -

      OData services expose their entity model according to OData-CSDLJSON or OData-CSDLXML at the metadata URL, formed by appending $metadata to the service root URL.

      +

      OData services expose their entity model according to OData-CSDL at the metadata URL, formed by appending $metadata to the service root URL.

      Example 5: Metadata document URL

      http://host/service/$metadata
      @@ -721,7 +721,7 @@

      4.3.1 Canon

      4.3.2 Canonical URL for Contained Entities

       -

      For contained entities (i.e. related via a containment navigation property, see OData-CSDLJSON or OData-CSDLXML) the canonical URL is the canonical URL of the containing entity followed by:

      +

      For contained entities (i.e. related via a containment navigation property, see OData-CSDLJSON) the canonical URL is the canonical URL of the containing entity followed by:

      • A type-cast segment if the navigation property is defined on a type derived from the entity type declared for the entity set,
      • A path segment for the containment navigation property, and
        • @@ -752,7 +752,7 @@

        OData-Protocol document.

        +

        The semantics of $entity are covered in OData-Protocol, section 10.

      4.3.5 Alternate Keys

      @@ -797,7 +797,7 @@

    • matches a defined OData segment (starting with “$”), treat it as such
    • matches a qualified bound function, bound action, or type name, treat it as such
      • -
    • matches an unqualified bound function, bound action, or type name defined in a default namespace (see OData-Protocol) treat it as such
      • +
    • matches an unqualified bound function, bound action, or type name defined in a default namespace (see OData-Protocol, section 4.4) treat it as such
    • treat as a key value

      • For maximum interoperability, services that support the key-as-segment convention SHOULD also support the canonical parentheses-style convention for addressing an entity within a collection, otherwise they MUST specify the URL for each returned entity in a response, as specified by the particular format.

      @@ -813,7 +813,7 @@

      OData-Protocol.

      +

      Resource paths addressing a single related entity reference can be used in DELETE requests to unrelate two entities. In OData 4.01, this includes resource paths that identify an individual entity reference within a related collection by key. In OData 4.0, resource paths addressing a collection of references MUST be followed by the system query option $id in order to identify a single entity reference within the collection to be removed. The entity-id specified by $id may be expressed absolute or relative to the request URL. For details see OData-Protocol, section 4.1.

      Example 29: three ways of unrelating Categories(1) and Products(0); the second option is supported only in OData 4.01

      DELETE http://host/service/Categories(1)/Products/$ref?$id=../../Products(0)
      @@ -824,8 +824,8 @@

      4.5 Addressing Operations

       -

      The semantic rules for addressing and invoking actions and functions are defined in the OData-Protocol document.

      -

      Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol.

      +

      The semantic rules for addressing and invoking actions and functions are defined in OData-Protocol, section 11.5.

      +

      Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see OData-Protocol, section 4.4.

      4.5.1 Addressing Actions

       @@ -845,7 +845,7 @@

      OData-Protocol. +
    • The aliasAndValue syntax rule defines the grammar for providing function parameter values using Parameter Alias Syntax, see OData-Protocol, section 11.2.6.1.3.

      • Note: there is no literal representation for Edm.Stream values in URLs, so it is not possible to pass Edm.Stream values to parameters of function imports or to non-binding parameters of bound functions used in the resource path. Function expressions within query options can use path expressions of type Edm.Stream as values of non-binding function parameters. The aliases can contain common expressions. In the case of a bound function these MAY contain path expressions, which the service evaluates on the binding parameter value.

      @@ -927,7 +927,7 @@

      Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol.

      +

      Services MAY additionally support the use of the unqualified name of a derived type in a URL by defining one or more default namespaces through the Core.DefaultNamespace term defined in OData-VocCore. For more information on default namespaces, see OData-Protocol, section 4.4.

      Services MAY also support treating an instance as a type outside of the type hierarchy using the same syntax and semantics as when addressing a derived type. In this case, the set and values of properties of the addressed type may be different than the properties of the source type. The set of such possible target types outside of the type hierarchy SHOULD be called out using the Core.MayImplement annotation term, defined in OData-VocCore.

      Example 37: entity set restricted to VipCustomer instances

      @@ -1128,7 +1128,7 @@

      OData-Protocol document.

      +

      The semantics of all system query options are defined in OData-Protocol, section 11.2.1.

      The grammar and syntax rules for system query options are defined in OData-ABNF.

      Dynamic properties can be used in the same way as declared properties. If they are not defined on an instance, they evaluate to null.

      @@ -2060,7 +2060,7 @@

      Core.Messages annotation

      http://host/service/Employees?$filter=@Core.Messages/any(m:m/severity eq 'error')

      -

      Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the Core.DefaultNamespace annotation term defined in OData-VocCore. For more information on default namespaces, see Default Namespaces in OData-Protocol. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a parameter alias, then any occurrence of the parameter alias name in an expression MUST evaluate to the parameter alias value and MUST NOT evaluate to the annotation value of an identical unqualified term name.

      +

      Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the Core.DefaultNamespace annotation term defined in OData-VocCore. For more information on default namespaces, see OData-Protocol, section 4.4. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a parameter alias, then any occurrence of the parameter alias name in an expression MUST evaluate to the parameter alias value and MUST NOT evaluate to the annotation value of an identical unqualified term name.

      5.1.1.17 Operator Precedence

      @@ -2374,7 +2374,7 @@

      OData-Protocol) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via $select. The Preference-Applied response header only reflects the set of annotations included due to the include-annotations preference and not those only included due to $select.

      +

      Annotations requested in $select MUST be included in the response; $select overrules the include-annotations preference (see OData-Protocol, section 8.2.8.4) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via $select. The Preference-Applied response header only reflects the set of annotations included due to the include-annotations preference and not those only included due to $select.

      If any select item (including a star) is specified, actions and functions SHOULD be omitted unless explicitly requested.

      If an action or function is requested as a select item, either explicitly by using its qualified name, or implicitly by requesting all operations in a schema, then the service includes information about how to invoke that operation for each entity identified by the last path segment in the request URL for which the operation can be bound.

      If an action or function is requested in a select item using its qualified name and that operation cannot be bound to the entities requested, the service MUST ignore the select item.

      @@ -2388,20 +2388,20 @@

      5.1.5 System Query Option $orderby

      The $orderby system query option allows clients to request resources in a particular order.

      -

      The semantics of $orderby are covered in the OData-Protocol document.

      +

      The semantics of $orderby are covered in OData-Protocol, section 11.2.6.2.

      The OData-ABNF orderby syntax rule defines the formal grammar of the $orderby query option.

      5.1.6 System Query Options $top and $skip

      The $top system query option requests the number of items in the queried collection to be included in the result. The $skip query option requests the number of items in the queried collection that are to be skipped and not included in the result. A client can request a particular page of items by combining $top and $skip.

      -

      The semantics of $top and $skip are covered in the OData-Protocol document. The OData-ABNF top and skip syntax rules define the formal grammar of the $top and $skip query options respectively.

      +

      The semantics of $top and $skip are covered in OData-Protocol, section 11.2.6.3 and OData-Protocol, section 11.2.6.4. The OData-ABNF top and skip syntax rules define the formal grammar of the $top and $skip query options respectively.

      5.1.7 System Query Option $count

      The $count system query option allows clients to request a count of the matching resources included with the resources in the response. The $count query option has a Boolean value of true or false.

      -

      The semantics of $count is covered in the OData-Protocol document.

      +

      The semantics of $count is covered in OData-Protocol, section 11.2.6.5.

      @@ -2435,7 +2435,7 @@

      5.1.9 System Query Option $format

      The $format system query option allows clients to request a response in a particular format and is useful for clients without access to request headers for standard content-type negotiation. Where present $format takes precedence over standard content-type negotiation.

      -

      The semantics of $format is covered in the OData-Protocol document.

      +

      The semantics of $format is covered in OData-Protocol, section 11.2.11.

      The OData-ABNF format syntax rule defines the formal grammar of the $format query option.

      @@ -2464,7 +2464,7 @@

      5.1.12 System Query Option $schemaversion

       -

      The $schemaversion system query option allows clients to specify the version of the schema against which the request is made. The semantics of $schemaversion is covered in the OData-Protocol document.

      +

      The $schemaversion system query option allows clients to specify the version of the schema against which the request is made. The semantics of $schemaversion is covered in OData-Protocol, section 11.2.12.

      The OData-ABNF schemaversion syntax rule defines the formal grammar of the $schemaversion query option

      @@ -2483,7 +2483,7 @@

      Parameter aliases can be used in place of literal values in entity keys, function parameters, or within a $filter or $orderby expression.

      Parameter aliases MUST start with an @ character, see rule parameterAlias in OData-ABNF.

      -

      The semantics of parameter aliases are covered in OData-Protocol. The OData-ABNF rule aliasAndValue defines the formal grammar for passing parameter alias values as query options.

      +

      The semantics of parameter aliases are covered in OData-Protocol, section 11.2.6.1.3. The OData-ABNF rule aliasAndValue defines the formal grammar for passing parameter alias values as query options.

      Example 144:

      http://host/service/Movies?$filter=contains(@word,Title)&@word='Black'
      @@ -2503,7 +2503,7 @@

      6 Conformance

       -

      The conformance requirements for OData clients and services are described in OData-Protocol.

      +

      The conformance requirements for OData clients and services are described in OData-Protocol, section 12.

      diff --git a/docs/odata-url-conventions/odata-url-conventions.md b/docs/odata-url-conventions/odata-url-conventions.md index 7bb811cc..3ed0a793 100644 --- a/docs/odata-url-conventions/odata-url-conventions.md +++ b/docs/odata-url-conventions/odata-url-conventions.md @@ -448,7 +448,7 @@ path segment, nor is `Tablet')`. The service root URL identifies the root of an OData service. A `GET` request to this URL returns the format-specific service document, see -[OData-JSON](#ODataJSON). +[OData-JSON, section 5](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ServiceDocument). The service root URL MUST terminate in a forward slash. @@ -490,7 +490,7 @@ An OData service MAY respond with `301 Moved Permanently` or ## 4.1 Addressing the Model for a Service OData services expose their entity model according to -[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) at the +[OData-CSDL](#ODataCSDL) at the metadata URL, formed by appending `$metadata` to the [service root URL](#ServiceRootURL). @@ -727,8 +727,7 @@ http://host/service/Products(1) ### 4.3.2 Canonical URL for Contained Entities For contained entities (i.e. related via a containment navigation -property, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL)) the canonical URL is the canonical URL of +property, see [OData-CSDLJSON](#ODataCSDL)) the canonical URL is the canonical URL of the containing entity followed by: - A [type-cast segment](#AddressingDerivedTypes) if the navigation property is defined on a type derived from the entity type declared for @@ -790,8 +789,7 @@ http://host/service/$entity?$id=Products(0) ``` ::: -The semantics of `$entity` are covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$entity` are covered in [OData-Protocol, section 10](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL). ### 4.3.5 Alternate Keys @@ -909,7 +907,7 @@ such 2. matches a qualified bound function, bound action, or type name, treat it as such 3. matches an unqualified bound function, bound action, or type name -defined in a default namespace (see [OData-Protocol](#ODataProtocol)) treat it +defined in a default namespace (see [OData-Protocol, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces)) treat it as such 4. treat as a key value @@ -951,7 +949,7 @@ addressing a collection of references MUST be followed by the system query option `$id` in order to identify a single entity reference within the collection to be removed. The entity-id specified by `$id` may be expressed absolute or relative to the request URL. For details see -[OData-Protocol](#ODataProtocol). +[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences). ::: example Example 29: three ways of unrelating `Categories(1)` and @@ -972,14 +970,14 @@ DELETE http://host/service/Products(0)/Category/$ref ## 4.5 Addressing Operations The semantic rules for addressing and invoking actions and functions are -defined in the [OData-Protocol](#ODataProtocol) document. +defined in [OData-Protocol, section 11.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Operations). Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the [`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace) term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [OData-Protocol, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces). ### 4.5.1 Addressing Actions @@ -1026,7 +1024,7 @@ syntax rule define the grammar for invoking functions, for example to help filte and order resources identified by the `resourcePath` of the URL. - The `aliasAndValue` syntax rule defines the grammar for providing function parameter values using Parameter -Alias Syntax, see [OData-Protocol](#ODataProtocol). +Alias Syntax, see [OData-Protocol, section 11.2.6.1.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ParameterAliases). Note: there is no literal representation for `Edm.Stream` values in URLs, so it is not possible to pass `Edm.Stream` values to parameters of function imports or @@ -1203,7 +1201,7 @@ derived type in a URL by defining one or more default namespaces through the [`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace) term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [OData-Protocol, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces). Services MAY also support treating an instance as a type outside of the type hierarchy using the same syntax and semantics as when addressing a @@ -1631,8 +1629,8 @@ The same system query option, irrespective of casing or whether or not it is prefixed with a `$`, MUST NOT be specified more than once for any resource. -The semantics of all system query options are defined in the -[OData-Protocol](#ODataProtocol) document. +The semantics of all system query options are defined in +[OData-Protocol, section 11.2.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptions). The grammar and syntax rules for system query options are defined in [OData-ABNF](#ODataABNF). @@ -3483,7 +3481,7 @@ Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the [`Core.DefaultNamespace`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace) annotation term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [OData-Protocol, section 4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces). This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a [parameter alias](#ParameterAliases), then any occurrence of the parameter alias @@ -3910,7 +3908,7 @@ omitted from the response. Annotations requested in `$select` MUST be included in the response; `$select` overrules the `include-annotations` preference (see -[OData-Protocol](#ODataProtocol)) for the explicitly requested annotations. +[OData-Protocol, section 8.2.8.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Preferenceincludeannotationsodataincludeannotations)) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via `$select`. The `Preference-Applied` response header only reflects the set of annotations included due to the @@ -3949,8 +3947,7 @@ identified by each select item. The `$orderby` system query option allows clients to request resources in a particular order. -The semantics of `$orderby` are covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$orderby` are covered in [OData-Protocol, section 11.2.6.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionorderby). The [OData-ABNF](#ODataABNF) `orderby` syntax rule defines the formal grammar of the `$orderby` query option. @@ -3963,8 +3960,9 @@ option requests the number of items in the queried collection that are to be skipped and not included in the result. A client can request a particular page of items by combining `$top` and `$skip`. -The semantics of `$top` and `$skip` are covered in the -[OData-Protocol](#ODataProtocol) document. The [OData-ABNF](#ODataABNF) `top` +The semantics of `$top` and `$skip` are covered in +[OData-Protocol, section 11.2.6.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptiontop) and [OData-Protocol, section 11.2.6.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionskip). +The [OData-ABNF](#ODataABNF) `top` and `skip` syntax rules define the formal grammar of the `$top` and `$skip` query options respectively. @@ -3974,8 +3972,7 @@ The `$count` system query option allows clients to request a count of the matching resources included with the resources in the response. The `$count` query option has a Boolean value of `true` or `false`. -The semantics of `$count` is covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$count` is covered in [OData-Protocol, section 11.2.6.5](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptioncount). ### 5.1.8 System Query Option `$search` @@ -4057,8 +4054,7 @@ in a particular format and is useful for clients without access to request headers for standard content-type negotiation. Where present `$format` takes precedence over standard content-type negotiation. -The semantics of `$format` is covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$format` is covered in [OData-Protocol, section 11.2.11](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionformat). The [OData-ABNF](#ODataABNF) `format` syntax rule defines the formal grammar of the `$format` query option. @@ -4121,7 +4117,7 @@ grammar of the `$index` query option. The `$schemaversion` system query option allows clients to specify the version of the schema against which the request is made. The semantics -of `$schemaversion` is covered in the [OData-Protocol](#ODataProtocol) document. +of `$schemaversion` is covered in [OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion). The [OData-ABNF](#ODataABNF) `schemaversion` syntax rule defines the formal grammar of the `$schemaversion` query option @@ -4153,7 +4149,7 @@ Parameter aliases MUST start with an `@` character, see rule `parameterAlias` in [OData-ABNF](#ODataABNF). The semantics of parameter aliases are covered in -[OData-Protocol](#ODataProtocol). The [OData-ABNF](#ODataABNF) rule +[OData-Protocol, section 11.2.6.1.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ParameterAliases). The [OData-ABNF](#ODataABNF) rule `aliasAndValue` defines the formal grammar for passing parameter alias values as query options. @@ -4186,7 +4182,7 @@ http://host/service/Products/Model.WithIngredients(Ingredients=@i) # 6 Conformance The conformance requirements for OData clients and services are -described in [OData-Protocol](#ODataProtocol). +described in [OData-Protocol, section 12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Conformance). ------- diff --git a/odata-csdl/1 Introduction.md b/odata-csdl/1 Introduction.md index 3aa65bc7..16330f22 100644 --- a/odata-csdl/1 Introduction.md +++ b/odata-csdl/1 Introduction.md @@ -560,7 +560,7 @@ length. The value of `$MaxLength` is a positive integer. -Note: [OData-CSDL-XML](#ODataCSDL) defines a symbolic +Note: [#OData-CSDLXML#MaxLength] defines a symbolic value `max` that is only allowed in OData 4.0 responses. This symbolic value is not allowed in CDSL JSON documents at all. Services MAY instead specify the concrete maximum length supported for the type by the diff --git a/odata-csdl/14 Vocabulary and Annotation.md b/odata-csdl/14 Vocabulary and Annotation.md index 73801ec6..6268d2b7 100644 --- a/odata-csdl/14 Vocabulary and Annotation.md +++ b/odata-csdl/14 Vocabulary and Annotation.md @@ -18,7 +18,7 @@ Metadata annotations are applied in CSDL documents describing or referencing an entity model. *Instance annotations* are terms applied to a particular instance within -an OData payload, such as described in [OData-JSON](#ODataJSON). An +an OData payload, such as described in [#OData-JSON#InstanceAnnotations]. An instance annotation can be used to define additional information associated with a particular result, entity, property, or error. For example, whether a property is read-only for a particular instance. @@ -195,10 +195,10 @@ of the collection and specifies whether the collection MAY contain The value of `$DefaultValue` is the type-specific JSON representation of the default value of the term, see -[OData-JSON](#ODataJSON). +[#OData-JSON#PrimitiveValue]. Note: the `$DefaultValue` member is purely for documentation and -isomorphy to [OData-CSDLXML](#ODataCSDL). Annotations in +isomorphy to [#OData-CSDLXML#DefaultValue]. Annotations in CSDL JSON documents MUST always specify an explicit value. ::: @@ -1223,7 +1223,7 @@ Example ##ex: ### ##subsubsec Geo Values ::: {.varjson .rep} -Values are represented as GeoJSON, see [OData-JSON](#ODataJSON). +Values are represented as GeoJSON, see [RFC7946](#rfc7946). ::: ::: {.varjson .example} @@ -1252,7 +1252,7 @@ Example ##ex: ### ##subsubsec Stream Values ::: {.varjson .rep} -Constant values of type `Edm.Stream` are represented according to [OData-JSON](#ODataJSON) and MUST be accompanied by +Constant values of type `Edm.Stream` are represented according to [#OData-JSON#StreamProperty] and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted. ::: @@ -1330,7 +1330,7 @@ than the `Edm.*Path` types. #### ##subsubsubsec Path Syntax Model paths and instance paths share a common syntax which is derived -from the path expression syntax of URLs, see [OData-URL](#ODataURL). +from the path expression syntax of URLs, see [#OData-URL#PathExpressions]. A path MUST be composed of zero or more path segments joined together by forward slashes (`/`). @@ -1466,7 +1466,7 @@ vs. term cast addressing an annotation on the resource addressed by the navigati An instance path MAY contain path segments starting with an entity set or a collection-valued navigation property, then followed by a key predicate using parentheses-style convention, see -[OData-URL](#ODataURL). The key values are either primitive literals or +[#OData-URL#CanonicalURL]. The key values are either primitive literals or instance paths. If the key value is a relative instance path, it is interpreted according to the same rule below as the instance path it is part of, *not* relative to the instance identified by the preceding path @@ -1981,7 +1981,7 @@ they MAY be used anywhere instead of a Boolean expression. The `And` and `Or` operators require two operand expressions that evaluate to Boolean values. The `Not` operator requires a single operand expression that evaluates to a Boolean value. For details on null -handling for comparison operators see [OData-URL](#ODataURL). +handling for comparison operators see [#OData-URL#LogicalOperators]. The other comparison operators require two operand expressions that evaluate to comparable values. @@ -2208,7 +2208,7 @@ to a numeric value. These expressions MAY be combined, and they MAY be used anywhere instead of a numeric expression of the appropriate type. The semantics and evaluation rules for each arithmetic expression is identical to the corresponding arithmetic operator defined in -[OData-URL](#ODataURL). +[#OData-URL#ArithmeticOperators]. Operator|Description --------|----------- @@ -2412,10 +2412,10 @@ specification and its future versions. #### ##subsubsubsec Canonical Functions -All canonical functions defined in [OData-URL](#ODataURL) can be used as +All canonical functions defined in [#OData-URL#CanonicalFunctions] can be used as client-side functions, qualified with the namespace `odata`. The semantics of these client-side functions is identical to their -counterpart function defined in [OData-URL](#ODataURL). +counterpart function defined in [#OData-URL#CanonicalFunctions]. For example, the `odata.concat` client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or @@ -2656,7 +2656,7 @@ Example ##ex: The cast expression casts the value obtained from its single child expression to the specified type. The cast expression follows the same rules as the `cast` canonical function defined in -[OData-URL](#ODataURL). +[#OData-URL#cast]. ::: {.varjson .rep} ### ##subisec `$Cast` @@ -3167,7 +3167,7 @@ property value expression. The member name is the property name, and the member value is the property value expression. The type of a record expression is represented as the `type` control -information, see [OData-JSON](#ODataJSON). +information, see [#OData-JSON#ControlInformationtypeodatatype]. It MAY contain [annotations](#Annotation) for itself and its members. Annotations for record members are prefixed with the member name. diff --git a/odata-csdl/4 CSDL Document.md b/odata-csdl/4 CSDL Document.md index 8e572799..f7dd24b3 100644 --- a/odata-csdl/4 CSDL Document.md +++ b/odata-csdl/4 CSDL Document.md @@ -104,8 +104,8 @@ The annotation, defined in [OData-VocCore](#ODataVocCore), MAY be used to indicate a particular version of the referenced document. If the [`Core.SchemaVersion`]($$$OData-VocCore$$$#SchemaVersion) -annotation is present, the `$schemaversion` system query option, defined -[OData-Protocol](#ODataProtocol), SHOULD be used when retrieving the +annotation is present, the `$schemaversion` system query option, defined in +[#OData-Protocol#SystemQueryOptionschemaversion], SHOULD be used when retrieving the referenced schema document. ::: {.varjson .rep} diff --git a/odata-csdl/5 Schema.md b/odata-csdl/5 Schema.md index 274d34e5..f9e31622 100644 --- a/odata-csdl/5 Schema.md +++ b/odata-csdl/5 Schema.md @@ -386,7 +386,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#DataModel]. ::: {.varjson .rep} ### ##subisec `$OpenType` @@ -413,7 +413,7 @@ entity with one or more properties of type `Edm.Stream` if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data. For more information on media entities see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#RequestingtheMediaStreamofaMediaEntityusingvalue]. An entity type derived from a media entity type MUST indicate that it is also a media entity type. @@ -480,7 +480,7 @@ on one of these primitive types: Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in -[OData-Protocol](#ODataProtocol)) MUST be language independent. +[#OData-Protocol#EntityIdsandEntityReferences]) MUST be language independent. A key property MUST be a non-nullable primitive property of the entity type itself, including non-nullable primitive properties of non-nullable diff --git a/odata-csdl/7 Structural Property.md b/odata-csdl/7 Structural Property.md index 3ff11b51..e3228b0a 100644 --- a/odata-csdl/7 Structural Property.md +++ b/odata-csdl/7 Structural Property.md @@ -217,7 +217,7 @@ If no value is specified, the client SHOULD NOT assume a default value. The value of `$DefaultValue` is the type-specific JSON representation of the default value of the property, see -[OData-JSON](#ODataJSON). For properties of type +[#OData-JSON#PrimitiveValue]. For properties of type `Edm.Decimal` and `Edm.Int64` the representation depends on the media type parameter [`IEEE754Compatible`](#ControllingtheRepresentationofNumbers). @@ -494,7 +494,7 @@ the entities referenced by the containment navigation property. The canonical URL for contained entities is the canonical URL of the containing instance, followed by the path segment of the navigation property and the key of the contained entity, see -[OData-URL](#ODataURL). +[#OData-URL#CanonicalURLforContainedEntities]. Entity types used in collection-valued containment navigation properties MUST have a [key](#Key) defined. diff --git a/odata-csdl/9 Complex Type.md b/odata-csdl/9 Complex Type.md index 6f553fc1..c8769313 100644 --- a/odata-csdl/9 Complex Type.md +++ b/odata-csdl/9 Complex Type.md @@ -178,7 +178,7 @@ Note: structural and navigation properties MAY be returned by the service on instances of any structured type, whether or not the type is marked as open. Clients MUST always be prepared to deal with additional properties on instances of any structured type, see -[OData‑Protocol](#ODataProtocol). +[#OData-Protocol#DataModel]. ::: {.varjson .rep} ### ##subisec `$OpenType` diff --git a/odata-csdl/Appendix.md b/odata-csdl/Appendix.md index 29ae9ced..9ce4175b 100644 --- a/odata-csdl/Appendix.md +++ b/odata-csdl/Appendix.md @@ -92,6 +92,10 @@ https://www.rfc-editor.org/info/rfc6570. ###### [RFC7493]{id=rfc7493} _The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015_. https://www.rfc-editor.org/info/rfc7493. + +###### [RFC7946]{id=rfc7946} +_Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10.17487/RFC7946, August 2016_. +https://www.rfc-editor.org/info/rfc7946. : ###### [RFC8174]{id=rfc8174} @@ -164,7 +168,7 @@ especially the contributions of : The contributions of the OASIS OData Technical Committee members, -enumerated in [ODataProtocol](#ODataProtocol), are gratefully +enumerated in [#OData-Protocol#Participants], are gratefully acknowledged. ## ##subasec Participants diff --git a/odata-data-aggregation-ext/4 Cross-Joins and Aggregation.md b/odata-data-aggregation-ext/4 Cross-Joins and Aggregation.md index f49feb63..7fa9bb6d 100644 --- a/odata-data-aggregation-ext/4 Cross-Joins and Aggregation.md +++ b/odata-data-aggregation-ext/4 Cross-Joins and Aggregation.md @@ -5,7 +5,7 @@ OData supports querying related entities through defining navigation properties in the data model. These navigation paths help guide simple consumers in understanding and navigating relationships. -In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource `$crossjoin` instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See [OData-URL](#ODataURL) for details. +In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource `$crossjoin` instead of an individual entity set. The cross join of a list of entity sets is the Cartesian product of the listed entity sets, represented as a collection of complex type instances that have a navigation property with cardinality to-one for each participating entity set, and queries across entity sets can be formulated using these navigation properties. See [#OData-URL#AddressingtheCrossJoinofEntitySets] for details. Where useful navigations exist it is beneficial to expose those as explicit navigation properties in the model, but the ability to pose queries that span entity sets not related by an association provides a mechanism for advanced consumers to use more flexible join conditions. diff --git a/odata-data-aggregation-ext/5 Vocabulary for Data Aggregation.md b/odata-data-aggregation-ext/5 Vocabulary for Data Aggregation.md index 01f9ce68..f2ebcc9c 100644 --- a/odata-data-aggregation-ext/5 Vocabulary for Data Aggregation.md +++ b/odata-data-aggregation-ext/5 Vocabulary for Data Aggregation.md @@ -7,7 +7,7 @@ The following terms are defined in the vocabulary for data aggregation [OData-Vo ## ##subsec Aggregation Capabilities -The term `ApplySupported` can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see [example ##containerrooted]). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of `$apply` even if they do not specify the `OpenType` attribute, see [OData-CSDL](#ODataCSDL). The term has a complex type with the following properties: +The term `ApplySupported` can be applied to an entity set, an entity type, or a collection if the target expression of the annotation starts with an entity container (see [example ##containerrooted]). It describes the aggregation capabilities of the annotated target. If present, it implies that instances of the annotated target can contain dynamic properties as an effect of `$apply` even if they do not specify the `OpenType` attribute, see [#OData-CSDL#OpenEntityType]. The term has a complex type with the following properties: - The `Transformations` collection lists all supported set transformations. Allowed values are the names of the standard transformations introduced in sections 3 and 6, and namespace-qualified names identifying a service-defined bindable function. If `Transformations` is omitted the server supports all transformations defined by this specification. - The `CustomAggregationMethods` collection lists supported custom aggregation methods. Allowed values are namespace-qualified names identifying service-specific aggregation methods. If omitted, no custom aggregation methods are supported. - `Rollup` specifies whether the service supports no rollup, only a single rollup hierarchy, or multiple rollup hierarchies in a [`groupby`](#Transformationgroupby) transformation. If omitted, multiple rollup hierarchies are supported. diff --git a/odata-data-aggregation-ext/8 Conformance.md b/odata-data-aggregation-ext/8 Conformance.md index 5f1e57b3..057febd1 100644 --- a/odata-data-aggregation-ext/8 Conformance.md +++ b/odata-data-aggregation-ext/8 Conformance.md @@ -68,7 +68,7 @@ https://www.rfc-editor.org/info/rfc8174. ## ##subasec Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol), are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [#OData-Protocol#Participants], are gratefully acknowledged. ## ##subasec Participants diff --git a/odata-json-format/10 Media Entity.md b/odata-json-format/10 Media Entity.md index 348bfdd7..6bc26b79 100644 --- a/odata-json-format/10 Media Entity.md +++ b/odata-json-format/10 Media Entity.md @@ -34,7 +34,7 @@ object. A single-valued property or operation response that has the `null` value does not have a representation; see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#ResponseCode204NoContent]. A property or operation response that is of a primitive type is represented as an object with a single name/value pair, whose name is @@ -194,7 +194,7 @@ Example ##ex: # ##sec Entity Reference -An entity reference (see [OData-Protocol](#ODataProtocol)) MAY take the +An entity reference (see [#OData-Protocol#EntityIdsandEntityReferences]) MAY take the place of an entity in a JSON payload, based on the client request. It is serialized as a JSON object that MUST contain the [id](#ControlInformationidodataid) of the referenced entity and MAY contain the [`type`](#ControlInformationtypeodatatype) diff --git a/odata-json-format/15 Delta Payload.md b/odata-json-format/15 Delta Payload.md index d6263f85..6037a283 100644 --- a/odata-json-format/15 Delta Payload.md +++ b/odata-json-format/15 Delta Payload.md @@ -109,7 +109,7 @@ entity's primary key fields are omitted from the response _or_ the entity-id is identical to the canonical URL of the entity. When using a delta payload in an [update request](#UpdateaCollectionofEntities), an -[alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see _Alternate Keys_ in [OData-URL](#ODataURL)) +[alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see [#OData-URL#AlternateKeys]) MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it @@ -204,7 +204,7 @@ For ordered payloads, this control information MUST follow the information MUST appear if any of the entity's primary key fields are omitted from the response _or_ the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an - [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see _Alternate Keys_ in [OData-URL](#ODataURL)) + [update request](#UpdateaCollectionofEntities), an [alternate key](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys) (see [#OData-URL#AlternateKeys]) MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the `id` control information and other primary key fields. diff --git a/odata-json-format/16 Bound Function.md b/odata-json-format/16 Bound Function.md index 27e447c5..9cb2d9da 100644 --- a/odata-json-format/16 Bound Function.md +++ b/odata-json-format/16 Bound Function.md @@ -7,8 +7,7 @@ A bound function is advertised via a name/value pair where the name is a hash (`#`) character followed by the namespace- or alias-qualified name of the function. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL) A +service, see [OData-CSDL](#ODataCSDL). A specific function overload can be advertised by appending the parentheses-enclosed, comma-separated list of non-binding parameter names to the qualified function name, see rule @@ -125,8 +124,7 @@ A bound action is advertised via a name/value pair where the name is a hash (`#`) character followed by the namespace- or alias-qualified name of the action. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the -service, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL) +service, see [OData-CSDL](#ODataCSDL). An action that is bound to a single structured type is advertised within the JSON object representing that structured type. diff --git a/odata-json-format/19 Batch Requests and Responses.md b/odata-json-format/19 Batch Requests and Responses.md index b70c3add..3a4ba39d 100644 --- a/odata-json-format/19 Batch Requests and Responses.md +++ b/odata-json-format/19 Batch Requests and Responses.md @@ -20,13 +20,13 @@ name/value pairs `atomicityGroup`, `dependsOn`, `if`, `headers`, and `body`. The value of `id` is a string containing the request identifier of the individual request, see -[OData-Protocol](#ODataProtocol). It MUST NOT be identical to the value +[#OData-Protocol#IdentifyingIndividualRequests]. It MUST NOT be identical to the value of any other request identifier nor any `atomicityGroup` within the batch request. Note: the `id` name/value pair corresponds to the `Content-ID` header in the multipart batch format specified -in [OData-Protocol](#ODataProtocol). +in [#OData-Protocol#MultipartBatchRequestBody]. The value of `method` is a string that MUST contain one of the literals `delete`, `get`, `patch`, `post`, or `put`. @@ -61,7 +61,7 @@ request, and which MUST satisfy the rule `request-id` in operation and MUST either all succeed, or all fail. Note: the atomicity group is a generalization of the change set in the -multipart batch format specified in [OData-Protocol](#ODataProtocol). +multipart batch format specified in [#OData-Protocol#MultipartBatchRequestBody]. The value of `dependsOn` is an array of strings whose values MUST be values of either `id` or `atomicityGroup` @@ -77,7 +77,7 @@ dependent request is not executed and a response with status code of The `if` member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see -[OData-URL](#ODataURL)) that evaluates to a Boolean value. +[#OData-URL#CommonExpressionSyntax]) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows - `$/$succeeded` @@ -348,7 +348,7 @@ processing the remaining individual requests while waiting for the client to fire a `GET` request to the next link. In a response to a batch request using the multipart format defined in -[OData-Protocol](#ODataProtocol) the response objects +[#OData-Protocol#MultipartBatchFormat] the response objects MUST appear in the same order as required for multipart batch responses because the `Content-ID` header is not required outside of change sets. Response objects corresponding to requests that specify a `Content-ID` header MUST contain the diff --git a/odata-json-format/20 Instance Annotations.md b/odata-json-format/20 Instance Annotations.md index 400e16f9..ff6acfd7 100644 --- a/odata-json-format/20 Instance Annotations.md +++ b/odata-json-format/20 Instance Annotations.md @@ -13,7 +13,7 @@ dot (`.`) as part of the name. The part after the "at" sign namespace or alias of the schema that defines the term, followed by a dot (`.`), followed by the name of the term, optionally followed by a hash (`#`) and a qualifier. The namespace or alias MUST be defined in the -metadata document, see [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) +metadata document, see [OData-CSDL](#ODataCSDL). The annotation identifier `odata` is reserved for future extensions of the protocol and format. Instance annotations MUST have a @@ -179,7 +179,7 @@ JSON object in the response. Services MAY include the header `OData-Error` as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#HeaderODataError]. The value of the `OData-Error` trailing header is an OData error object as defined in the preceding chapter, represented in a diff --git a/odata-json-format/23 Conformance.md b/odata-json-format/23 Conformance.md index 2eceda74..9264c00e 100644 --- a/odata-json-format/23 Conformance.md +++ b/odata-json-format/23 Conformance.md @@ -56,7 +56,7 @@ In order to be a conforming producer of the OData JSON format, a client or servi In addition, in order to conform to the OData JSON format, a service: -11. MUST comply with one of the conformance levels defined in [OData-Protocol](#ODataProtocol) +11. MUST comply with one of the conformance levels defined in [#OData-Protocol#Conformance] 12. MUST support the `application/json` media type in the `Accept` header ([section ##RequestingtheJSONFormat]) 13. MUST return well-formed JSON payloads 14. MUST support `odata.metadata=full` ([section ##metadatafullodatametadatafull]) diff --git a/odata-json-format/4 Common Characteristics.md b/odata-json-format/4 Common Characteristics.md index 4c32577c..b09a8501 100644 --- a/odata-json-format/4 Common Characteristics.md +++ b/odata-json-format/4 Common Characteristics.md @@ -51,7 +51,7 @@ order of objects within an array in JSON responses. ## ##subsec URLs in Message Bodies URLs represented as a string within a JSON payload, including [batch -requests](#BatchRequest), must follow standard OData encoding rules as defined in [OData-URL](#ODataURL). +requests](#BatchRequest), must follow standard OData encoding rules as defined in [#OData-URL#URLParsing]. For [relative URLs](#RelativeURLs) this means that colons (`:`) in the path part, especially within key values, MUST be percent-encoded to avoid confusion with the @@ -212,7 +212,7 @@ stop processing and MUST NOT signal an error. ### ##subsubsec Control Information: `context` (`odata.context`) The `context` control information -returns the context URL (see [OData-Protocol](#ODataProtocol)) for the +returns the context URL (see [#OData-Protocol#ContextURL]) for the payload. This URL can be absolute or [relative](#RelativeURLs). The fragment portion of the context URL MUST NOT be percent-encoded. @@ -226,7 +226,7 @@ entity set cannot be determined from the context URL of the collection. For more information on the format of the context URL, see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#ContextURL]. Request payloads MAY include a context URL as a base URL for [relative URLs](#RelativeURLs) in the request payload. @@ -257,7 +257,7 @@ If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the `metadataEtag` control information in any responses. -For details on how ETags are used, see [OData-Protocol](#ODataProtocol). +For details on how ETags are used, see [#OData-Protocol#UseofETagsforAvoidingUpdateConflicts]. ### ##subsubsec Control Information: `type` (`odata.type`) @@ -278,7 +278,7 @@ The root `type` may be absolute or relative to the root If the URI references a metadata document (that is, it's not just a fragment), it MAY refer to a specific version of that metadata document using the `$schemaversion` system query option -defined in [OData-Protocol](#ODataProtocol). +defined in [#OData-Protocol#SystemQueryOptionschemaversion]. For non-built in primitive types, the URI contains the namespace-qualified or alias-qualified type, specified as a URI @@ -287,8 +287,7 @@ fragment is the namespace-qualified or alias-qualified element type enclosed in parentheses and prefixed with `Collection`. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see -[OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL). +[OData-CSDL](#ODataCSDL). The `type` control information MUST appear in requests and in responses with [minimal](#metadataminimalodatametadataminimal) or @@ -330,8 +329,7 @@ The `type` control information can be absent in properties nested in an instance In particular, individual primitive values within a collection cannot have `type` control information. For more information on namespace- and alias-qualified names, see -[OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL). +[OData-CSDL](#ODataCSDL). ::: example Example ##ex: entity of type @@ -402,9 +400,9 @@ control information. ### ##subsubsec Control Information: `id` (`odata.id`) The `id` control information contains the entity-id, see -[OData-Protocol](#ODataProtocol). By convention the entity-id is +[#OData-Protocol#EntityIdsandEntityReferences]. By convention the entity-id is identical to the canonical URL of the entity, as defined in -[OData-URL](#ODataURL). +[#OData-URL#CanonicalURL]. The `id` control information MUST appear in responses if [`metadata=full`](#metadatafullodatametadatafull) @@ -424,7 +422,7 @@ if it does not match convention for the localized key values. If the `id` is represented, it MAY be a [relative URL](#RelativeURLs). -If the entity is transient (see [OData-Protocol](#ODataProtocol)), the +If the entity is transient (see [#OData-Protocol#TransientEntities]), the `id` control information MUST appear in OData 4.0 payloads and have the `null` value. In 4.01 or greater payloads transient entities need not have the `id` control information, and @@ -443,10 +441,10 @@ of this specification. ### ##subsubsec Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`) The `editLink` control information contains -the edit [URL](URLsinMessageBodies) of the entity; see [OData-Protocol](#ODataProtocol). +the edit [URL](URLsinMessageBodies) of the entity; see [#OData-Protocol#ReadURLsandEditURLs]. The `readLink` control information contains the read URL of -the entity or collection; see [OData-Protocol](#ODataProtocol). +the entity or collection; see [#OData-Protocol#ReadURLsandEditURLs]. The `editLink` and `readLink` control information is ignored in request payloads and not written in responses if @@ -500,7 +498,7 @@ value of the control information is an entity tag (ETag) which is an opaque string value that can be used in a subsequent request to determine if the value of the entity or collection has changed. -For details on how ETags are used, see [OData-Protocol](#ODataProtocol). +For details on how ETags are used, see [#OData-Protocol#UseofETagsforAvoidingUpdateConflicts]. The `etag` control information is ignored in request payloads for single entities and not written in responses if diff --git a/odata-json-format/5 Service Document.md b/odata-json-format/5 Service Document.md index 6140d050..00538e5a 100644 --- a/odata-json-format/5 Service Document.md +++ b/odata-json-format/5 Service Document.md @@ -15,7 +15,7 @@ The value of the `value` property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of `true` for the attribute `IncludeInServiceDocument` and each singleton exposed by the -service, see [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL). +service, see [OData-CSDL](#ODataCSDL). Each element MUST be a JSON object with at least two name/value pairs, one with name `name` containing the name of the entity set, @@ -104,9 +104,8 @@ represented as a name/value pair within the object. The order properties appear within the object is considered insignificant. An entity in a payload may be a complete entity, a projected entity (see -_System Query Option_ `$select` in -[OData-Protocol](#ODataProtocol)), or a partial entity update (see -_Update an Entity_ in [OData-Protocol](#ODataProtocol)). +[#OData-Protocol#SystemQueryOptionselect]), or a partial entity update (see +[#OData-Protocol#UpdateanEntity]). An entity representation can be (modified and) round-tripped to the service directly. The [context diff --git a/odata-json-format/7 Structural Property.md b/odata-json-format/7 Structural Property.md index b09ce931..1550d31e 100644 --- a/odata-json-format/7 Structural Property.md +++ b/odata-json-format/7 Structural Property.md @@ -201,6 +201,7 @@ an `Edm.Boolean`, `Edm.String`, or `Edm.Decimal` value, depending on the JavaScript type. Collections directly contained within an untyped collection are themselves untyped. + ------- # ##sec Navigation Property @@ -467,7 +468,7 @@ Instead stream property data is generally read and edited via URLs. [`media*`](#ControlInformationmediaodatamedia) control information. - Stream properties requested with `$expand` or implicitly expanded are represented as a property with its value. -See [OData-Protocol](#ODataProtocol) for details on the system query options `$select` and `$expand`. +See [#OData-Protocol#SystemQueryOptionselect] for details on the system query options `$select` and `$expand`. Depending on the [metadata level](#ControllingtheAmountofControlInformationinResponses), the stream property MAY be annotated to provide the read link, edit diff --git a/odata-json-format/Appendix.md b/odata-json-format/Appendix.md index 47fe8008..d2650b27 100644 --- a/odata-json-format/Appendix.md +++ b/odata-json-format/Appendix.md @@ -96,7 +96,7 @@ For JSON-relevant security implications please cf. at least the relevant subsect ## ##subasec Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [#OData-Protocol#Participants], are gratefully acknowledged. ## ##subasec Participants diff --git a/odata-protocol/1 Introduction.md b/odata-protocol/1 Introduction.md index e8a0d0b6..b43b3c1c 100644 --- a/odata-protocol/1 Introduction.md +++ b/odata-protocol/1 Introduction.md @@ -16,7 +16,7 @@ service as well as a set of reserved URL query options. The [OData-CSDLJSON](#ODataCSDL) specification defines a JSON representation of the entity data model exposed by an OData service. -The [OData-CSDLXML](#ODataCSDL) specification defines an XML +The [OData-CSDLXML](#ODataCSDLXML) specification defines an XML representation of the entity data model exposed by an OData service. The [OData-JSON](#ODataJSON) document specifies the JSON format of the @@ -210,7 +210,7 @@ set. An OData *resource* is anything in the model that can be addressed (an entity set, entity, property, or operation). -Refer to [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) for +Refer to [OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDLXML) for more information on the OData entity data model. ## ##subsec Annotations @@ -269,7 +269,7 @@ of the specification since there is currently no lossless representation of an IRI in the [`EntityId`](#HeaderODataEntityId) header. Services are strongly encouraged to use the canonical URL for an entity -as defined in [OData-URL](#ODataURL) as its entity-id, but clients cannot assume +as defined in [#OData-URL#CanonicalURL] as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the [`Core.DereferenceableIDs`]($$$OData-VocCore$$$#DereferenceableIDs) term is applied to the entity container, nor can the client assume any @@ -296,7 +296,7 @@ The edit URL of a property is the edit URL of the entity with appended segment(s) containing the path to the property. Services are strongly encouraged to use the canonical URL for an entity -as defined in [OData-URL](#ODataURL) for both the read URL and the edit URL of an +as defined in [#OData-URL#CanonicalURL] for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention diff --git a/odata-protocol/10 Context URL.md b/odata-protocol/10 Context URL.md index 5ad8ce5a..d2356653 100644 --- a/odata-protocol/10 Context URL.md +++ b/odata-protocol/10 Context URL.md @@ -569,7 +569,7 @@ Context URL template: {context-url}#Collection(Edm.EntityType) Responses to requests to the virtual collection `$all` (see -[OData-URL](#ODataURL)) use the built-in abstract entity type. Each +[#OData-URL#AddressingAllEntitiesinaService]) use the built-in abstract entity type. Each single entity in such a response has its individual context URL that identifies the entity set or singleton. @@ -580,5 +580,5 @@ Context URL template: {context-url}#Collection(Edm.ComplexType) Responses to requests to the virtual collections `$crossjoin(…)` (see -[OData-URL](#ODataURL)) use the built-in abstract complex type. Single +[#OData-URL#AddressingtheCrossJoinofEntitySets]) use the built-in abstract complex type. Single instances in these responses do not have a context URL. diff --git a/odata-protocol/11 Data Service Requests.md b/odata-protocol/11 Data Service Requests.md index 1af41135..229b5547 100644 --- a/odata-protocol/11 Data Service Requests.md +++ b/odata-protocol/11 Data Service Requests.md @@ -67,7 +67,7 @@ metadata documents and provides a JSON schema to validate their contents. The media type of the JSON representation of an OData metadata document is `application/json`. -[OData-CSDLXML](#ODataCSDL) describes an XML representation for OData +[OData-CSDLXML](#ODataCSDLXML) describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is `application/xml`. @@ -151,9 +151,9 @@ URL that identifies the entity, e.g. its read URL. The read URL can be obtained from a response payload containing that instance, for example as a `readLink` or `editLink` in an -[OData-JSON](#ODataJSON) payload. In addition, services +[#OData-JSON#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink] payload. In addition, services MAY support conventions for constructing a read URL using the entity's -key value(s), as described in [OData-URL](#ODataURL). +key value(s), as described in [#OData-URL#CanonicalURL]. The set of structural or navigation properties to return may be specified through [`$select`](#SystemQueryOptionselect) or @@ -213,7 +213,7 @@ the property name appended. For complex typed properties, the path can be further extended with the name of an individual property of the complex type. -See [OData-URL](#ODataURL) for details. +See [#OData-URL#AddressingaProperty] for details. If the property is single-valued and has the `null` value, the service responds with [`204 No Content`](#ResponseCode204NoContent). @@ -243,7 +243,7 @@ system query option. #### ##subsubsubsec Requesting a Raw Value using `$value` To retrieve the raw value of a primitive property or operation result, the client sends -a `GET` request to the raw value URL. See the [OData-URL](#ODataURL) document for details. +a `GET` request to the raw value URL. See [#OData-URL#AddressingaRawValue] for details. The `Content-Type` of the response is determined using the `Accept` header and the [`$format`](#SystemQueryOptionformat) system query @@ -442,7 +442,7 @@ GET http://host/service.svc/Customers?$expand=Photo The 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](#ODataURL). +[#OData-URL#SystemQueryOptionexpand]. Allowed system query options are [`$compute`](#SystemQueryOptioncompute), @@ -1232,7 +1232,7 @@ 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](#ODataJSON). +[#OData-JSON#metadatafullodatametadatafull]. ::: example Example ##ex: the request @@ -1244,7 +1244,7 @@ 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](#ODataJSON). +[#OData-JSON#metadataminimalodatametadataminimal]. In [metadata document requests](#MetadataDocumentRequest), the values `application/xml` and `application/json`, along with their subtypes and diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index 4c61d0e7..67be5abc 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -733,7 +733,7 @@ deleted, the dependent entity is also deleted. Relationships between entities are represented by navigation properties as described in [Data Model](#DataModel). URL conventions for navigation -properties are described in [OData-URL](#ODataURL). +properties are described in [#OData-URL#URLsforRelatedEntitieswithReferentialConstraints]. #### ##subsubsubsec Add a Reference to a Collection-Valued Navigation Property @@ -759,7 +759,7 @@ collection of related references, with the reference to be removed identified by the [`$id`](#ResolvinganEntityId) query option. OData 4.01 services additionally support using the URL that represents the reference of the collection member to be removed, identified by key, as -described in [OData-URL](#ODataURL). +described in [#OData-URL#AddressingReferencesbetweenEntities]. For single-valued navigation properties, the [`$id`](#ResolvinganEntityId) query option MUST NOT be specified. @@ -783,7 +783,7 @@ On successful completion, the response MUST be Alternatively, a relationship MAY be updated as part of an update to the source entity by including the required binding information for the new target entity. This binding information is format-specific, see -[OData-JSON](#ODataJSON) for details. +[#OData-JSON#RelatedEntities] for details. If the single-valued navigation property is used in the key definition of an entity type, it cannot be changed and the request MUST fail with @@ -976,7 +976,7 @@ Attempting to request a stream property whose value is null results in Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows -properties to be individually modified. See [OData-URL](#ODataURL) for +properties to be individually modified. See [#OData-URL#AddressingaProperty] for details on addressing individual properties. #### ##subsubsubsec Update a Primitive Property @@ -1261,7 +1261,8 @@ describes an update to each member of the collection, not an update to the collection itself. The resource path of the collection MAY contain type-cast or filter -segments to subset the collection, see [OData-URL](#ODataURL). +segments to subset the collection, see [#OData-URL#AddressingDerivedTypes] and +[#OData-URL#AddressingaSubsetofaCollection]. For primitive-typed collections the body of the request MUST be a primitive value. Each member of the potentially filtered collection is diff --git a/odata-protocol/11.5 Operations.md b/odata-protocol/11.5 Operations.md index 6406a107..9313aaab 100644 --- a/odata-protocol/11.5 Operations.md +++ b/odata-protocol/11.5 Operations.md @@ -4,7 +4,7 @@ Custom operations ([Actions](#Actions) and [Functions](#Functions)) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See `Action`, `ActionImport`, `Function`, and `FunctionImport` in -[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL). +[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDLXML). ### ##subsubsec Binding an Operation to a Resource @@ -123,7 +123,7 @@ bound to the entity 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](#ODataURL). +[#OData-URL#AddressingOperations]. Services can advertise that a function or action is not available for a particular instance by setting its value to null. @@ -250,7 +250,7 @@ result requires a `4xx` response, and continues otherwise. Function imports preceded by the `$root` literal MAY be used in the [`$filter`](#SystemQueryOptionfilter) or [`$orderby`](#SystemQueryOptionorderby) system query options, see -[OData-URL](#ODataURL). +[#OData-URL#SystemQueryOptionfilter] and [#OData-URL#SystemQueryOptionorderby]. ##### ##subsubsubsubsec Inline Parameter Syntax @@ -338,7 +338,7 @@ If the function is bound and the binding parameter type is part of an inheritance hierarchy, the function overload is selected based on the type of the URL segment preceding the function name. A type-cast segment can be used to select a function defined on a particular type in the -hierarchy, see [OData-URL](#ODataURL). +hierarchy, see [#OData-URL#AddressingDerivedTypes]. Non-binding parameters MAY be marked as optional by annotating them with the term @@ -474,7 +474,7 @@ If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, -see [OData-URL](#ODataURL). +see [#OData-URL#AddressingDerivedTypes]. ## ##subsec Asynchronous Requests diff --git a/odata-protocol/11.7 Batch Requests.md b/odata-protocol/11.7 Batch Requests.md index df053c89..c8e46f9b 100644 --- a/odata-protocol/11.7 Batch Requests.md +++ b/odata-protocol/11.7 Batch Requests.md @@ -17,7 +17,7 @@ a batch request. A batch request is represented using either the [multipart batch format](#MultipartBatchFormat) defined in this document or the JSON -batch format defined in [OData-JSON](#ODataJSON). +batch format defined in [#OData-JSON#BatchRequestsandResponses]. If the set of request headers of a batch request are valid the service MUST return a [`200 OK`](#ResponseCode200OK) HTTP response code to diff --git a/odata-protocol/12 Conformance.md b/odata-protocol/12 Conformance.md index 13adc84b..262959d7 100644 --- a/odata-protocol/12 Conformance.md +++ b/odata-protocol/12 Conformance.md @@ -60,7 +60,7 @@ request 7. MUST successfully parse the request according to [OData-ABNF](#ODataABNF) for any supported system query options and follow the specification or fail the request -8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDL) +8. MUST expose only data types defined in [OData-CSDLXML](#ODataCSDLXML) 9. MUST NOT require clients to understand any metadata or instance annotations ([section ##VocabularyExtensibility]), custom headers ([section ##HeaderFieldExtensibility]), or custom content ([section ##PayloadExtensibility]) in the payload in order to correctly consume the @@ -70,7 +70,7 @@ service 11. MUST NOT violate any other OData-defined semantics 12. SHOULD support `$expand` ([section ##SystemQueryOptionexpand]) 13. SHOULD publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) and MAY publish metadata according to +[OData-CSDLXML](#ODataCSDLXML) and MAY publish metadata according to [OData-CSDLJSON](#ODataCSDL) ([section ##MetadataDocumentRequest]) 14. MUST support prefixed variants of supported headers and preference values @@ -88,7 +88,7 @@ final response to an asynchronous request To be considered an *Updatable OData Service*, the service additionally: 18. MUST include edit links (explicitly or implicitly) for all -updatable or deletable resources according to [OData-JSON](#ODataJSON) +updatable or deletable resources according to [#OData-JSON#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink] 19. MUST support `POST` of new entities to insertable entity sets ([section ##ReturningResultsfromDataModificationRequests]) 20. MUST support `POST` of new related entities to updatable navigation @@ -129,7 +129,7 @@ Level](#OData40MinimalConformanceLevel) follow the specification or fail the request 3. MUST support `$select` ([section ##SystemQueryOptionselect]) 4. MUST support casting to a derived type according to -[OData-URL](#ODataURL) if derived types are present in the model +[#OData-URL#AddressingDerivedTypes] if derived types are present in the model 5. MUST support `$top` ([section ##SystemQueryOptiontop]) 6. MUST support `/$value` on media entities ([section ##MetadataDocumentRequest]) and individual properties ([section ##RequestingaRawValueusingvalue]) 7. MUST support `$filter` ([section ##SystemQueryOptionfilter]) @@ -143,7 +143,7 @@ operations MUST fail the request for any unsupported canonical functions 5. SHOULD support `$filter` on expanded entities ([section ##ExpandOptions]) 8. SHOULD publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) ([section ##MetadataDocumentRequest]) +[OData-CSDLXML](#ODataCSDLXML) ([section ##MetadataDocumentRequest]) 9. SHOULD support the [OData-JSON](#ODataJSON) format 10. SHOULD consider supporting basic authentication as defined in [RFC7617](#rfc7617) over HTTPS for the highest level of interoperability @@ -166,7 +166,7 @@ In order to conform to the OData Advanced Conformance Level, a service: 1. MUST conform to at least the [OData 4.0 Intermediate Conformance Level](#OData40IntermediateConformanceLevel) 2. MUST publish metadata at `$metadata` according to -[OData-CSDLXML](#ODataCSDL) ([section ##MetadataDocumentRequest]) +[OData-CSDLXML](#ODataCSDLXML) ([section ##MetadataDocumentRequest]) 3. MUST support the [OData-JSON](#ODataJSON) format 4. MUST support the `/$count` segment on navigation and collection properties ([section ##RequestingtheNumberofItemsinaCollection]) @@ -191,13 +191,13 @@ properties 10. MUST support the `$search` system query option ([section ##SystemQueryOptionsearch]) 11. MUST support batch requests according to the multipart format ([section ##BatchRequests] and all subsections) and MAY support batch requests -according to the JSON Batch format defined in [OData-JSON](#ODataJSON) +according to the JSON Batch format defined in [#OData-JSON#BatchRequestsandResponses] 12. MUST support the resource path conventions defined in -[OData-URL](#ODataURL) +[#OData-URL#ResourcePath] 13. SHOULD support asynchronous requests ([section ##AsynchronousRequests]) 14. SHOULD support Delta change tracking ([section ##RequestingChanges]) -15. SHOULD support cross-join queries defined in [OData-URL](#ODataURL) +15. SHOULD support cross-join queries defined in [#OData-URL#AddressingtheCrossJoinofEntitySets] 16. MAY support the `$compute` system query option ([section ##SystemQueryOptioncompute]) ## ##subsec OData 4.01 Service Conformance Levels @@ -258,12 +258,12 @@ with a maximum cardinality of one 11. SHOULD support negative indexes for the substring function 12. MAY support Key-As-Segment URL convention 1. MUST also support canonical URL conventions (described in -[OData-URL](#ODataURL)) or include URLs in payload +[#OData-URL#CanonicalURL]) or include URLs in payload 13. MAY support the count of a filtered collection in a common expression 14. MAY support equal and non-equal structural comparison 10. SHOULD publish metadata at `$metadata` according to both -[OData-CSDLXML](#ODataCSDL) and [OData-CSDLJSON](#ODataCSDL) ([section ##MetadataDocumentRequest]) +[OData-CSDLXML](#ODataCSDLXML) and [OData-CSDLJSON](#ODataCSDL) ([section ##MetadataDocumentRequest]) 11. SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case @@ -345,7 +345,7 @@ properties [OData-CSDLJSON](#ODataCSDL) ([section ##MetadataDocumentRequest]) 7. MUST support batch requests according both to the multipart format ([section ##BatchRequests] and all subsections) and the JSON Batch format defined in -[OData-JSON](#ODataJSON) +[#OData-JSON#BatchRequestsandResponses] 8. SHOULD support filtering a collection using a `/$filter` path segment 9. SHOULD support nested parameter alias assignments in @@ -368,7 +368,7 @@ To be generally interoperable, OData clients 2. MUST specify `OData-Version` ([section ##HeaderODataVersion]) and `Content-Type` ([section ##HeaderContentType]) in any request with a payload 3. MUST be a conforming consumer of OData as defined in -[OData-JSON](#ODataJSON) +[#OData-JSON#Conformance] 4. MUST follow redirects ([section ##ResponseCode3xxRedirection]) 5. MUST correctly handle next links ([section ##ServerDrivenPaging]) 6. MUST support instances returning properties and navigation @@ -388,9 +388,9 @@ returned in the response ([section ##RequestingEntityReferences]) in a delta response ([section ##RequestingChanges]) 14. MAY support asynchronous responses ([section ##AsynchronousRequests]) 15. MAY support `metadata=minimal` in a JSON response (see -[OData-JSON](#ODataJSON)) +[#OData-JSON#metadataminimalodatametadataminimal]) 16. MAY support `streaming` in a JSON response (see -[OData-JSON](#ODataJSON)) +[#OData-JSON#PayloadOrderingConstraints]) In addition, interoperable OData 4.01 clients diff --git a/odata-protocol/8 Header Fields.md b/odata-protocol/8 Header Fields.md index aa388e72..f7b7b985 100644 --- a/odata-protocol/8 Header Fields.md +++ b/odata-protocol/8 Header Fields.md @@ -27,7 +27,7 @@ ignored. Custom format parameters MUST NOT start with `odata` and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload. -See [OData-JSON](#ODataJSON) for format-specific details about format +See [#OData-JSON#HeaderContentType] for format-specific details about format parameters within the `Content-Type` header. ### ##subsubsec Header `Content-Encoding` @@ -838,7 +838,7 @@ HTTP/2). The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport -in a header, see e.g. [OData-JSON](#ODataJSON). +in a header, see e.g. [#OData-JSON#InStreamError]. ### ##subsubsec Header `Preference-Applied` diff --git a/odata-protocol/Appendix.md b/odata-protocol/Appendix.md index 7f458754..c3fe5fdf 100644 --- a/odata-protocol/Appendix.md +++ b/odata-protocol/Appendix.md @@ -19,10 +19,11 @@ See link in "[Related work](#RelatedWork)" section on cover page. _OData Extension for Data Aggregation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. -###### [OData-CSDL]{id=ODataCSDL} +###### [OData-CSDLJSON]{id=ODataCSDL} _OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-CSDLXML]{id=ODataCSDLXML} _OData Common Schema Definition Language (CSDL) XML Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. diff --git a/odata-temporal-ext/4.3 Modifying Temporal Data.md b/odata-temporal-ext/4.3 Modifying Temporal Data.md index 5e2ba23e..8cf60106 100644 --- a/odata-temporal-ext/4.3 Modifying Temporal Data.md +++ b/odata-temporal-ext/4.3 Modifying Temporal Data.md @@ -54,7 +54,7 @@ slices. These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data [OData-VocTemporal](#ODataVocTemporal). Implementations SHOULD consider the preferences `return=representation` -and `return=minimal` as specified inv[OData-Protocol](#ODataProtocol). +and `return=minimal` as specified in [#OData-Protocol#Preferencereturnrepresentationandreturnminimal]. The convenience operations are atomic (all or nothing): they either succeed and produce the result described below, or they fail and do not change the temporal objects. @@ -108,7 +108,7 @@ This works identical to the SQL statement UPDATE FOR PORTION OF: slice's period. 4. Then all fully included time slices (including ones created in the previous step) are updated following the rules for updating entities - specified in [OData-Protocol](#ODataProtocol). + specified in [#OData-Protocol#UpdateanEntity]. 5. Gaps between selected time slices in the period to update are not affected. On success it returns the created or updated time slices. @@ -301,10 +301,10 @@ Step 5 is (except for computed properties), 2. setting the period boundaries to close the gap, and then 3. updating the new time slice following the rules for updating - entities specified in [OData-Protocol](#ODataProtocol). + entities specified in [#OData-Protocol#UpdateanEntity]. If no preceding time slice exists, the time slice is created following - the rules for creating entities specified in [OData-Protocol](#ODataProtocol). + the rules for creating entities specified in [#OData-Protocol#CreateanEntity]. On success it returns the created or updated time slices. @@ -450,7 +450,7 @@ This works identical to the SQL statement DELETE FOR PORTION OF: slices, one with non-overlapping, and one with fully included period. 4. Then all fully included time slices (including ones created in the previous step) are deleted following the rules for deleting entities - specified in [OData-Protocol](#ODataProtocol). + specified in [#OData-Protocol#DeleteanEntity]. On success it returns the deleted time slices. diff --git a/odata-temporal-ext/Appendix.md b/odata-temporal-ext/Appendix.md index 90b20e4f..14d05565 100644 --- a/odata-temporal-ext/Appendix.md +++ b/odata-temporal-ext/Appendix.md @@ -78,7 +78,7 @@ _ISO/IEC 9075-2:2011 Information technology - Database languages - SQL - Part 2: ## ##subasec Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [#OData-Protocol#Participants], are gratefully acknowledged. Special thanks to Andrew Eisenberg, whose contributions in the early stages of the OData TC were invaluable to getting this extension specification on track. diff --git a/odata-url-conventions/1 Introduction.md b/odata-url-conventions/1 Introduction.md index 5a141e69..cda1a171 100644 --- a/odata-url-conventions/1 Introduction.md +++ b/odata-url-conventions/1 Introduction.md @@ -212,7 +212,7 @@ path segment, nor is `Tablet')`. The service root URL identifies the root of an OData service. A `GET` request to this URL returns the format-specific service document, see -[OData-JSON](#ODataJSON). +[#OData-JSON#ServiceDocument]. The service root URL MUST terminate in a forward slash. diff --git a/odata-url-conventions/4 Resource Path.md b/odata-url-conventions/4 Resource Path.md index bc00cc85..cfd51864 100644 --- a/odata-url-conventions/4 Resource Path.md +++ b/odata-url-conventions/4 Resource Path.md @@ -33,7 +33,7 @@ An OData service MAY respond with `301 Moved Permanently` or ## ##subsec Addressing the Model for a Service OData services expose their entity model according to -[OData-CSDLJSON](#ODataCSDL) or [OData-CSDLXML](#ODataCSDL) at the +[OData-CSDL](#ODataCSDL) at the metadata URL, formed by appending `$metadata` to the [service root URL](#ServiceRootURL). @@ -270,8 +270,7 @@ http://host/service/Products(1) ### ##subsubsec Canonical URL for Contained Entities For contained entities (i.e. related via a containment navigation -property, see [OData-CSDLJSON](#ODataCSDL) or -[OData-CSDLXML](#ODataCSDL)) the canonical URL is the canonical URL of +property, see [OData-CSDLJSON](#ODataCSDL)) the canonical URL is the canonical URL of the containing entity followed by: - A [type-cast segment](#AddressingDerivedTypes) if the navigation property is defined on a type derived from the entity type declared for @@ -333,8 +332,7 @@ http://host/service/$entity?$id=Products(0) ``` ::: -The semantics of `$entity` are covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$entity` are covered in [#OData-Protocol#ContextURL]. ### ##subsubsec Alternate Keys @@ -452,7 +450,7 @@ such 2. matches a qualified bound function, bound action, or type name, treat it as such 3. matches an unqualified bound function, bound action, or type name -defined in a default namespace (see [OData-Protocol](#ODataProtocol)) treat it +defined in a default namespace (see [#OData-Protocol#DefaultNamespaces]) treat it as such 4. treat as a key value @@ -494,7 +492,7 @@ addressing a collection of references MUST be followed by the system query option `$id` in order to identify a single entity reference within the collection to be removed. The entity-id specified by `$id` may be expressed absolute or relative to the request URL. For details see -[OData-Protocol](#ODataProtocol). +[#OData-Protocol#EntityIdsandEntityReferences]. ::: example Example ##ex: three ways of unrelating `Categories(1)` and @@ -515,14 +513,14 @@ DELETE http://host/service/Products(0)/Category/$ref ## ##subsec Addressing Operations The semantic rules for addressing and invoking actions and functions are -defined in the [OData-Protocol](#ODataProtocol) document. +defined in [#OData-Protocol#Operations]. Services MAY additionally support the use of the unqualified name of an action or function in a URL by defining one or more default namespaces through the [`Core.DefaultNamespace`]($$$OData-VocCore$$$#DefaultNamespace) term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [#OData-Protocol#DefaultNamespaces]. ### ##subsubsec Addressing Actions @@ -569,7 +567,7 @@ syntax rule define the grammar for invoking functions, for example to help filte and order resources identified by the `resourcePath` of the URL. - The `aliasAndValue` syntax rule defines the grammar for providing function parameter values using Parameter -Alias Syntax, see [OData-Protocol](#ODataProtocol). +Alias Syntax, see [#OData-Protocol#ParameterAliases]. Note: there is no literal representation for `Edm.Stream` values in URLs, so it is not possible to pass `Edm.Stream` values to parameters of function imports or @@ -746,7 +744,7 @@ derived type in a URL by defining one or more default namespaces through the [`Core.DefaultNamespace`]($$$OData-VocCore$$$#DefaultNamespace) term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [#OData-Protocol#DefaultNamespaces]. Services MAY also support treating an instance as a type outside of the type hierarchy using the same syntax and semantics as when addressing a diff --git a/odata-url-conventions/5 Query Options.md b/odata-url-conventions/5 Query Options.md index 4222a8dc..d82a7de5 100644 --- a/odata-url-conventions/5 Query Options.md +++ b/odata-url-conventions/5 Query Options.md @@ -57,8 +57,8 @@ The same system query option, irrespective of casing or whether or not it is prefixed with a `$`, MUST NOT be specified more than once for any resource. -The semantics of all system query options are defined in the -[OData-Protocol](#ODataProtocol) document. +The semantics of all system query options are defined in +[#OData-Protocol#SystemQueryOptions]. The grammar and syntax rules for system query options are defined in [OData-ABNF](#ODataABNF). @@ -1909,7 +1909,7 @@ Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the [`Core.DefaultNamespace`]($$$OData-VocCore$$$#DefaultNamespace) annotation term defined in [OData-VocCore](#ODataVocCore). For more information on -default namespaces, see Default Namespaces in [OData-Protocol](#ODataProtocol). +default namespaces, see [#OData-Protocol#DefaultNamespaces]. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a [parameter alias](#ParameterAliases), then any occurrence of the parameter alias @@ -2336,7 +2336,7 @@ omitted from the response. Annotations requested in `$select` MUST be included in the response; `$select` overrules the `include-annotations` preference (see -[OData-Protocol](#ODataProtocol)) for the explicitly requested annotations. +[#OData-Protocol#Preferenceincludeannotationsodataincludeannotations]) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via `$select`. The `Preference-Applied` response header only reflects the set of annotations included due to the @@ -2375,8 +2375,7 @@ identified by each select item. The `$orderby` system query option allows clients to request resources in a particular order. -The semantics of `$orderby` are covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$orderby` are covered in [#OData-Protocol#SystemQueryOptionorderby]. The [OData-ABNF](#ODataABNF) `orderby` syntax rule defines the formal grammar of the `$orderby` query option. @@ -2389,8 +2388,9 @@ option requests the number of items in the queried collection that are to be skipped and not included in the result. A client can request a particular page of items by combining `$top` and `$skip`. -The semantics of `$top` and `$skip` are covered in the -[OData-Protocol](#ODataProtocol) document. The [OData-ABNF](#ODataABNF) `top` +The semantics of `$top` and `$skip` are covered in +[#OData-Protocol#SystemQueryOptiontop] and [#OData-Protocol#SystemQueryOptionskip]. +The [OData-ABNF](#ODataABNF) `top` and `skip` syntax rules define the formal grammar of the `$top` and `$skip` query options respectively. @@ -2400,8 +2400,7 @@ The `$count` system query option allows clients to request a count of the matching resources included with the resources in the response. The `$count` query option has a Boolean value of `true` or `false`. -The semantics of `$count` is covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$count` is covered in [#OData-Protocol#SystemQueryOptioncount]. ### ##subsubsec System Query Option `$search` @@ -2483,8 +2482,7 @@ in a particular format and is useful for clients without access to request headers for standard content-type negotiation. Where present `$format` takes precedence over standard content-type negotiation. -The semantics of `$format` is covered in the [OData-Protocol](#ODataProtocol) -document. +The semantics of `$format` is covered in [#OData-Protocol#SystemQueryOptionformat]. The [OData-ABNF](#ODataABNF) `format` syntax rule defines the formal grammar of the `$format` query option. @@ -2547,7 +2545,7 @@ grammar of the `$index` query option. The `$schemaversion` system query option allows clients to specify the version of the schema against which the request is made. The semantics -of `$schemaversion` is covered in the [OData-Protocol](#ODataProtocol) document. +of `$schemaversion` is covered in [#OData-Protocol#SystemQueryOptionschemaversion]. The [OData-ABNF](#ODataABNF) `schemaversion` syntax rule defines the formal grammar of the `$schemaversion` query option @@ -2579,7 +2577,7 @@ Parameter aliases MUST start with an `@` character, see rule `parameterAlias` in [OData-ABNF](#ODataABNF). The semantics of parameter aliases are covered in -[OData-Protocol](#ODataProtocol). The [OData-ABNF](#ODataABNF) rule +[#OData-Protocol#ParameterAliases]. The [OData-ABNF](#ODataABNF) rule `aliasAndValue` defines the formal grammar for passing parameter alias values as query options. @@ -2612,4 +2610,4 @@ http://host/service/Products/Model.WithIngredients(Ingredients=@i) # ##sec Conformance The conformance requirements for OData clients and services are -described in [OData-Protocol](#ODataProtocol). +described in [#OData-Protocol#Conformance]. diff --git a/odata-vocabularies/Appendix.md b/odata-vocabularies/Appendix.md index 96dbe7e9..00357a24 100644 --- a/odata-vocabularies/Appendix.md +++ b/odata-vocabularies/Appendix.md @@ -50,7 +50,7 @@ do we have considerations specific to URLs, for example length, encoding, privac ## ##subasec Special Thanks -The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol), are gratefully acknowledged. +The contributions of the OASIS OData Technical Committee members, enumerated in [#OData-Protocol#Partipants], are gratefully acknowledged. ## ##subasec Participants From 874253e07c209a67ce27fe3e551d090aaecefb30 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 6 Nov 2024 19:01:24 +0100 Subject: [PATCH 3/8] return=minimal for status monitor resources (#2024) Fixes #336 --- docs/odata-protocol/odata-protocol.html | 4 ++-- docs/odata-protocol/odata-protocol.md | 14 ++++++++------ odata-protocol/11.5 Operations.md | 14 ++++++++------ 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 35d02a8b..24440406 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -3013,8 +3013,8 @@

      202 Accepted response. A service MUST NOT reply to a Data Service Request with 202 Accepted if the request has not included the respond-async preference.

      Responses that return 202 Accepted MUST include a Location header pointing to a status monitor resource that represents the current state of the asynchronous processing in addition to an optional Retry-After header indicating the time, in seconds, the client should wait before querying the service for status. Services MAY include a response body, for example, to provide additional status information.

      A GET request to the status monitor resource again returns 202 Accepted response if the asynchronous processing has not finished. This response MUST again include a Location header and MAY include a Retry-After header to be used for a subsequent request. The Location header and optional Retry-After header may or may not contain the same values as returned by the previous request.

      -

      A GET request to the status monitor resource returns 200 OK once the asynchronous processing has completed. For OData 4.01 or greater responses, or OData 4.0 requests that include an Accept header that does not specify application/http, the response MUST include the AsyncResult response header. Any other headers, along with the response body, represent the result of the completed asynchronous operation. If the GET request to the status monitor includes an OData-MaxVersion header with a value of 4.0 and no Accept header, or an Accept header that includes application/http, then the body of the final 200 OK response MUST be represented as an HTTP message, as described in RFC9110, which is the full HTTP response to the completed asynchronous operation.

      -

      A DELETE request sent to the status monitor resource requests that the asynchronous processing be canceled. A 200 OK or a 204 No Content response indicates that the asynchronous processing has been successfully canceled. A client can request that the DELETE should be executed asynchronously. A 202 Accepted response indicates that the cancellation is being processed asynchronously; the client can use the returned Location header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns 405 Method Not Allowed.

      +

      Once the asynchronous processing has completed, a GET request to the status monitor resource returns 200 OK, or 204 No Content if the request included a Prefer header with a value of return=minimal that was applied by the service. For OData 4.01 or greater responses, or OData 4.0 requests that include an Accept header that does not specify application/http, the response MUST include the AsyncResult response header. A 204 No Content response MUST include a Location header that contains the status monitor resource URL that can be used to request the result of the completed asynchronous operation. This may or may not be the current request’s URL. In a 200 OK response any other headers, along with the response body, represent the result of the completed asynchronous operation. If the GET request to the status monitor includes an OData-MaxVersion header with a value of 4.0 and no Accept header, or an Accept header that includes application/http, then the body of the final 200 OK response MUST be represented as an HTTP message, as described in RFC9110, which is the full HTTP response to the completed asynchronous operation.

      +

      A DELETE request sent to the status monitor resource requests that the asynchronous processing be canceled. A 200 OK or a 204 No Content response indicates that the asynchronous processing has been successfully canceled. A client can request that the DELETE should be executed asynchronously. A 202 Accepted response indicates that the cancellation is being processed asynchronously; the client can use the returned Location header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns 405 Method Not Allowed.

      After a successful DELETE request against the status monitor resource, any subsequent GET requests for the same status monitor resource returns 404 Not Found.

      If an asynchronous request is cancelled for reasons other than the consumers issuing a DELETE request against the status monitor resource, a GET request to the status monitor resource returns 200 OK with a response body containing a single HTTP response with a status code in the 5xx Server Error range indicating that the operation was cancelled.

      The service MUST ensure that no observable change has occurred as a result of a canceled request.

      diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index 88e7ac8d..acc0233c 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -5864,11 +5864,13 @@ and MAY include a [`Retry-After`](#HeaderRetryAfter) header to be used for a sub `Location` header and optional `Retry-After` header may or may not contain the same values as returned by the previous request. -A `GET` request to the status monitor resource returns [`200 OK`](#ResponseCode200OK) once the -asynchronous processing has completed. For OData 4.01 or greater -responses, or OData 4.0 requests that include an `Accept` header that +Once the asynchronous processing has completed, a `GET` request to the status monitor resource returns [`200 OK`](#ResponseCode200OK), +or [`204 No Content`](#ResponseCode204NoContent) if the request included a `Prefer` header with a value of `return=minimal` that was applied by the service. +For OData 4.01 or greater responses, or OData 4.0 requests that include an `Accept` header that does not specify `application/http`, the response MUST include the -[`AsyncResult`](#HeaderAsyncResult) response header. Any other headers, +[`AsyncResult`](#HeaderAsyncResult) response header. +A `204 No Content` response MUST include a `Location` header that contains the status monitor resource URL that can be used to request the result of the completed asynchronous operation. This may or may not be the current request's URL. +In a `200 OK` response any other headers, along with the response body, represent the result of the completed asynchronous operation. If the `GET` request to the status monitor includes an `OData-MaxVersion` header with a value of `4.0` and no @@ -5879,11 +5881,11 @@ HTTP response to the completed asynchronous operation. A `DELETE` request sent to the status monitor resource requests that the asynchronous processing be canceled. A `200 OK` or a -[`204 No Content`](#ResponseCode204NoContent) response indicates that the asynchronous processing has +`204 No Content` response indicates that the asynchronous processing has been successfully canceled. A client can request that the `DELETE` should be executed asynchronously. A `202 Accepted` response indicates that the cancellation is being processed asynchronously; the client can -use the returned [`Location`](#HeaderLocation) header (which MUST be +use the returned `Location` header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns diff --git a/odata-protocol/11.5 Operations.md b/odata-protocol/11.5 Operations.md index 9313aaab..4d5d0892 100644 --- a/odata-protocol/11.5 Operations.md +++ b/odata-protocol/11.5 Operations.md @@ -505,11 +505,13 @@ and MAY include a [`Retry-After`](#HeaderRetryAfter) header to be used for a sub `Location` header and optional `Retry-After` header may or may not contain the same values as returned by the previous request. -A `GET` request to the status monitor resource returns [`200 OK`](#ResponseCode200OK) once the -asynchronous processing has completed. For OData 4.01 or greater -responses, or OData 4.0 requests that include an `Accept` header that +Once the asynchronous processing has completed, a `GET` request to the status monitor resource returns [`200 OK`](#ResponseCode200OK), +or [`204 No Content`](#ResponseCode204NoContent) if the request included a `Prefer` header with a value of `return=minimal` that was applied by the service. +For OData 4.01 or greater responses, or OData 4.0 requests that include an `Accept` header that does not specify `application/http`, the response MUST include the -[`AsyncResult`](#HeaderAsyncResult) response header. Any other headers, +[`AsyncResult`](#HeaderAsyncResult) response header. +A `204 No Content` response MUST include a `Location` header that contains the status monitor resource URL that can be used to request the result of the completed asynchronous operation. This may or may not be the current request's URL. +In a `200 OK` response any other headers, along with the response body, represent the result of the completed asynchronous operation. If the `GET` request to the status monitor includes an `OData-MaxVersion` header with a value of `4.0` and no @@ -520,11 +522,11 @@ HTTP response to the completed asynchronous operation. A `DELETE` request sent to the status monitor resource requests that the asynchronous processing be canceled. A `200 OK` or a -[`204 No Content`](#ResponseCode204NoContent) response indicates that the asynchronous processing has +`204 No Content` response indicates that the asynchronous processing has been successfully canceled. A client can request that the `DELETE` should be executed asynchronously. A `202 Accepted` response indicates that the cancellation is being processed asynchronously; the client can -use the returned [`Location`](#HeaderLocation) header (which MUST be +use the returned `Location` header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns From 616b74d61220cd5b939a3c6421cc91180b511a4e Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 13 Nov 2024 18:31:39 +0100 Subject: [PATCH 4/8] Use really simple identifiers (#2016) Fixes #375 --- docs/odata-csdl-json/odata-csdl-json.html | 9 ++++++++- docs/odata-csdl-json/odata-csdl-json.md | 8 +++++++- docs/odata-csdl-xml/odata-csdl-xml.html | 9 ++++++++- docs/odata-csdl-xml/odata-csdl-xml.md | 8 +++++++- odata-csdl/1 Introduction.md | 1 + odata-csdl/15 Identifier and Path Values.md | 7 ++++++- 6 files changed, 37 insertions(+), 5 deletions(-) diff --git a/docs/odata-csdl-json/odata-csdl-json.html b/docs/odata-csdl-json/odata-csdl-json.html index e4dfd831..718ece73 100644 --- a/docs/odata-csdl-json/odata-csdl-json.html +++ b/docs/odata-csdl-json/odata-csdl-json.html @@ -489,6 +489,11 @@

      326

      + + + + + @@ -3888,6 +3893,7 @@

      The remaining characters MUST be the underscore character (U+005F) or any character in the Unicode category “Letter (L)”, “Letter number (Nl)”, “Decimal number (Nd)”, “Non-spacing mark (Mn)”, “Combining spacing mark (Mc)”, “Connector punctuation (Pc)”, and “Other, format (Cf)”.

      Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits.

      +

      For maximum interoperability services SHOULD use simple identifiers that additionally only consist of characters from the Basic Latin code block and match the pattern ^[_A-Za-z][_A-Za-z0-9]*$.

      15.3 Qualified Name

      @@ -4225,9 +4231,10 @@

      17 Conformance
    • SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case
      • -

      In addition, OData 4.01 services:

      +

      In addition, OData 4.02 or greater services:

      1. SHOULD NOT include constant Geo or Stream values in annotations
        2. +
      2. SHOULD use simple identifiers matching the pattern ^[_A-Za-z][_A-Za-z0-9]*$

      Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom annotations, and MUST ignore constructs not defined in this version of the specification.

      diff --git a/docs/odata-csdl-json/odata-csdl-json.md b/docs/odata-csdl-json/odata-csdl-json.md index 6acf0845..f8f960a6 100644 --- a/docs/odata-csdl-json/odata-csdl-json.md +++ b/docs/odata-csdl-json/odata-csdl-json.md @@ -273,6 +273,7 @@ Section | Feature / Change | Issue [Section 14.3.14](#StreamValues) | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [575](https://github.com/oasis-tcs/odata-specs/issues/575) [Section 14.4.7](#IfThenElse)| Nested `If` without else part in collections| [326](https://github.com/oasis-tcs/odata-specs/issues/326) +[Section 15.2](#SimpleIdentifier) | Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers | [375](https://github.com/oasis-tcs/odata-specs/issues/375) [Section 17](#Conformance) | Additional conformance clauses for version 4.02 | ## 1.2 Glossary @@ -5695,6 +5696,10 @@ restrictions: Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits. +For maximum interoperability services SHOULD use simple identifiers +that additionally only consist of characters from the Basic Latin code block +and match the pattern `^[_A-Za-z][_A-Za-z0-9]*$`. + ## 15.3 Qualified Name For model elements that are direct children of a schema: the namespace @@ -6071,9 +6076,10 @@ In addition, OData 4.01 or greater services: schema, a structural type, or an entity container) that differ only by case -In addition, OData 4.01 services: +In addition, OData 4.02 or greater services: 15. SHOULD NOT include constant [Geo](#GeoValues) or [Stream values](#StreamValues) in annotations +16. SHOULD use [simple identifiers](#SimpleIdentifier) matching the pattern `^[_A-Za-z][_A-Za-z0-9]*$` Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html index 3c57b6db..8eb5d574 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.html +++ b/docs/odata-csdl-xml/odata-csdl-xml.html @@ -493,6 +493,11 @@

      326

      + + + + + @@ -3642,6 +3647,7 @@

      The remaining characters MUST be the underscore character (U+005F) or any character in the Unicode category “Letter (L)”, “Letter number (Nl)”, “Decimal number (Nd)”, “Non-spacing mark (Mn)”, “Combining spacing mark (Mc)”, “Connector punctuation (Pc)”, and “Other, format (Cf)”.

      Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits.

      +

      For maximum interoperability services SHOULD use simple identifiers that additionally only consist of characters from the Basic Latin code block and match the pattern ^[_A-Za-z][_A-Za-z0-9]*$.

      15.3 Qualified Name

      @@ -3861,9 +3867,10 @@

      17 Conformance
    • SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case
      • -

      In addition, OData 4.01 services:

      +

      In addition, OData 4.02 or greater services:

      1. SHOULD NOT include constant Geo or Stream values in annotations
        2. +
      2. SHOULD use simple identifiers matching the pattern ^[_A-Za-z][_A-Za-z0-9]*$

      Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom annotations, and MUST ignore constructs not defined in this version of the specification.

      diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md index a8a554ec..9b762167 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.md +++ b/docs/odata-csdl-xml/odata-csdl-xml.md @@ -274,6 +274,7 @@ Section | Feature / Change | Issue [Section 14.3.14](#StreamValues) | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.4.1.2](#PathEvaluation)| New path evaluation rules for annotations targeting annotations and external targeting via container| [575](https://github.com/oasis-tcs/odata-specs/issues/575) [Section 14.4.7](#IfThenElse)| Nested `If` without else part in collections| [326](https://github.com/oasis-tcs/odata-specs/issues/326) +[Section 15.2](#SimpleIdentifier) | Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers | [375](https://github.com/oasis-tcs/odata-specs/issues/375) [Section 17](#Conformance) | Additional conformance clauses for version 4.02 | ## 1.2 Glossary @@ -5495,6 +5496,10 @@ restrictions: Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits. +For maximum interoperability services SHOULD use simple identifiers +that additionally only consist of characters from the Basic Latin code block +and match the pattern `^[_A-Za-z][_A-Za-z0-9]*$`. + ## 15.3 Qualified Name For model elements that are direct children of a schema: the namespace @@ -5753,9 +5758,10 @@ In addition, OData 4.01 or greater services: schema, a structural type, or an entity container) that differ only by case -In addition, OData 4.01 services: +In addition, OData 4.02 or greater services: 15. SHOULD NOT include constant [Geo](#GeoValues) or [Stream values](#StreamValues) in annotations +16. SHOULD use [simple identifiers](#SimpleIdentifier) matching the pattern `^[_A-Za-z][_A-Za-z0-9]*$` Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom diff --git a/odata-csdl/1 Introduction.md b/odata-csdl/1 Introduction.md index 16330f22..1fe28e19 100644 --- a/odata-csdl/1 Introduction.md +++ b/odata-csdl/1 Introduction.md @@ -56,6 +56,7 @@ New path evaluation rules for annotations targeting annotations and external tar [Section ##IfThenElse]| Nested `If` without else part in collections| [326](https://github.com/oasis-tcs/odata-specs/issues/326) +[Section ##SimpleIdentifier] | Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers | [375](https://github.com/oasis-tcs/odata-specs/issues/375) [Section ##Conformance] | Additional conformance clauses for version 4.02 | ## ##subsec Glossary diff --git a/odata-csdl/15 Identifier and Path Values.md b/odata-csdl/15 Identifier and Path Values.md index 2ef481f0..3ed1a3c9 100644 --- a/odata-csdl/15 Identifier and Path Values.md +++ b/odata-csdl/15 Identifier and Path Values.md @@ -28,6 +28,10 @@ restrictions: Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits. +For maximum interoperability services SHOULD use simple identifiers +that additionally only consist of characters from the Basic Latin code block +and match the pattern `^[_A-Za-z][_A-Za-z0-9]*$`. + ## ##subsec Qualified Name For model elements that are direct children of a schema: the namespace @@ -574,9 +578,10 @@ In addition, OData 4.01 or greater services: schema, a structural type, or an entity container) that differ only by case -In addition, OData 4.01 services: +In addition, OData 4.02 or greater services: 15. SHOULD NOT include constant [Geo](#GeoValues) or [Stream values](#StreamValues) in annotations +16. SHOULD use [simple identifiers](#SimpleIdentifier) matching the pattern `^[_A-Za-z][_A-Za-z0-9]*$` Conforming clients MUST be prepared to consume a model that uses any or all constructs defined in this specification, including custom From f950cddb3bf199892b9a66d02dca7d6aeb9d8189 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Wed, 20 Nov 2024 17:18:27 +0100 Subject: [PATCH 5/8] Example 78 (#2030) --- .../odata-data-aggregation-ext.html | 3 +-- docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md | 4 +--- odata-data-aggregation-ext/7 Examples.md | 4 +--- 3 files changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html index a84c280a..c9d45241 100644 --- a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html +++ b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html @@ -3628,12 +3628,11 @@

      { "ID": "P3", "Name": "Paper", "Color": "White", "TaxRate": 0.14, "Total@type": "Decimal", "Total": 8 }, { "ID": "P4", "Name": "Pencil", "Color": "Black", "TaxRate": 0.14, - "Total": null }, + "Total": null }, { "ID": "P1", "Name": "Sugar", "Color": "White", "TaxRate": 0.06, "Total@type": "Decimal", "Total": 4 } ] } -

      The expression $it/Sales refers to the sales of the current product. Without $it, all sales of all products would be aggregated, because the input collection for the aggregate function consists of all products.

      Example 79: Alternatively, join could be applied to yield a flat structure:

      diff --git a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md index 8f691ab1..7c9ac06b 100644 --- a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md +++ b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md @@ -3471,14 +3471,12 @@ results in { "ID": "P3", "Name": "Paper", "Color": "White", "TaxRate": 0.14, "Total@type": "Decimal", "Total": 8 }, { "ID": "P4", "Name": "Pencil", "Color": "Black", "TaxRate": 0.14, - "Total": null }, + "Total": null }, { "ID": "P1", "Name": "Sugar", "Color": "White", "TaxRate": 0.06, "Total@type": "Decimal", "Total": 4 } ] } ``` - -The expression `$it/Sales` refers to the sales of the current product. Without `$it`, all sales of all products would be aggregated, because the input collection for the `aggregate` function consists of all products. ::: ::: example diff --git a/odata-data-aggregation-ext/7 Examples.md b/odata-data-aggregation-ext/7 Examples.md index 20aafd33..061e3695 100644 --- a/odata-data-aggregation-ext/7 Examples.md +++ b/odata-data-aggregation-ext/7 Examples.md @@ -233,14 +233,12 @@ results in { "ID": "P3", "Name": "Paper", "Color": "White", "TaxRate": 0.14, "Total@type": "Decimal", "Total": 8 }, { "ID": "P4", "Name": "Pencil", "Color": "Black", "TaxRate": 0.14, - "Total": null }, + "Total": null }, { "ID": "P1", "Name": "Sugar", "Color": "White", "TaxRate": 0.06, "Total@type": "Decimal", "Total": 4 } ] } ``` - -The expression `$it/Sales` refers to the sales of the current product. Without `$it`, all sales of all products would be aggregated, because the input collection for the `aggregate` function consists of all products. ::: ::: example From 53c6062d067a22a1dbb468bd23567ab60053d932 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Wed, 20 Nov 2024 17:43:07 +0100 Subject: [PATCH 6/8] Context fragment of contained single entity (#2009) Fixes #2000 --- docs/odata-protocol/odata-protocol.html | 696 ++++++++++++------------ docs/odata-protocol/odata-protocol.md | 373 +++++++------ odata-protocol/10 Context URL.md | 179 +++--- scripts/folding.html | 2 +- 4 files changed, 638 insertions(+), 612 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 24440406..d6a41cee 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -1301,15 +1301,16 @@

      10 Context URL

      For details on how the context URL is used to describe a payload, see the relevant sections in the particular format.

      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 or path to a containment navigation property,
        • -
      • {entity} is the canonical URL for an entity,
        • -
      • {singleton} is the canonical URL for a singleton entity,
        • -
      • {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,
        • +
      • {context-url} is the canonical resource path to the $metadata document.
        • +
      • A canonical collection is an entity set OData-CSDL, section 13.2 or a collection addressed by a containment navigation property OData-CSDL, section 8.4. We denote by {canonical-collection} the canonical URL OData-URL, section 4.3.1 that addresses a canonical collection relative to the service root.
        • +
      • A canonical singleton is a singleton OData-CSDL, section 13.3 or an entity addressed by a single-valued containment navigation property. We denote by {canonical-singleton} the canonical URL that addresses a canonical singleton relative to the service root.
        • +
      • A canonical member is an entity within a canonical collection. We denote by {canonical-member} the canonical URL that addresses a canonical member relative to the service root.
        • +
      • {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 {canonical-collection}, {canonical-singleton}, and {canonical-member} 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.

      10.1 Service Document

      @@ -1327,62 +1328,65 @@

      10

      10.2 Collection of Entities

      Context URL template:

      -
      {context-url}#{entity-set}
+
      {context-url}#{canonical-collection}
 {context-url}#Collection({type-name})
      
-
      If all entities in the collection are members of one entity set, its name is the context URL fragment.
      
+
      If all entities in the response or a response part are members of a single canonical collection, the context URL fragment is the {canonical-collection}.
      
 
      
 
      Example 11: resource URL and corresponding context URL
      
 
      http://host/service/Customers
 http://host/service/$metadata#Customers
      
 
      
-
      If the entities are contained, then entity-set is the top-level entity set or singleton followed by the canonical path to the containment navigation property of the containing entity. Key values in that path are represented in canonical form (parentheses-style) without percent-encoding.
      
 
      
 
      Example 12: resource URL and corresponding context URL for contained entities
      
 
      http://host/service/Orders(4711)/Items
 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 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.
      
+
      If the entities are not members of a single canonical collection, such as entities 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.

      10.3 Entity

      Context URL template:

      -
      {context-url}#{entity-set}/$entity
+
      {context-url}#{canonical-collection}/$entity
 {context-url}#{type-name}
      
-
      If a response or response part is a single entity of the declared type of an entity set, the context URL fragment is the entity set’s name with /$entity appended.
      
+
      If a response or response part is an entity within in a canonical collection, the context URL fragment is the {canonical-collection} with /$entity appended.
      
 
      
-
      Example 13: resource URL and corresponding context URL
      
+
      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
      
 
      
-
      If the entity is contained, then entity-set is the top-level entity set or singleton followed by the path to the containment navigation property of the containing entity.
      
 
      
 
      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 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 of the returned entity.
      
+
      If the entity is within a collection, but a canonical collection 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-name} of the returned entity.

      10.4 Singleton

      Context URL template:

      -
      {context-url}#{singleton}
      -

      If a response or response part is a singleton, its name is the context URL fragment.

      +
      {context-url}#{canonical-singleton}
      +

      If a response or response part is a canonical singleton, the context URL fragment is the {canonical-singleton} without /$entity appended.

      Example 15: resource URL and corresponding context URL

      http://host/service/MainSupplier
 http://host/service/$metadata#MainSupplier
      +
      +

      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}#{canonical-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 16: resource URL and corresponding context URL

      +

      Example 17: resource URL and corresponding context URL

      http://host/service/Customers/Model.VipCustomer
 http://host/service/$metadata#Customers/Model.VipCustomer
      @@ -1391,28 +1395,34 @@

      10.6 Derived Entity

      Context URL template:

      -
      {context-url}#{entity-set}{/type-name}/$entity
      -

      If a response or response part is a single 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}#{canonical-collection}{/type-name}/$entity
+{context-url}#{canonical-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 {canonical-collection} or {canonical-singleton} and prior to appending /$entity, if any.

      -

      Example 17: 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}#{canonical-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 18: 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)
      
 
      
@@ -1421,17 +1431,17 @@ 
      10.8 Projected Entity
      
 
 
      Context URL templates:
      
-
      {context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{singleton}{select-list}
+
      {context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+{context-url}#{canonical-singleton}{/type-name}{select-list}
 {context-url}#{type-name}{select-list}
      
-
      If a single 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. 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 {canonical-collection} or {canonical-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 19: 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
      
 
      
@@ -1440,7 +1450,7 @@ 
      10
 
      10.9 Collection of Expanded Entities
      
 
 
      Context URL template:
      
-
      {context-url}#{entity-set}{/type-name}{select-list}
+
      {context-url}#{canonical-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.
      
@@ -1448,17 +1458,17 @@ 
      
-
      Example 20: 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 21: 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 22: 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
@@ -1469,15 +1479,15 @@ 
      10.10 Expanded Entity
      
 
 
      Context URL template:
      
-
      {context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{singleton}{select-list}
+
      {context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+{context-url}#{canonical-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 23: 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
@@ -1491,7 +1501,7 @@ 
      
-
      Example 24: 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)
      
 
      
@@ -1503,7 +1513,7 @@ 
      1
 
      {context-url}#$ref
      
 
      If a response is a single entity reference, $ref is the context URL fragment.
      
 
      
-
      Example 25: 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
      
 
      
@@ -1512,12 +1522,12 @@ 
      1
 
      10.13 Property Value
      
 
 
      Context URL templates:
      
-
      {context-url}#{entity}/{property-path}{select-list}
+
      {context-url}#{canonical-member}/{property-path}{select-list}
 {context-url}#{type-name}{select-list}
      
-
      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 a response represents an individual property of a canonical member, the context URL specifies the {canonical-member} and the path to the structural property. 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 26: 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
      
 
      
@@ -1527,9 +1537,9 @@ 
      
-
      Example 27: 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)
      @@ -1539,9 +1549,9 @@

      -

      Example 28: resource URL and corresponding context URL

      +

      Example 30: resource URL and corresponding context URL

      http://host/service/MostPopularName()
 http://host/service/$metadata#Edm.String
      @@ -1549,15 +1559,9 @@

      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}/{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 a single 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 a single 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.

      +

      The context URL in a response from an action or function has one of the formats described so far (except the service document format). It does not mention the name of the invoked action or function.

      -

      Example 29: resource URL and corresponding context URL

      +

      Example 31: resource URL and corresponding context URL

      http://host/service/TopFiveCustomers()
 http://host/service/$metadata#Customers
      @@ -1566,14 +1570,14 @@

      1

      10.17 Delta Payload

      Context URL template:

      -
      {context-url}#{entity-set}{/type-name}{select-list}/$delta
-{context-url}#{entity}{select-list}/$delta
-{context-url}#{entity}/{property-path}{select-list}/$delta
+
      {context-url}#{canonical-collection}{/type-name}{select-list}/$delta
+{context-url}#{canonical-member}{select-list}/$delta
+{context-url}#{canonical-member}/{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 {canonical-collection} is the top-level entity set followed by the path to the containment navigation property of the containing entity.
      
 
      
-
      Example 30: 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
      
 
      
@@ -1583,10 +1587,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}#{canonical-collection}/$deletedEntity
+{context-url}#{canonical-collection}/$link
+{context-url}#{canonical-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. {canonical-collection} corresponds to the set of the deleted entity, or source entity for an added or deleted link.
      
 
 
      
 
      10.19 $all Response
      
@@ -1728,7 +1732,7 @@ 
      204 No Content.
      
 
      If the property is not available, for example due to permissions, the service responds with 404 Not Found.
      
 
      
-
      Example 31:
      
+
      Example 33:
      
 
      GET http://host/service/Products(1)/Name
      
 
      
 
      
@@ -1749,7 +1753,7 @@ 
      204 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 32:
      
+
      Example 34:
      
 
      GET http://host/service/Products(1)/Name/$value
      
 
      
 
      
@@ -1764,27 +1768,27 @@ 
      actions and functions explicitly requested by the client. The service returns the specified content, if available, along with any available expanded navigation or stream properties, and MAY return additional information.
      
 
      The 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 33: 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,ReleaseDate
      
 
      
 
      It 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 34:
      
+
      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 35:
      
+
      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 36: 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,Products
      
 
      
 
      It is also possible to request all actions or functions available for each returned entity.
      
 
      
-
      Example 37:
      
+
      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.
      
@@ -1798,15 +1802,15 @@ 
      OData-URL, section 5.1.3.
      
 
      
-
      Example 38: 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=Orders
      
 
      
 
      
-
      Example 39: 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/$ref
      
 
      
 
      
-
      Example 40: 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=Photo
      
 
      
 
      
@@ -1815,11 +1819,11 @@ 
      11.2.
 
      The 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, section 5.1.3.
      
 
      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 41: 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 42: 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:
      
 
      
 
      
-
      Example 43: 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
      
 
      
 
      
@@ -1838,7 +1842,7 @@ 
      
-
      Example 44: return each employee from the Employees entity set and, for each employee that is a manager, return all direct reports, recursively to four levels
      
+
      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
      
 
      GET http://host/service/Employees?$expand=Model.Manager/DirectReports($levels=4)
      
 
 
      
@@ -1850,7 +1854,7 @@ 
      The $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 45: 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
@@ -1870,12 +1874,12 @@ 
      
-
      Example 46: 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 47: 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
      
 
      
 
      The value of the $filter option is a Boolean expression as defined in OData-ABNF.
      
@@ -1975,7 +1979,7 @@ 
      function parameters, or within a $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 48: 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.
      
@@ -1983,7 +1987,7 @@ 
      
-
      Example 49: 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))
      
 
 
      
@@ -2000,17 +2004,17 @@ 
      Services SHOULD order language-dependent strings according to the 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 50: 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 desc
      
 
      
 
      Related entities may be ordered by specifying $orderby within the $expand clause.
      
 
      
-
      Example 51: 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 52: 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
      
 
      
 
      
@@ -2021,7 +2025,7 @@ 
      \(A\) be a copy of the result set with a total order that extends any existing order of the result set but is otherwise chosen by the service. If no unique ordering is imposed through an $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 53: 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
      
 
      
 
@@ -2032,12 +2036,12 @@ 
      \(A\) be a copy of the result set with a total order that extends any existing order of the result set but is otherwise chosen by the service. If no unique ordering is imposed through an $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 54: 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=5
      
 
      
 
      Where $top and $skip are used together, $skip MUST be applied before $top, regardless of the order in which they appear in the request.
      
 
      
-
      Example 55: 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=2
      
 
      
 
      If no unique ordering is imposed through an $orderby query option, the service MUST impose a stable ordering across requests that include $skip.
      
@@ -2047,12 +2051,12 @@ 
      
-
      Example 56: 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=true
      
 
 
      The count of related entities can be requested by specifying the $count query option within the $expand clause.
      
 
      
-
      Example 57:
      
+
      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.
      
@@ -2065,32 +2069,32 @@
      + +
      +

      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.

      @@ -2412,29 +2416,29 @@

      $expand. Instead, the values are generally read or written through URLs.

      -

      Example 81: 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

      would 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.jpg

      Services 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 82: 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

      can 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.

      @@ -2671,7 +2675,7 @@

      -

      Example 83: delete the stream value using the media edit link retrieved in example 81

      +

      Example 85: delete the stream value using the media edit link retrieved in example 83

      DELETE http://server/uploads/Thumbnail546.jpg

      Attempting to request a stream property whose value is null results in 204 No Content.

      @@ -2733,13 +2737,13 @@

      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 84: 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"
+}
      @@ -2794,13 +2798,13 @@

      For primitive-typed collections the body of the request MUST be a primitive value. Each member of the potentially filtered collection is updated to the specified primitive value.

      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 85: 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.

      @@ -2813,7 +2817,7 @@

      Members of a collection can be deleted by submitting a 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 86: delete all products older than 3

      +

      Example 88: delete all products older than 3

      DELETE /service/Products/$filter(Age gt 3)/$each

      If 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.

      @@ -2832,25 +2836,25 @@

      Actions and Functions MAY be bound to any type or collection, similar to defining a method in a class in object-oriented programming. The first parameter of a bound operation is the binding parameter.

      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 87: 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 88: 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 89: 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 90: 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()

      @@ -2861,7 +2865,7 @@

      -

      Example 91: 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.

      @@ -2872,29 +2876,29 @@

      format.

      -

      Example 92: 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, section 4.5.

      -

      Services can advertise that a function or action is not available for a particular instance by setting its value to null.

      -
      -

      Example 93: 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,
-  …
-}
      + "#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, section 4.5.

      +

      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,
+  …
+}
      @@ -2912,7 +2916,7 @@

      inline parameter syntax. The canonical URL for a function import is the service root, followed by the name of the function import. Services MAY support omitting the parentheses when invoking a function import with no parameters, but for maximum interoperability MUST also support invoking the function import with empty parentheses.

      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 94: 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
 
 …
      @@ -2929,22 +2933,22 @@
      -

      Example 95: 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 96: 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 97: 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=3

      Services 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 98: 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=3

      Non-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.

      @@ -2984,18 +2988,18 @@

      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 99: 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"
+}

      @@ -3035,7 +3039,7 @@

      multipart batch format MUST contain a Content-Type header specifying a content type of multipart/mixed and a boundary parameter as defined in RFC2046.

      -

      Example 100: multipart batch request

      +

      Example 102: multipart batch request

      POST /service/$batch HTTP/1.1
 Host: odata.org
 OData-Version: 4.0
@@ -3045,7 +3049,7 @@ 
      
-
      Example 101: JSON batch request
      
+
      Example 103: JSON batch request
      
 
      POST /service/$batch HTTP/1.1
 Host: odata.org
 OData-Version: 4.01
@@ -3072,7 +3076,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 106.

      +

      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.

      @@ -3106,25 +3110,25 @@

      Absolute URI with schema, host, port, and absolute resource path.
      -

      Example 102:

      +

      Example 104:

      GET https://host:1234/path/service/People(1) HTTP/1.1
      • Absolute resource path and separate Host header
      -

      Example 103:

      -
      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 104:

      +

      Example 106:

      DELETE People(1) HTTP/1.1

      Services MUST support all three formats for URLs of individual requests.

      @@ -3136,7 +3140,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 105: 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

      1. A query request
      2. A change set that contains the following requests: @@ -3202,7 +3206,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 106: 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)
          • @@ -3262,54 +3266,54 @@

          example 103). 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 107: 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 108: 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
          • @@ -3358,9 +3362,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 106). 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 109: referencing the batch request example 105 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: ####
@@ -3414,7 +3418,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 110: referencing the example 105 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 acc0233c..de6c788d 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -1998,23 +1998,33 @@ 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 or path to a containment navigation property,
-- `{entity}` is the canonical URL for an
-entity,
-- `{singleton}` is the canonical URL for a
-singleton entity,
+resource path to the `$metadata` document.
+- A _canonical collection_ is 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 a collection addressed by a containment navigation property
+[OData-CSDL, section 8.4](https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#ContainmentNavigationProperty).
+We denote by `{canonical-collection}` the canonical URL [OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL)
+that addresses a canonical collection relative to the service root.
+- A _canonical singleton_ is a singleton [OData-CSDL, section 13.3](https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#Singleton)
+or an entity addressed by a single-valued containment
+navigation property.
+We denote by `{canonical-singleton}` the canonical URL
+that addresses a canonical singleton relative to the service root.
+- A _canonical member_ is an entity within a canonical collection.
+We denote by `{canonical-member}` the canonical URL
+that addresses a canonical member relative to the service root.
 - `{select-list}` is an optional
 parenthesized comma-separated list of selected properties, instance
-annotations, functions, and actions,
+annotations, functions, and actions.
 - `{property-path}` is the
-path to a structural property of the entity,
-- `{type-name}` is a qualified type name,
+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 `{canonical-collection}`, `{canonical-singleton}`, and `{canonical-member}` are represented in canonical form
+(parentheses-style) without percent-encoding.
+
 The full grammar for the context URL is defined in
 [OData-ABNF](#ODataABNF). Note that the syntax of the context URL is
 independent of whatever URL conventions the service uses for addressing
@@ -2041,11 +2051,12 @@ http://host/service/$metadata
 
 Context URL template:
 
-    {context-url}#{entity-set}
+    {context-url}#{canonical-collection}
     {context-url}#Collection({type-name})
 
-If all entities in the collection are members of one entity set, its
-name is the context URL fragment.
+If all entities in the response or a response part are members of a single
+canonical collection,
+the context URL fragment is the `{canonical-collection}`.
 
 ::: example
 Example 11: resource URL and corresponding context URL
@@ -2055,11 +2066,6 @@ http://host/service/$metadata#Customers
 ```
 :::
 
-If the entities are contained, then `entity-set` is the top-level entity
-set or singleton followed by the canonical path to the containment navigation
-property of the containing entity.
-Key values in that path are represented in canonical form (parentheses-style) without percent-encoding.
-
 ::: example
 Example 12: resource URL and corresponding context URL for contained
 entities
@@ -2069,8 +2075,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 are not members of a single
+canonical collection, such as entities 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.
@@ -2079,25 +2085,22 @@ the type of the returned entity collection.
 
 Context URL template:
 
-    {context-url}#{entity-set}/$entity
+    {context-url}#{canonical-collection}/$entity
     {context-url}#{type-name}
 
-If a response or response part is a single entity of the declared type
-of an entity set, the context URL fragment is the entity set's
-name with `/$entity` appended.
+If a response or response part is an entity within in a canonical collection,
+the context URL fragment is the
+`{canonical-collection}` with `/$entity` appended.
 
 ::: example
-Example 13: resource URL and corresponding context URL
+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
 ```
 :::
 
-If the entity is contained, then `entity-set` is the  top-level entity
-set or singleton followed by the path to the containment navigation
-property of the containing entity.
-
 ::: example
 Example 14: resource URL and corresponding context URL for contained
 entity
@@ -2107,20 +2110,21 @@ http://host/service/$metadata#Orders(4711)/Items/$entity
 ```
 :::
 
-If the entity is not bound to an entity set, such as an entity
+If the entity is within a collection, but a canonical collection
+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 of the returned entity.
+the `{type-name}` of the returned entity.
 
 ## 10.4 Singleton
 
 Context URL template:
 
-    {context-url}#{singleton}
+    {context-url}#{canonical-singleton}
 
-If a response or response part is a singleton, its name is the context
-URL fragment.
+If a response or response part is a canonical singleton, the context
+URL fragment is the `{canonical-singleton}` without `/$entity` appended.
 
 ::: example
 Example 15: resource URL and corresponding context URL
@@ -2130,17 +2134,27 @@ http://host/service/$metadata#MainSupplier
 ```
 :::
 
+::: 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}#{canonical-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 16: resource URL and corresponding context URL
+Example 17: resource URL and corresponding context URL
 ```
 http://host/service/Customers/Model.VipCustomer
 http://host/service/$metadata#Customers/Model.VipCustomer
@@ -2151,28 +2165,38 @@ http://host/service/$metadata#Customers/Model.VipCustomer
 
 Context URL template:
 
-    {context-url}#{entity-set}{/type-name}/$entity
+    {context-url}#{canonical-collection}{/type-name}/$entity
+    {context-url}#{canonical-singleton}{/type-name}
 
-If a response or response part is a single 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 `{canonical-collection}` or `{canonical-singleton}`
+and prior to appending `/$entity`, if any.
 
 ::: example
-Example 17: 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}#{canonical-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
@@ -2207,7 +2231,7 @@ entities in the collection, see system query option
 [`$select`](#SystemQueryOptionselect).
 
 ::: example
-Example 18: 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)
@@ -2218,17 +2242,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}#{singleton}{select-list}
+    {context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+    {context-url}#{canonical-singleton}{/type-name}{select-list}
     {context-url}#{type-name}{select-list}
 
-If a single 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`. 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 `{canonical-collection}` or `{canonical-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
@@ -2260,7 +2283,7 @@ returned entity, see system query option
 [`$select`](#SystemQueryOptionselect).
 
 ::: example
-Example 19: 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
@@ -2271,7 +2294,7 @@ http://host/service/$metadata#Customers(Name,Rating)/$entity
 
 Context URL template:
 
-    {context-url}#{entity-set}{/type-name}{select-list}
+    {context-url}#{canonical-collection}{/type-name}{select-list}
     {context-url}#Collection({type-name}){select-list}
 
 For a 4.01 response, if a navigation property is explicitly expanded,
@@ -2302,7 +2325,7 @@ Navigation properties with expanded references are not represented in
 the context URL.
 
 ::: example
-Example 20: 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
@@ -2311,7 +2334,7 @@ http://host/service/$metadata#Customers(Name,Address/Country())
 :::
 
 ::: example
-Example 21: 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
@@ -2319,7 +2342,7 @@ http://host/service/$metadata#Customers
 :::
 
 ::: example
-Example 22: 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
@@ -2333,8 +2356,8 @@ http://host/service/$metadata
 
 Context URL template:
 
-    {context-url}#{entity-set}{/type-name}{select-list}/$entity
-    {context-url}#{singleton}{select-list}
+    {context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+    {context-url}#{canonical-singleton}{/type-name}{select-list}
     {context-url}#{type-name}{select-list}
 
 For a 4.01 response, if a navigation property is explicitly expanded,
@@ -2362,7 +2385,7 @@ Navigation properties with expanded references are not represented in
 the context URL.
 
 ::: example
-Example 23: 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)
@@ -2381,7 +2404,7 @@ If a response is a collection of entity references, the context URL does
 not contain the type of the referenced entities.
 
 ::: example
-Example 24: 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
@@ -2399,7 +2422,7 @@ If a response is a single entity reference, `$ref` is the context URL
 fragment.
 
 ::: example
-Example 25: 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
@@ -2411,13 +2434,13 @@ http://host/service/$metadata#$ref
 
 Context URL templates:
 
-    {context-url}#{entity}/{property-path}{select-list}
+    {context-url}#{canonical-member}/{property-path}{select-list}
     {context-url}#{type-name}{select-list}
 
 If a response represents an [individual
-property](#RequestingIndividualProperties) 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
+property](#RequestingIndividualProperties) of a canonical member,
+the context URL specifies the `{canonical-member}` and the
+path to the structural property. The path MUST include
 cast segments for properties defined on types derived from the expected
 type of the previous segment.
 
@@ -2426,7 +2449,7 @@ navigation properties or operations, OData 4.01 responses MAY use the
 less specific second template.
 
 ::: example
-Example 26: 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
@@ -2440,12 +2463,12 @@ Context URL template:
     {context-url}#Collection({type-name}){select-list}
 
 If a response is a collection of complex types or primitive types that
-do not represent an individual property of an entity with a canonical
-URL, the context URL specifies the fully qualified type of the
+do not represent an individual property of a canonical member,
+the context URL specifies the fully qualified type of the
 collection.
 
 ::: example
-Example 27: 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)
@@ -2459,11 +2482,11 @@ Context URL template:
     {context-url}#{type-name}{select-list}
 
 If a response is a complex type or primitive type that does not
-represent an individual property of an entity with a canonical URL, the
+represent an individual property of a canonical member, the
 context URL specifies the fully qualified type of the result.
 
 ::: example
-Example 28: resource URL and corresponding context URL
+Example 30: resource URL and corresponding context URL
 ```
 http://host/service/MostPopularName()
 http://host/service/$metadata#Edm.String
@@ -2472,24 +2495,12 @@ http://host/service/$metadata#Edm.String
 
 ## 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}/{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 a single 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 a single 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.
+The context URL in a response from an action or function has one of the formats
+described so far (except the [service document](#ServiceDocument) format).
+It does not mention the name of the invoked action or function.
 
 ::: example
-Example 29: resource URL and corresponding context URL
+Example 31: resource URL and corresponding context URL
 ```
 http://host/service/TopFiveCustomers()
 http://host/service/$metadata#Customers
@@ -2500,9 +2511,9 @@ http://host/service/$metadata#Customers
 
 Context URL template:
 
-    {context-url}#{entity-set}{/type-name}{select-list}/$delta
-    {context-url}#{entity}{select-list}/$delta
-    {context-url}#{entity}/{property-path}{select-list}/$delta
+    {context-url}#{canonical-collection}{/type-name}{select-list}/$delta
+    {context-url}#{canonical-member}{select-list}/$delta
+    {context-url}#{canonical-member}/{property-path}{select-list}/$delta
     #$delta
 
 The context URL of a [delta response](#RequestingChanges) is the context
@@ -2510,12 +2521,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 `{canonical-collection}` is the top-level
 entity set followed by the path to the containment navigation property
 of the containing entity.
 
 ::: example
-Example 30: 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
@@ -2529,14 +2540,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}#{canonical-collection}/$deletedEntity
+    {context-url}#{canonical-collection}/$link
+    {context-url}#{canonical-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. `{canonical-collection}` corresponds to the set of the
 deleted entity, or source entity for an added or deleted link.
 
 ## 10.19 `$all` Response
@@ -2784,7 +2795,7 @@ If the property is not available, for example due to permissions, the
 service responds with [`404 Not Found`](#ResponseCode404NotFound).
 
 ::: example
-Example 31:
+Example 33:
 ```
 GET http://host/service/Products(1)/Name
 ```
@@ -2844,7 +2855,7 @@ If the property or operation result is not available, for example due to permiss
 service responds with [`404 Not Found`](#ResponseCode404NotFound).
 
 ::: example
-Example 32:
+Example 34:
 ```
 GET http://host/service/Products(1)/Name/$value
 ```
@@ -2878,7 +2889,7 @@ schema. Only aliases defined in the metadata document of the service can
 be used in URLs.
 
 ::: example
-Example 33: 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
@@ -2891,7 +2902,7 @@ NOT introduce navigation properties, actions or functions not otherwise
 requested.
 
 ::: example
-Example 34:
+Example 36:
 ```
 GET http://host/service/Products?$select=*
 ```
@@ -2901,7 +2912,7 @@ Properties of related entities can be specified by including the
 `$select` query option within the `$expand`.
 
 ::: example
-Example 35:
+Example 37:
 ```
 GET http://host/service/Products?$expand=Category($select=Name)
 ```
@@ -2915,7 +2926,7 @@ an [`$expand`](#SystemQueryOptionexpand) query option, then it is
 additionally represented as inline content.
 
 ::: example
-Example 36: 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
@@ -2926,7 +2937,7 @@ It is also possible to request all actions or functions available for
 each returned entity.
 
 ::: example
-Example 37:
+Example 39:
 ```
 GET http://host/service/Products?$select=DemoService.*
 ```
@@ -2976,7 +2987,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 38: 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
@@ -2984,7 +2995,7 @@ GET http://host/service.svc/Customers?$expand=Orders
 :::
 
 ::: example
-Example 39: 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
@@ -2992,7 +3003,7 @@ GET http://host/service.svc/Customers?$expand=Orders/$ref
 :::
 
 ::: example
-Example 40: 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
@@ -3020,7 +3031,7 @@ Allowed system query options are
  for collection-valued navigation properties.
 
 ::: example
-Example 41: 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
 ```
@@ -3029,7 +3040,7 @@ GET http://host/service.svc/Customers?$expand=Orders($filter=Amount gt 100)
 :::
 
 ::: example
-Example 42: 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
@@ -3041,7 +3052,7 @@ GET http://host/service.svc/Orders?$expand=Items($expand=Product),Customer
 :::
 
 ::: example
-Example 43: 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
@@ -3071,7 +3082,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 44: 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
 ```
@@ -3091,7 +3102,7 @@ result and MUST be included if `$select` is specified with the computed
 property name, or star (`*`).
 
 ::: example
-Example 45: 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
@@ -3127,7 +3138,7 @@ return [`501 Not Implemented`](#ResponseCode501NotImplemented).
 The `$filter` system query option restricts the set of items returned.
 
 ::: example
-Example 46: 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
 ```
@@ -3138,7 +3149,7 @@ The [`$count`](#SystemQueryOptioncount) segment may be used within a
 count of related entities or items within a collection-valued property.
 
 ::: example
-Example 47: 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
 ```
@@ -3262,7 +3273,7 @@ alias, and the query option value is the value to be used for the
 specified parameter alias.
 
 ::: example
-Example 48: 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'
@@ -3289,7 +3300,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 49: 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
@@ -3336,7 +3347,7 @@ see [OData-VocCore](#ODataVocCore).
 Values of type `Edm.Stream` or any of the `Geo` types cannot be sorted.
 
 ::: example
-Example 50: 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
@@ -3347,7 +3358,7 @@ Related entities may be ordered by specifying `$orderby` within the
 `$expand` clause.
 
 ::: example
-Example 51: 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)
@@ -3359,7 +3370,7 @@ returned items according to the exact count of related entities or items
 within a collection-valued property.
 
 ::: example
-Example 52: 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
@@ -3382,7 +3393,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 53: 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
@@ -3406,7 +3417,7 @@ from the result and all remaining instances are kept in the same order as
 they occur in $A$.
 
 ::: example
-Example 54: 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
@@ -3418,7 +3429,7 @@ Where [`$top`](#SystemQueryOptiontop) and `$skip` are used together,
 they appear in the request.
 
 ::: example
-Example 55: 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
@@ -3436,7 +3447,7 @@ the total count of items within a collection matching the request be
 returned along with the result.
 
 ::: example
-Example 56: 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
@@ -3447,7 +3458,7 @@ The count of related entities can be requested by specifying
 the `$count` query option within the `$expand` clause.
 
 ::: example
-Example 57:
+Example 59:
 ```
 GET http://host/service/Categories?$expand=Products($count=true)
 ```
@@ -3479,7 +3490,7 @@ those items *matching* the specified search expression. The definition
 of what it means to match is dependent upon the implementation.
 
 ::: example
-Example 58: 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
 ```
@@ -3488,7 +3499,7 @@ GET http://host/service/Products?$search=bike
 The search expression can contain phrases, enclosed in double-quotes.
 
 ::: example
-Example 59: 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"
 ```
@@ -3498,7 +3509,7 @@ The upper-case keyword `NOT` restricts the set of entities to those that
 do not match the specified term.
 
 ::: example
-Example 60: 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
 ```
@@ -3509,7 +3520,7 @@ Multiple terms within a search expression are separated by a space
 such terms must be matched.
 
 ::: example
-Example 61: 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
@@ -3520,7 +3531,7 @@ The upper-case keyword `OR` is used to return entities that satisfy
 either the immediately preceding or subsequent expression.
 
 ::: example
-Example 62: 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
@@ -3531,7 +3542,7 @@ Parentheses within the search expression group together multiple
 expressions.
 
 ::: example
-Example 63: 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
@@ -3587,7 +3598,7 @@ Entities are stably addressable using their canonical URL and are not
 accessible using an ordinal index.
 
 ::: example
-Example 64: 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
 ```
@@ -3615,7 +3626,7 @@ entity is related, the service returns
 [`204 No Content`](#ResponseCode204NoContent).
 
 ::: example
-Example 65: 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
@@ -3654,7 +3665,7 @@ exists, the service returns either
 [`404 Not Found`](#ResponseCode404NotFound).
 
 ::: example
-Example 66: 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
@@ -3670,7 +3681,7 @@ the URL `$entity` relative to the service root. The entity-id MUST be
 specified using the system query option `$id`.
 
 ::: example
-Example 67: 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)
 ```
@@ -3687,7 +3698,7 @@ system query options [`$select`](#SystemQueryOptionselect) and
 to the `$entity` resource.
 
 ::: example
-Example 68: 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
@@ -3717,7 +3728,7 @@ SHOULD NOT combine the system query options
 The result of such a request is undefined.
 
 ::: example
-Example 69: 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
 ```
@@ -3728,7 +3739,7 @@ the `/$filter` path segment to count the items in the filtered
 collection.
 
 ::: example
-Example 70: 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
@@ -3740,7 +3751,7 @@ combination with the [`$filter`](#SystemQueryOptionfilter) system query
 option.
 
 ::: example
-Example 71: 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
@@ -3755,14 +3766,14 @@ The `/$count` suffix can also be used in path expressions within system
 query options, e.g. [`$filter`](#SystemQueryOptionfilter).
 
 ::: example
-Example 72: 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 73: 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
 ```
@@ -3785,7 +3796,7 @@ In addition, format-specific abbreviations may be used, e.g. `json` for
 MUST NOT be appended to the format abbreviations.
 
 ::: example
-Example 74: the request
+Example 76: the request
 ```
 GET http://host/service/Orders?$format=application/json;metadata=full
 ```
@@ -3797,7 +3808,7 @@ media type including full metadata, as defined in
 [OData-JSON, section 3.1.2](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadatafullodatametadatafull).
 
 ::: example
-Example 75: the request
+Example 77: the request
 ```
 GET http://host/service/Orders?$format=json
 ```
@@ -4223,7 +4234,7 @@ request body.
 The representation for referencing related entities is format-specific.
 
 ::: example
-Example 76: 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
 
@@ -4244,7 +4255,7 @@ annotation to the `Manager` and `DirectReports` navigation properties
 :::
 
 ::: example
-Example 77: 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
 
@@ -4457,7 +4468,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 78: 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`.
@@ -4507,7 +4518,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 79: 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
@@ -4555,7 +4566,7 @@ nested delta representation to:
 :::
 
 ::: example
-Example 80: 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.
@@ -4882,7 +4893,7 @@ payload unless explicitly requested with [`$expand`](#SystemQueryOptionexpand).
 Instead, the values are generally read or written through URLs.
 
 ::: example
-Example 81: 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
@@ -4913,7 +4924,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 82: 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
@@ -4964,7 +4975,7 @@ attempts to set the property to null and results in an error if the
 property is non-nullable.
 
 ::: example
-Example 83: delete the stream value using the media edit link retrieved in [example 81](#entityWithStreamProperty)
+Example 85: delete the stream value using the media edit link retrieved in [example 83](#entityWithStreamProperty)
 
 ```
 DELETE http://server/uploads/Thumbnail546.jpg
@@ -5118,7 +5129,7 @@ ordinal number indexes from the end of the collection, with -1
 representing an insert as the last item in the collection.
 
 ::: example
-Example 84: 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
@@ -5281,7 +5292,7 @@ semantics described in [Update a Collection of
 Entities](#UpdateaCollectionofEntities) applies.
 
 ::: example
-Example 85: 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'
@@ -5327,7 +5338,7 @@ The request resource path of the collection MAY contain type-cast or
 filter segments to subset the collection.
 
 ::: example
-Example 86: delete all products older than 3
+Example 88: delete all products older than 3
 
 ```
 DELETE /service/Products/$filter(Age gt 3)/$each
@@ -5379,7 +5390,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 87: 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
 
@@ -5390,7 +5401,7 @@ identifies a `SampleModel.Customer`
 :::
 
 ::: example
-Example 88: 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)`
 ```
@@ -5399,7 +5410,7 @@ GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()
 :::
 
 ::: example
-Example 89: 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
 
@@ -5410,7 +5421,7 @@ identifies a collection of entities
 :::
 
 ::: example
-Example 90: 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()
 ```
@@ -5433,7 +5444,7 @@ result type of the bound operation. If the bound operation returns a
 collection, the response is a collection of collections.
 
 ::: example
-Example 91: 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()
@@ -5461,7 +5472,7 @@ or entity collection within the payload. The representation of an action
 or function depends on the [format](#Formats).
 
 ::: example
-Example 92: 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
@@ -5488,7 +5499,7 @@ Services can advertise that a function or action is not available for a
 particular instance by setting its value to null.
 
 ::: example
-Example 93: the `SampleEntities.MostRecentOrder` function is not
+Example 95: the `SampleEntities.MostRecentOrder` function is not
 available for customer `ALFKI`
 ```json
 {
@@ -5572,7 +5583,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 94: 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
@@ -5621,7 +5632,7 @@ Each parameter value is represented as a name/value pair in the format
 and `Value` is the parameter value.
 
 ::: example
-Example 95: 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`
 ```
@@ -5630,7 +5641,7 @@ GET http://host/service/EmployeesByManager(ManagerID=3)
 :::
 
 ::: example
-Example 96: 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?
@@ -5643,7 +5654,7 @@ parameter value. The value for the alias is specified as a separate
 query option using the name of the parameter alias.
 
 ::: example
-Example 97: 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
 ```
@@ -5663,7 +5674,7 @@ optional `$` prefix), the parameter name MUST be prefixed with an at
 (`@`) sign.
 
 ::: example
-Example 98: 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
 ```
@@ -5803,7 +5814,7 @@ collection as a whole is transported in the [`ETag`](#HeaderETag) header of a
 collection response.
 
 ::: example
-Example 99: 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
@@ -5952,7 +5963,7 @@ format](#MultipartBatchFormat) MUST contain a
 [RFC2046](#rfc2046).
 
 ::: example
-Example 100: multipart batch request
+Example 102: multipart batch request
 ```
 POST /service/$batch HTTP/1.1
 Host: odata.org
@@ -5967,7 +5978,7 @@ A batch request using the JSON batch format MUST contain a
 `Content-Type` header specifying a content type of `application/json`.
 
 ::: example
-Example 101: JSON batch request
+Example 103: JSON batch request
 ```
 POST /service/$batch HTTP/1.1
 Host: odata.org
@@ -6022,7 +6033,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 106](#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`,
@@ -6123,7 +6134,7 @@ set can use one of the following three formats:
 - Absolute URI with schema, host, port, and absolute resource path.
 
 ::: example
-Example 102:
+Example 104:
 ```
 GET https://host:1234/path/service/People(1) HTTP/1.1
 ```
@@ -6132,7 +6143,7 @@ GET https://host:1234/path/service/People(1) HTTP/1.1
 - Absolute resource path and separate `Host` header
 
 ::: example
-Example 103:
+Example 105:
 ```json
 PATCH /path/service/People(1) HTTP/1.1
 Host: myserver.mydomain.org:1234
@@ -6145,7 +6156,7 @@ Content-Type: application/json
 - Resource path relative to the batch request URI.
 
 ::: example
-Example 104:
+Example 106:
 ```
 DELETE People(1) HTTP/1.1
 ```
@@ -6170,7 +6181,7 @@ processor may choose to disallow chunked encoding to be used by such
 HTTP requests.
 
 ::: example
-Example 105: 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
@@ -6249,7 +6260,7 @@ which case they SHOULD advertise this support by specifying the
 term applied to the entity container, see [OData-VocCap](#ODataVocCap).
 
 ::: example
-Example 106: 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:
@@ -6321,7 +6332,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 103](#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)`.
 :::
@@ -6329,7 +6340,7 @@ URL, which therefore resolves to `http://host/service/Customers('ALFKI')/Orders(
 #### 11.7.7.3 Referencing an ETag
 
 ::: example
-Example 107: 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`)
@@ -6370,7 +6381,7 @@ If-Match: $1
 #### 11.7.7.4 Referencing Response Body Values
 
 ::: example
-Example 108: 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`)
@@ -6463,11 +6474,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 106](#batchcontentid)).
+URL of the corresponding individual request (see [example 108](#batchcontentid)).
 URLs in responses MUST NOT contain `$`-prefixed request identifiers.
 
 ::: example
-Example 109: referencing the batch request [example 105](#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
 ```
@@ -6543,7 +6554,7 @@ Since a change set is executed atomically,
 a change set.
 
 ::: example
-Example 110: referencing the [example 105](#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 d2356653..5c6d2083 100644
--- a/odata-protocol/10 Context URL.md	
+++ b/odata-protocol/10 Context URL.md	
@@ -21,23 +21,33 @@ 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 or path to a containment navigation property,
-- `{entity}` is the canonical URL for an
-entity,
-- `{singleton}` is the canonical URL for a
-singleton entity,
+resource path to the `$metadata` document.
+- A _canonical collection_ is an entity set [#OData-CSDL#EntitySet]
+or a collection addressed by a containment navigation property
+[#OData-CSDL#ContainmentNavigationProperty].
+We denote by `{canonical-collection}` the canonical URL [#OData-URL#CanonicalURL]
+that addresses a canonical collection relative to the service root.
+- A _canonical singleton_ is a singleton [#OData-CSDL#Singleton]
+or an entity addressed by a single-valued containment
+navigation property.
+We denote by `{canonical-singleton}` the canonical URL
+that addresses a canonical singleton relative to the service root.
+- A _canonical member_ is an entity within a canonical collection.
+We denote by `{canonical-member}` the canonical URL
+that addresses a canonical member relative to the service root.
 - `{select-list}` is an optional
 parenthesized comma-separated list of selected properties, instance
-annotations, functions, and actions,
+annotations, functions, and actions.
 - `{property-path}` is the
-path to a structural property of the entity,
-- `{type-name}` is a qualified type name,
+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 `{canonical-collection}`, `{canonical-singleton}`, and `{canonical-member}` are represented in canonical form
+(parentheses-style) without percent-encoding.
+
 The full grammar for the context URL is defined in
 [OData-ABNF](#ODataABNF). Note that the syntax of the context URL is
 independent of whatever URL conventions the service uses for addressing
@@ -64,11 +74,12 @@ http://host/service/$metadata
 
 Context URL template:
 
-    {context-url}#{entity-set}
+    {context-url}#{canonical-collection}
     {context-url}#Collection({type-name})
 
-If all entities in the collection are members of one entity set, its
-name is the context URL fragment.
+If all entities in the response or a response part are members of a single
+canonical collection,
+the context URL fragment is the `{canonical-collection}`.
 
 ::: example
 Example ##ex: resource URL and corresponding context URL
@@ -78,11 +89,6 @@ http://host/service/$metadata#Customers
 ```
 :::
 
-If the entities are contained, then `entity-set` is the top-level entity
-set or singleton followed by the canonical path to the containment navigation
-property of the containing entity.
-Key values in that path are represented in canonical form (parentheses-style) without percent-encoding.
-
 ::: example
 Example ##ex: resource URL and corresponding context URL for contained
 entities
@@ -92,8 +98,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 are not members of a single
+canonical collection, such as entities 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.
@@ -102,25 +108,22 @@ the type of the returned entity collection.
 
 Context URL template:
 
-    {context-url}#{entity-set}/$entity
+    {context-url}#{canonical-collection}/$entity
     {context-url}#{type-name}
 
-If a response or response part is a single entity of the declared type
-of an entity set, the context URL fragment is the entity set's
-name with `/$entity` appended.
+If a response or response part is an entity within in a canonical collection,
+the context URL fragment is the
+`{canonical-collection}` with `/$entity` appended.
 
 ::: example
-Example ##ex: resource URL and corresponding context URL
+Example ##ex: 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
 ```
 :::
 
-If the entity is contained, then `entity-set` is the  top-level entity
-set or singleton followed by the path to the containment navigation
-property of the containing entity.
-
 ::: example
 Example ##ex: resource URL and corresponding context URL for contained
 entity
@@ -130,20 +133,21 @@ http://host/service/$metadata#Orders(4711)/Items/$entity
 ```
 :::
 
-If the entity is not bound to an entity set, such as an entity
+If the entity is within a collection, but a canonical collection
+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 of the returned entity.
+the `{type-name}` of the returned entity.
 
 ## ##subsec Singleton
 
 Context URL template:
 
-    {context-url}#{singleton}
+    {context-url}#{canonical-singleton}
 
-If a response or response part is a singleton, its name is the context
-URL fragment.
+If a response or response part is a canonical singleton, the context
+URL fragment is the `{canonical-singleton}` without `/$entity` appended.
 
 ::: example
 Example ##ex: resource URL and corresponding context URL
@@ -153,14 +157,24 @@ http://host/service/$metadata#MainSupplier
 ```
 :::
 
+::: 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}#{canonical-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
@@ -174,28 +188,38 @@ http://host/service/$metadata#Customers/Model.VipCustomer
 
 Context URL template:
 
-    {context-url}#{entity-set}{/type-name}/$entity
+    {context-url}#{canonical-collection}{/type-name}/$entity
+    {context-url}#{canonical-singleton}{/type-name}
 
-If a response or response part is a single 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 `{canonical-collection}` or `{canonical-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}#{canonical-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
@@ -241,17 +265,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}#{singleton}{select-list}
+    {context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+    {context-url}#{canonical-singleton}{/type-name}{select-list}
     {context-url}#{type-name}{select-list}
 
-If a single 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`. 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 `{canonical-collection}` or `{canonical-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
@@ -294,7 +317,7 @@ http://host/service/$metadata#Customers(Name,Rating)/$entity
 
 Context URL template:
 
-    {context-url}#{entity-set}{/type-name}{select-list}
+    {context-url}#{canonical-collection}{/type-name}{select-list}
     {context-url}#Collection({type-name}){select-list}
 
 For a 4.01 response, if a navigation property is explicitly expanded,
@@ -356,8 +379,8 @@ http://host/service/$metadata
 
 Context URL template:
 
-    {context-url}#{entity-set}{/type-name}{select-list}/$entity
-    {context-url}#{singleton}{select-list}
+    {context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+    {context-url}#{canonical-singleton}{/type-name}{select-list}
     {context-url}#{type-name}{select-list}
 
 For a 4.01 response, if a navigation property is explicitly expanded,
@@ -434,13 +457,13 @@ http://host/service/$metadata#$ref
 
 Context URL templates:
 
-    {context-url}#{entity}/{property-path}{select-list}
+    {context-url}#{canonical-member}/{property-path}{select-list}
     {context-url}#{type-name}{select-list}
 
 If a response represents an [individual
-property](#RequestingIndividualProperties) 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
+property](#RequestingIndividualProperties) of a canonical member,
+the context URL specifies the `{canonical-member}` and the
+path to the structural property. The path MUST include
 cast segments for properties defined on types derived from the expected
 type of the previous segment.
 
@@ -463,8 +486,8 @@ Context URL template:
     {context-url}#Collection({type-name}){select-list}
 
 If a response is a collection of complex types or primitive types that
-do not represent an individual property of an entity with a canonical
-URL, the context URL specifies the fully qualified type of the
+do not represent an individual property of a canonical member,
+the context URL specifies the fully qualified type of the
 collection.
 
 ::: example
@@ -482,7 +505,7 @@ Context URL template:
     {context-url}#{type-name}{select-list}
 
 If a response is a complex type or primitive type that does not
-represent an individual property of an entity with a canonical URL, the
+represent an individual property of a canonical member, the
 context URL specifies the fully qualified type of the result.
 
 ::: example
@@ -495,21 +518,9 @@ http://host/service/$metadata#Edm.String
 
 ## ##subsec 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}/{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 a single 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 a single 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.
+The context URL in a response from an action or function has one of the formats
+described so far (except the [service document](#ServiceDocument) format).
+It does not mention the name of the invoked action or function.
 
 ::: example
 Example ##ex: resource URL and corresponding context URL
@@ -523,9 +534,9 @@ http://host/service/$metadata#Customers
 
 Context URL template:
 
-    {context-url}#{entity-set}{/type-name}{select-list}/$delta
-    {context-url}#{entity}{select-list}/$delta
-    {context-url}#{entity}/{property-path}{select-list}/$delta
+    {context-url}#{canonical-collection}{/type-name}{select-list}/$delta
+    {context-url}#{canonical-member}{select-list}/$delta
+    {context-url}#{canonical-member}/{property-path}{select-list}/$delta
     #$delta
 
 The context URL of a [delta response](#RequestingChanges) is the context
@@ -533,7 +544,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 `{canonical-collection}` is the top-level
 entity set followed by the path to the containment navigation property
 of the containing entity.
 
@@ -552,14 +563,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}#{canonical-collection}/$deletedEntity
+    {context-url}#{canonical-collection}/$link
+    {context-url}#{canonical-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. `{canonical-collection}` corresponds to the set of the
 deleted entity, or source entity for an added or deleted link.
 
 ## ##subsec `$all` Response
diff --git a/scripts/folding.html b/scripts/folding.html
index 2b925e7b..31ab642c 100644
--- a/scripts/folding.html
+++ b/scripts/folding.html
@@ -3,7 +3,7 @@
     var page = location.href.match(/:\/\/.*?(\/.*?)(#|$)/)[1];
     var folding = JSON.parse(localStorage.getItem(page) || "{}");
     for (var id in folding) {
-      var target = document.getElementById(id).parentElement.parentElement;
+      var target = document.getElementById(id)?.parentElement.parentElement;
       if (target) {
         if (folding[id]) target.removeAttribute("open");
         else target.setAttribute("open", "");

From 8aafe89d81574803e1d36e95485126b9d7b664e7 Mon Sep 17 00:00:00 2001
From: Ralf Handl 
Date: Wed, 20 Nov 2024 18:05:34 +0100
Subject: [PATCH 7/8] Clarify "Expand to the level present in the deep insert
 request" (#2025)

Fixes #363
---
 docs/odata-protocol/odata-protocol.html  | 17 +++++++++++------
 docs/odata-protocol/odata-protocol.md    |  4 ++--
 odata-protocol/1 Introduction.md         |  3 +++
 odata-protocol/11.4 Data Modification.md |  4 ++--
 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
index d6a41cee..dc4c035f 100644
--- a/docs/odata-protocol/odata-protocol.html
+++ b/docs/odata-protocol/odata-protocol.html
@@ -584,31 +584,36 @@ 
        356

      + + + + + - + - + - + - + - + @@ -2374,7 +2379,7 @@
      Section 15.2Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers375
      Section 17 Additional conformance clauses for version 4.02
      Section 15.2Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers375
      Section 17 Additional conformance clauses for version 4.02
      Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) Deep-insert response includes at least the properties present in the request363
      Section 11.4.3 Services can validate non-updatable property values in update payloads 356
      Section 11.4.4 Upserts to single-valued non-containment navigation properties 455
      Section 11.4.9.3 Setting a complex property to a different type 534
      Section 11.4.13 Semantics of continue-on-error when replacing a collection of entities 358
      Section 12 Allow 400 Bad Request in addition to 501 Not Implemented for unsupported functionality 391
      Section 12.3 Encoding of plus character in URLs 485