From 3571d78b20cc9e74fb2dbafd99afb259b8f4a371 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= <heiko.theissen@sap.com>
Date: Wed, 2 Oct 2024 17:52:42 +0200
Subject: [PATCH 01/19] Caution: next links (#2001)
---
docs/odata-json-format/odata-json-format.html | 2 +-
docs/odata-json-format/odata-json-format.md | 4 +++-
docs/odata-protocol/odata-protocol.html | 2 +-
docs/odata-protocol/odata-protocol.md | 3 ++-
odata-json-format/4 Common Characteristics.md | 4 +++-
odata-protocol/11 Data Service Requests.md | 3 ++-
6 files changed, 12 insertions(+), 6 deletions(-)
diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html
index 2b89ccdb..50fe4189 100644
--- a/docs/odata-json-format/odata-json-format.html
+++ b/docs/odata-json-format/odata-json-format.html
@@ -723,7 +723,7 @@ <h3 id="464-control-information-count-odatacount"><a id="ControlInformationcount
<h3 id="465-control-information-nextlink-odatanextlink"><a id="ControlInformationnextLinkodatanextLink" href="#ControlInformationnextLinkodatanextLink">4.6.5 Control Information: <code>nextLink</code> (<code>odata.nextLink</code>)</a></h3>
</summary>
<p>The <code>nextLink</code> control information indicates that a response is only a subset of the requested collection. It contains a <a href="URLsinMessageBodies">URL</a> that allows retrieving the next subset of the requested collection.</p>
-<p>This control information can also be applied to <a href="#ExpandedNavigationProperty">expanded to-many navigation properties</a>.</p>
+<p>This control information can also be applied to <a href="#ExpandedNavigationProperty">expanded to-many navigation properties</a> and to collections of <a href="#CollectionofPrimitiveValues">primitive</a> or <a href="#CollectionofComplexValues">complex</a> values.</p>
</details>
<details open><summary>
<h3 id="466-control-information-delta-odatadelta"><a id="ControlInformationdeltaodatadelta" href="#ControlInformationdeltaodatadelta">4.6.6 Control Information: <code>delta</code> (<code>odata.delta</code>)</a></h3>
diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md
index 2dccc6fe..0dc397f1 100644
--- a/docs/odata-json-format/odata-json-format.md
+++ b/docs/odata-json-format/odata-json-format.md
@@ -923,7 +923,9 @@ is only a subset of the requested collection. It contains a [URL](URLsinMessageB
allows retrieving the next subset of the requested collection.
This control information can also be applied to [expanded to-many
-navigation properties](#ExpandedNavigationProperty).
+navigation properties](#ExpandedNavigationProperty) and to collections of
+[primitive](#CollectionofPrimitiveValues) or [complex](#CollectionofComplexValues)
+values.
### <a id="ControlInformationdeltaodatadelta" href="#ControlInformationdeltaodatadelta">4.6.6 Control Information: `delta` (`odata.delta`)</a>
diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
index 67b5040b..8a009ba1 100644
--- a/docs/odata-protocol/odata-protocol.html
+++ b/docs/odata-protocol/odata-protocol.html
@@ -2100,7 +2100,7 @@ <h4 id="11266-system-query-option-search"><a id="SystemQueryOptionsearch" href="
<details open><summary>
<h4 id="11267-server-driven-paging"><a id="ServerDrivenPaging" href="#ServerDrivenPaging">11.2.6.7 Server-Driven Paging</a></h4>
</summary>
-<p>Responses that include only a partial set of the items identified by the request URL MUST contain a link that allows retrieving the next partial set of items. This link is called a <em>next link</em>; its representation is format-specific. The final partial set of items MUST NOT contain a next link.</p>
+<p>Responses that include only a partial set of the items identified by the request URL MUST contain a link that allows retrieving the next partial set of items. This link is called a <em>next link</em>; its representation is format-specific. The final partial set of items MUST NOT contain a next link. Clients MUST check for next links before assuming to have received all items within a collection, including expanded and nested collections.</p>
<p>The client can request a maximum page size through the <a href="#Preferencemaxpagesizeodatamaxpagesize"><code>maxpagesize</code></a> preference. The service may apply this requested page size or implement a page size different than, or in the absence of, this preference.</p>
<p>OData clients MUST treat the URL of the next link as opaque, and MUST NOT append system query options to the URL of a next link. Services may not allow a change of format on requests for subsequent pages using the next link. Clients therefore SHOULD request the same format on subsequent page requests using a compatible <code>Accept</code> header. OData services may use the reserved system query option <code>$skiptoken</code> when building next links. Its content is opaque, service-specific, and must only follow the rules for URL query parts.</p>
<p>OData clients MUST NOT use the system query option <code>$skiptoken</code> when constructing requests.</p>
diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index 693825de..5f4f6a68 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -3555,7 +3555,8 @@ Responses that include only a partial set of the items identified by the
request URL MUST contain a link that allows retrieving the next partial
set of items. This link is called a *next link*; its representation is
format-specific. The final partial set of items MUST NOT contain a next
-link.
+link. Clients MUST check for next links before assuming to have received
+all items within a collection, including expanded and nested collections.
The client can request a maximum page size through the
[`maxpagesize`](#Preferencemaxpagesizeodatamaxpagesize) preference. The
diff --git a/odata-json-format/4 Common Characteristics.md b/odata-json-format/4 Common Characteristics.md
index 98448833..daa44aa1 100644
--- a/odata-json-format/4 Common Characteristics.md
+++ b/odata-json-format/4 Common Characteristics.md
@@ -376,7 +376,9 @@ is only a subset of the requested collection. It contains a [URL](URLsinMessageB
allows retrieving the next subset of the requested collection.
This control information can also be applied to [expanded to-many
-navigation properties](#ExpandedNavigationProperty).
+navigation properties](#ExpandedNavigationProperty) and to collections of
+[primitive](#CollectionofPrimitiveValues) or [complex](#CollectionofComplexValues)
+values.
### ##subsubsec Control Information: `delta` (`odata.delta`)
diff --git a/odata-protocol/11 Data Service Requests.md b/odata-protocol/11 Data Service Requests.md
index e122e92a..3a5f12d7 100644
--- a/odata-protocol/11 Data Service Requests.md
+++ b/odata-protocol/11 Data Service Requests.md
@@ -993,7 +993,8 @@ Responses that include only a partial set of the items identified by the
request URL MUST contain a link that allows retrieving the next partial
set of items. This link is called a *next link*; its representation is
format-specific. The final partial set of items MUST NOT contain a next
-link.
+link. Clients MUST check for next links before assuming to have received
+all items within a collection, including expanded and nested collections.
The client can request a maximum page size through the
[`maxpagesize`](#Preferencemaxpagesizeodatamaxpagesize) preference. The
From 216dfd987c838180ccb730a06c13c2409be9a589 Mon Sep 17 00:00:00 2001
From: Michael Pizzo <mikep@microsoft.com>
Date: Wed, 2 Oct 2024 09:00:17 -0700
Subject: [PATCH 02/19] Support functions and actions taking/returning delta
payloads (#2005)
---
docs/odata-csdl-json/odata-csdl-json.html | 31 +++++++--
docs/odata-csdl-json/odata-csdl-json.md | 32 ++++++++-
docs/odata-csdl-xml/odata-csdl-xml.html | 27 ++++++--
docs/odata-csdl-xml/odata-csdl-xml.md | 30 +++++++-
docs/odata-protocol/odata-protocol.html | 10 +--
docs/odata-protocol/odata-protocol.md | 10 +--
odata-csdl/1 Introduction.md | 1 +
odata-csdl/12 Action and Function.md | 79 +++++++++++++++-------
odata-csdl/14 Vocabulary and Annotation.md | 2 +-
odata-protocol/10 Context URL.md | 6 +-
package-lock.json | 2 +-
11 files changed, 172 insertions(+), 58 deletions(-)
diff --git a/docs/odata-csdl-json/odata-csdl-json.html b/docs/odata-csdl-json/odata-csdl-json.html
index f5ea66c0..e05c7694 100644
--- a/docs/odata-csdl-json/odata-csdl-json.html
+++ b/docs/odata-csdl-json/odata-csdl-json.html
@@ -459,26 +459,31 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td></td>
</tr>
<tr class="even">
+<td><a href="#ActionandFunction">Section 12</a></td>
+<td>Actions and functions can take, and return, delta payloads</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/348">348</a></td>
+</tr>
+<tr class="odd">
<td><a href="#GeoValues">Section 14.3.13</a></td>
<td>Constant Geo values in annotations</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/654">654</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#StreamValues">Section 14.3.14</a></td>
<td>Constant Stream values in annotations</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/654">654</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#PathEvaluation">Section 14.4.1.2</a></td>
<td>New path evaluation rules for annotations targeting annotations and external targeting via container</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/575">575</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#IfThenElse">Section 14.4.7</a></td>
<td>Nested <code>If</code> without else part in collections</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/326">326</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#Conformance">Section 17</a></td>
<td>Additional conformance clauses for version 4.02</td>
<td></td>
@@ -2010,6 +2015,9 @@ <h3><a id="Nullable.13.7" href="#Nullable.13.7"><code>$Nullable</code></a></h3>
<p>For other collection-valued return types the result will always be a collection that MAY be empty. In this case <code>$Nullable</code> applies to items of the collection and specifies whether the collection MAY contain <code>null</code> values.</p>
<p>For single-valued return types the value <code>true</code> means that the action or function MAY return a single <code>null</code> value. The value <code>false</code> means that the action or function will never return a <code>null</code> value and instead will fail with an error response if it cannot compute a result.</p>
</div>
+<h3><a id="AnnotationCoreIsDelta.13.8" href="#AnnotationCoreIsDelta.13.8">Annotation <code>Core.IsDelta</code></a></h3>
+<p>An action or function that returns a single entity or a collection of entities MAY return results as a delta payload. This is indicated by annotating the return type with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsDelta"><code>Core.IsDelta</code></a>.</p>
+<p>Delta payloads represent changes between two versions of data and, in addition to current values, MAY include deleted entities as well as changes to related entities and relationships, according to the format-specific delta representation.</p>
</details>
<details open><summary>
<h2 id="129-parameter"><a id="Parameter" href="#Parameter">12.9 Parameter</a></h2>
@@ -2021,7 +2029,7 @@ <h2 id="129-parameter"><a id="Parameter" href="#Parameter">12.9 Parameter</a></h
<p>The facets <a href="#MaxLength"><code>MaxLength</code></a>, <a href="#Precision"><code>Precision</code></a>, <a href="#Scale"><code>Scale</code></a>, or <a href="#SRID"><code>SRID</code></a> can be used as appropriate to specify value restrictions of the parameter, as well as the <a href="#Unicode"><code>Unicode</code></a> facet for 4.01 or greater payloads.</p>
<p>For single-valued parameters the facets apply to the parameter value. If the parameter value is a collection, the facets apply to the items in the collection.</p>
<div class="varjson rep">
-<h3><a id="Parameter.13.8" href="#Parameter.13.8"><code>$Parameter</code></a></h3>
+<h3><a id="Parameter.13.9" href="#Parameter.13.9"><code>$Parameter</code></a></h3>
<p>The value of <code>$Parameter</code> is an array. The array contains one object per parameter.</p>
<h3><a id="ParameterObject.14" href="#ParameterObject.14">Parameter Object</a></h3>
<p>A parameter object MUST contain the member <code>$Name</code>, and it MAY contain the members <code>$Type</code>, <code>$Collection</code>, <code>$Nullable</code>, <a href="#MaxLength"><code>$MaxLength</code></a>, <a href="#Unicode"><code>$Unicode</code></a>, <a href="#Precision"><code>$Precision</code></a>, <a href="#Scale"><code>$Scale</code></a>, and <a href="#SRID"><code>$SRID</code></a>.</p>
@@ -2037,6 +2045,9 @@ <h3><a id="Nullable.14.4" href="#Nullable.14.4"><code>$Nullable</code></a></h3>
<p>For single-valued parameters the value <code>true</code> means that the parameter accepts a <code>null</code> value.</p>
<p>For collection-valued parameters the parameter value will always be a collection that MAY be empty. In this case <code>$Nullable</code> applies to items of the collection and specifies whether the collection MAY contain <code>null</code> values.</p>
</div>
+<h3><a id="AnnotationCoreOptionalParameter.14.5" href="#AnnotationCoreOptionalParameter.14.5">Annotation <code>Core.OptionalParameter</code></a></h3>
+<p>A parameter that is annotated with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter"><code>Core.OptionalParameter</code></a> MAY be omitted when invoking the function or action.</p>
+<p>All parameters marked as optional MUST come after any parameters not marked as optional. The binding parameter MUST NOT be marked as optional.</p>
<div class="varjson example">
<p>Example 30: a function returning the top-selling products for a given year. In this case the year must be specified as a parameter of the function with the <code>$Parameter</code> member.</p>
<div class="sourceCode" id="cb30"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><span class="er">"TopSellingProducts":</span> <span class="ot">[</span></span>
@@ -2058,6 +2069,9 @@ <h3><a id="Nullable.14.4" href="#Nullable.14.4"><code>$Nullable</code></a></h3>
<span id="cb30-17"><a href="#cb30-17" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
<span id="cb30-18"><a href="#cb30-18" aria-hidden="true" tabindex="-1"></a><span class="ot">]</span></span></code></pre></div>
</div>
+<h3><a id="AnnotationCoreIsDelta.14.6" href="#AnnotationCoreIsDelta.14.6">Annotation <code>Core.IsDelta</code></a></h3>
+<p>A parameter that accepts a single entity or a collection of entities MAY accept a delta representation. This is indicated by annotating the parameter with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsDelta"><code>Core.IsDelta</code></a>.</p>
+<p>Deltas represent changes between two versions of data and, in addition to current values, MAY include deleted entities as well as changes to related entities and relationships, according to the format-specific delta representation.</p>
</details>
</details>
<hr />
@@ -2501,7 +2515,7 @@ <h3 id="1412-applicability"><a id="Applicability" href="#Applicability">14.1.2 A
</tr>
<tr class="even">
<td><code>Parameter</code></td>
-<td>Action of Function Parameter</td>
+<td>Action or Function Parameter</td>
</tr>
<tr class="odd">
<td><code>Property</code></td>
@@ -4369,7 +4383,8 @@ <h1 id="appendix-b-table-of-json-objects-and-members"><a id="TableofJSONObjectsa
<li><a href="#Type.13.5"><code>$Type</code></a></li>
<li><a href="#Collection.13.6"><code>$Collection</code></a></li>
<li><a href="#Nullable.13.7"><code>$Nullable</code></a></li>
-<li><a href="#Parameter.13.8"><code>$Parameter</code></a></li>
+<li><a href="#AnnotationCoreIsDelta.13.8">Annotation <code>Core.IsDelta</code></a></li>
+<li><a href="#Parameter.13.9"><code>$Parameter</code></a></li>
</ul></li>
<li><a href="#ParameterObject.14">Parameter Object</a>
<ul>
@@ -4377,6 +4392,8 @@ <h1 id="appendix-b-table-of-json-objects-and-members"><a id="TableofJSONObjectsa
<li><a href="#Type.14.2"><code>$Type</code></a></li>
<li><a href="#Collection.14.3"><code>$Collection</code></a></li>
<li><a href="#Nullable.14.4"><code>$Nullable</code></a></li>
+<li><a href="#AnnotationCoreOptionalParameter.14.5">Annotation <code>Core.OptionalParameter</code></a></li>
+<li><a href="#AnnotationCoreIsDelta.14.6">Annotation <code>Core.IsDelta</code></a></li>
</ul></li>
<li><a href="#EntityContainerObject.15">Entity Container Object</a>
<ul>
diff --git a/docs/odata-csdl-json/odata-csdl-json.md b/docs/odata-csdl-json/odata-csdl-json.md
index 17096bae..a4cf256b 100644
--- a/docs/odata-csdl-json/odata-csdl-json.md
+++ b/docs/odata-csdl-json/odata-csdl-json.md
@@ -267,6 +267,7 @@ Section | Feature / Change | Issue
[Section 3.3](#PrimitiveTypes)| Allow stream-valued non-binding parameters| [525](https://github.com/oasis-tcs/odata-specs/issues/525)
[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 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)
@@ -2909,6 +2910,14 @@ fail with an error response if it cannot compute a result.
:::
+### <a id="AnnotationCoreIsDelta.13.8" href="#AnnotationCoreIsDelta.13.8">Annotation `Core.IsDelta`</a>
+
+An action or function that returns a single entity or a collection of entities MAY return results as a delta payload.
+This is indicated by annotating the return type with the term [`Core.IsDelta`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsDelta).
+
+Delta payloads represent changes between two versions of data and, in addition
+to current values, MAY include deleted entities as well as changes to related entities and relationships, according to the format-specific delta representation.
+
## <a id="Parameter" href="#Parameter">12.9 Parameter</a>
An action or function overload MAY specify parameters.
@@ -2934,7 +2943,7 @@ the parameter value is a collection, the facets apply to the items in
the collection.
::: {.varjson .rep}
-### <a id="Parameter.13.8" href="#Parameter.13.8">`$Parameter`</a>
+### <a id="Parameter.13.9" href="#Parameter.13.9">`$Parameter`</a>
The value of `$Parameter` is an array. The array contains one object per
parameter.
@@ -2977,6 +2986,14 @@ of the collection and specifies whether the collection MAY contain
`null` values.
:::
+
+### <a id="AnnotationCoreOptionalParameter.14.5" href="#AnnotationCoreOptionalParameter.14.5">Annotation `Core.OptionalParameter`</a>
+
+A parameter that is annotated with the term [`Core.OptionalParameter`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter) MAY be omitted when invoking the function or action.
+
+All parameters marked as optional MUST come after any parameters not marked as optional.
+The binding parameter MUST NOT be marked as optional.
+
::: {.varjson .example}
Example 30: a function returning the top-selling products for a given
year. In this case the year must be specified as a parameter of the
@@ -3003,7 +3020,13 @@ function with the `$Parameter` member.
```
:::
+### <a id="AnnotationCoreIsDelta.14.6" href="#AnnotationCoreIsDelta.14.6">Annotation `Core.IsDelta`</a>
+
+A parameter that accepts a single entity or a collection of entities MAY accept a delta representation.
+This is indicated by annotating the parameter with the term [`Core.IsDelta`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsDelta).
+Deltas represent changes between two versions of data and, in addition
+to current values, MAY include deleted entities as well as changes to related entities and relationships, according to the format-specific delta representation.
-------
@@ -3719,7 +3742,7 @@ Symbolic Value|Model Element
`NavigationProperty` |Navigation Property
`Null` |Null annotation expression
`OnDelete` |On-Delete Action of a navigation property
-`Parameter` |Action of Function Parameter
+`Parameter` |Action or Function Parameter
`Property` |Structural Property
`PropertyValue` |Property value of a Record annotation expression
`Record` |Record annotation expression
@@ -6215,12 +6238,15 @@ https://openui5.hana.ondemand.com/topic/87aac894a40640f89920d7b2a414499b.
- [`$Type`](#Type.13.5)
- [`$Collection`](#Collection.13.6)
- [`$Nullable`](#Nullable.13.7)
- - [`$Parameter`](#Parameter.13.8)
+ - [Annotation `Core.IsDelta`](#AnnotationCoreIsDelta.13.8)
+ - [`$Parameter`](#Parameter.13.9)
- [Parameter Object](#ParameterObject.14)
- [`$Name`](#Name.14.1)
- [`$Type`](#Type.14.2)
- [`$Collection`](#Collection.14.3)
- [`$Nullable`](#Nullable.14.4)
+ - [Annotation `Core.OptionalParameter`](#AnnotationCoreOptionalParameter.14.5)
+ - [Annotation `Core.IsDelta`](#AnnotationCoreIsDelta.14.6)
- [Entity Container Object](#EntityContainerObject.15)
- [`$Extends`](#Extends.15.1)
- [Entity Set Object](#EntitySetObject.16)
diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html
index da7033c6..14978ace 100644
--- a/docs/odata-csdl-xml/odata-csdl-xml.html
+++ b/docs/odata-csdl-xml/odata-csdl-xml.html
@@ -463,26 +463,31 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/464">464</a></td>
</tr>
<tr class="odd">
+<td><a href="#ActionandFunction">Section 12</a></td>
+<td>Actions and functions can take, and return, delta payloads</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/348">348</a></td>
+</tr>
+<tr class="even">
<td><a href="#GeoValues">Section 14.3.13</a></td>
<td>Constant Geo values in annotations</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/654">654</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#StreamValues">Section 14.3.14</a></td>
<td>Constant Stream values in annotations</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/654">654</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#PathEvaluation">Section 14.4.1.2</a></td>
<td>New path evaluation rules for annotations targeting annotations and external targeting via container</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/575">575</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#IfThenElse">Section 14.4.7</a></td>
<td>Nested <code>If</code> without else part in collections</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/326">326</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#Conformance">Section 17</a></td>
<td>Additional conformance clauses for version 4.02</td>
<td></td>
@@ -1896,6 +1901,9 @@ <h3><a id="AttributeNullable.22.2" href="#AttributeNullable.22.2">Attribute <cod
<p>For other collection-valued return types the result will always be a collection that MAY be empty. In this case the <code>Nullable</code> attribute applies to items of the collection and specifies whether the collection MAY contain <code>null</code> values.</p>
<p>For single-valued return types the value <code>true</code> means that the action or function MAY return a single <code>null</code> value. The value <code>false</code> means that the action or function will never return a <code>null</code> value and instead will fail with an error response if it cannot compute a result.</p>
</div>
+<h3><a id="AnnotationCoreIsDelta.22.3" href="#AnnotationCoreIsDelta.22.3">Annotation <code>Core.IsDelta</code></a></h3>
+<p>An action or function that returns a single entity or a collection of entities MAY return results as a delta payload. This is indicated by annotating the return type with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsDelta"><code>Core.IsDelta</code></a>.</p>
+<p>Delta payloads represent changes between two versions of data and, in addition to current values, MAY include deleted entities as well as changes to related entities and relationships, according to the format-specific delta representation.</p>
</details>
<details open><summary>
<h2 id="129-parameter"><a id="Parameter" href="#Parameter">12.9 Parameter</a></h2>
@@ -1919,6 +1927,9 @@ <h3><a id="AttributeNullable.23.3" href="#AttributeNullable.23.3">Attribute <cod
<p>The value of <code>Nullable</code> is one of the Boolean literals <code>true</code> or <code>false</code>. Absence of the attribute means <code>true</code>.</p>
<p>The value <code>true</code> means that the parameter accepts a <code>null</code> value.</p>
</div>
+<h3><a id="AnnotationCoreOptionalParameter.23.4" href="#AnnotationCoreOptionalParameter.23.4">Annotation <code>Core.OptionalParameter</code></a></h3>
+<p>A parameter that is annotated with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter"><code>Core.OptionalParameter</code></a> MAY be omitted when invoking the function or action.</p>
+<p>All parameters marked as optional MUST come after any parameters not marked as optional. The binding parameter MUST NOT be marked as optional.</p>
<div class="varxml example">
<p>Example 30: a function returning the top-selling products for a given year. In this case the year must be specified as a parameter of the function with the <code>edm:Parameter</code> element.</p>
<div class="sourceCode" id="cb30"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb30-1"><a href="#cb30-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"TopSellingProducts"</span>></span>
@@ -1926,6 +1937,9 @@ <h3><a id="AttributeNullable.23.3" href="#AttributeNullable.23.3">Attribute <cod
<span id="cb30-3"><a href="#cb30-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"Collection(self.Product)"</span> /></span>
<span id="cb30-4"><a href="#cb30-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
</div>
+<h3><a id="AnnotationCoreIsDelta.23.5" href="#AnnotationCoreIsDelta.23.5">Annotation <code>Core.IsDelta</code></a></h3>
+<p>A parameter that accepts a single entity or a collection of entities MAY accept a delta representation. This is indicated by annotating the parameter with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsDelta"><code>Core.IsDelta</code></a>.</p>
+<p>Deltas represent changes between two versions of data and, in addition to current values, MAY include deleted entities as well as changes to related entities and relationships, according to the format-specific delta representation.</p>
</details>
</details>
<hr />
@@ -2318,7 +2332,7 @@ <h3 id="1412-applicability"><a id="Applicability" href="#Applicability">14.1.2 A
</tr>
<tr class="even">
<td><code>Parameter</code></td>
-<td>Action of Function Parameter</td>
+<td>Action or Function Parameter</td>
</tr>
<tr class="odd">
<td><code>Property</code></td>
@@ -4040,12 +4054,15 @@ <h1 id="appendix-b-table-of-xml-elements-and-attributes"><a id="TableofXMLElemen
<ul>
<li><a href="#AttributeType.22.1">Attribute <code>Type</code></a></li>
<li><a href="#AttributeNullable.22.2">Attribute <code>Nullable</code></a></li>
+<li><a href="#AnnotationCoreIsDelta.22.3">Annotation <code>Core.IsDelta</code></a></li>
</ul></li>
<li><a href="#ElementedmParameter.23">Element <code>edm:Parameter</code></a>
<ul>
<li><a href="#AttributeName.23.1">Attribute <code>Name</code></a></li>
<li><a href="#AttributeType.23.2">Attribute <code>Type</code></a></li>
<li><a href="#AttributeNullable.23.3">Attribute <code>Nullable</code></a></li>
+<li><a href="#AnnotationCoreOptionalParameter.23.4">Annotation <code>Core.OptionalParameter</code></a></li>
+<li><a href="#AnnotationCoreIsDelta.23.5">Annotation <code>Core.IsDelta</code></a></li>
</ul></li>
<li><a href="#ElementedmEntityContainer.24">Element <code>edm:EntityContainer</code></a>
<ul>
diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md
index fcca80a1..1e4fa24a 100644
--- a/docs/odata-csdl-xml/odata-csdl-xml.md
+++ b/docs/odata-csdl-xml/odata-csdl-xml.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](#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 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)
@@ -2785,6 +2786,14 @@ the action or function will never return a `null` value and instead will
fail with an error response if it cannot compute a result.
:::
+### <a id="AnnotationCoreIsDelta.22.3" href="#AnnotationCoreIsDelta.22.3">Annotation `Core.IsDelta`</a>
+
+An action or function that returns a single entity or a collection of entities MAY return results as a delta payload.
+This is indicated by annotating the return type with the term [`Core.IsDelta`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsDelta).
+
+Delta payloads represent changes between two versions of data and, in addition
+to current values, MAY include deleted entities as well as changes to related entities and relationships, according to the format-specific delta representation.
+
## <a id="Parameter" href="#Parameter">12.9 Parameter</a>
An action or function overload MAY specify parameters.
@@ -2810,7 +2819,6 @@ the parameter value is a collection, the facets apply to the items in
the collection.
-
::: {.varxml .rep}
### <a id="ElementedmParameter.23" href="#ElementedmParameter.23">Element `edm:Parameter`</a>
@@ -2842,6 +2850,13 @@ The value of `Nullable` is one of the Boolean literals `true` or
The value `true` means that the parameter accepts a `null` value.
:::
+### <a id="AnnotationCoreOptionalParameter.23.4" href="#AnnotationCoreOptionalParameter.23.4">Annotation `Core.OptionalParameter`</a>
+
+A parameter that is annotated with the term [`Core.OptionalParameter`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter) MAY be omitted when invoking the function or action.
+
+All parameters marked as optional MUST come after any parameters not marked as optional.
+The binding parameter MUST NOT be marked as optional.
+
::: {.varxml .example}
Example 30: a function returning the top-selling products for a given
year. In this case the year must be specified as a parameter of the
@@ -2854,6 +2869,14 @@ function with the `edm:Parameter` element.
```
:::
+### <a id="AnnotationCoreIsDelta.23.5" href="#AnnotationCoreIsDelta.23.5">Annotation `Core.IsDelta`</a>
+
+A parameter that accepts a single entity or a collection of entities MAY accept a delta representation.
+This is indicated by annotating the parameter with the term [`Core.IsDelta`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsDelta).
+
+Deltas represent changes between two versions of data and, in addition
+to current values, MAY include deleted entities as well as changes to related entities and relationships, according to the format-specific delta representation.
+
-------
@@ -3524,7 +3547,7 @@ Symbolic Value|Model Element
`NavigationProperty` |Navigation Property
`Null` |Null annotation expression
`OnDelete` |On-Delete Action of a navigation property
-`Parameter` |Action of Function Parameter
+`Parameter` |Action or Function Parameter
`Property` |Structural Property
`PropertyValue` |Property value of a Record annotation expression
`Record` |Record annotation expression
@@ -5920,10 +5943,13 @@ https://www.ogc.org/standard/sfa/.
- [Element `edm:ReturnType`](#ElementedmReturnType.22)
- [Attribute `Type`](#AttributeType.22.1)
- [Attribute `Nullable`](#AttributeNullable.22.2)
+ - [Annotation `Core.IsDelta`](#AnnotationCoreIsDelta.22.3)
- [Element `edm:Parameter`](#ElementedmParameter.23)
- [Attribute `Name`](#AttributeName.23.1)
- [Attribute `Type`](#AttributeType.23.2)
- [Attribute `Nullable`](#AttributeNullable.23.3)
+ - [Annotation `Core.OptionalParameter`](#AnnotationCoreOptionalParameter.23.4)
+ - [Annotation `Core.IsDelta`](#AnnotationCoreIsDelta.23.5)
- [Element `edm:EntityContainer`](#ElementedmEntityContainer.24)
- [Attribute `Name`](#AttributeName.24.1)
- [Attribute `Extends`](#AttributeExtends.24.2)
diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
index 8a009ba1..a10076a8 100644
--- a/docs/odata-protocol/odata-protocol.html
+++ b/docs/odata-protocol/odata-protocol.html
@@ -345,8 +345,8 @@ <h1 id="table-of-contents">Table of Contents</h1>
<li><a href="#CollectionofComplexorPrimitiveTypes">10.14 Collection of Complex or Primitive Types</a></li>
<li><a href="#ComplexorPrimitiveType">10.15 Complex or Primitive Type</a></li>
<li><a href="#OperationResult">10.16 Operation Result</a></li>
-<li><a href="#DeltaPayloadResponse">10.17 Delta Payload Response</a></li>
-<li><a href="#IteminaDeltaPayloadResponse">10.18 Item in a Delta Payload Response</a></li>
+<li><a href="#DeltaPayload">10.17 Delta Payload</a></li>
+<li><a href="#IteminaDeltaPayload">10.18 Item in a Delta Payload</a></li>
<li><a href="#allResponse">10.19 <code>$all</code> Response</a></li>
<li><a href="#crossjoinResponse">10.20 <code>$crossjoin</code> Response</a></li>
</ul></li>
@@ -1563,7 +1563,7 @@ <h2 id="1016-operation-result"><a id="OperationResult" href="#OperationResult">1
</div>
</details>
<details open><summary>
-<h2 id="1017-delta-payload-response"><a id="DeltaPayloadResponse" href="#DeltaPayloadResponse">10.17 Delta Payload Response</a></h2>
+<h2 id="1017-delta-payload"><a id="DeltaPayload" href="#DeltaPayload">10.17 Delta Payload</a></h2>
</summary>
<p>Context URL template:</p>
<pre><code>{context-url}#{entity-set}{/type-name}{select-list}/$delta
@@ -1577,10 +1577,10 @@ <h2 id="1017-delta-payload-response"><a id="DeltaPayloadResponse" href="#DeltaPa
<pre><code>http://host/service/Customers?$deltatoken=1234
http://host/service/$metadata#Customers/$delta</code></pre>
</div>
-<p>The context URL of an update request body for a collection of entities is simply the fragment <code>#$delta</code>.</p>
+<p>The context URL of an <a href="#UpdateaCollectionofEntities">update request body for a collection of entities</a> is simply the fragment <code>#$delta</code>.</p>
</details>
<details open><summary>
-<h2 id="1018-item-in-a-delta-payload-response"><a id="IteminaDeltaPayloadResponse" href="#IteminaDeltaPayloadResponse">10.18 Item in a Delta Payload Response</a></h2>
+<h2 id="1018-item-in-a-delta-payload"><a id="IteminaDeltaPayload" href="#IteminaDeltaPayload">10.18 Item in a Delta Payload</a></h2>
</summary>
<p>Context URL templates:</p>
<pre><code>{context-url}#{entity-set}/$deletedEntity
diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index 5f4f6a68..c4616c91 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -195,8 +195,8 @@ For complete copyright information please see the full Notices section in an App
- [10.14 Collection of Complex or Primitive Types](#CollectionofComplexorPrimitiveTypes)
- [10.15 Complex or Primitive Type](#ComplexorPrimitiveType)
- [10.16 Operation Result](#OperationResult)
- - [10.17 Delta Payload Response](#DeltaPayloadResponse)
- - [10.18 Item in a Delta Payload Response](#IteminaDeltaPayloadResponse)
+ - [10.17 Delta Payload](#DeltaPayload)
+ - [10.18 Item in a Delta Payload](#IteminaDeltaPayload)
- [10.19 `$all` Response](#allResponse)
- [10.20 `$crossjoin` Response](#crossjoinResponse)
- [11 Data Service Requests](#DataServiceRequests)
@@ -2496,7 +2496,7 @@ http://host/service/$metadata#Customers
```
:::
-## <a id="DeltaPayloadResponse" href="#DeltaPayloadResponse">10.17 Delta Payload Response</a>
+## <a id="DeltaPayload" href="#DeltaPayload">10.17 Delta Payload</a>
Context URL template:
@@ -2522,10 +2522,10 @@ http://host/service/$metadata#Customers/$delta
```
:::
-The context URL of an update request body for a collection of entities
+The context URL of an [update request body for a collection of entities](#UpdateaCollectionofEntities)
is simply the fragment `#$delta`.
-## <a id="IteminaDeltaPayloadResponse" href="#IteminaDeltaPayloadResponse">10.18 Item in a Delta Payload Response</a>
+## <a id="IteminaDeltaPayload" href="#IteminaDeltaPayload">10.18 Item in a Delta Payload</a>
Context URL templates:
diff --git a/odata-csdl/1 Introduction.md b/odata-csdl/1 Introduction.md
index 385a4ae0..9bdb1481 100644
--- a/odata-csdl/1 Introduction.md
+++ b/odata-csdl/1 Introduction.md
@@ -46,6 +46,7 @@ SRID value `variable` is deprecated|
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 ##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 99c0b3ac..deea8a82 100644
--- a/odata-csdl/12 Action and Function.md
+++ b/odata-csdl/12 Action and Function.md
@@ -328,6 +328,15 @@ the action or function will never return a `null` value and instead will
fail with an error response if it cannot compute a result.
:::
+### ##subisec Annotation `Core.IsDelta`
+
+An action or function that returns a single entity or a collection of entities MAY return results as a delta payload.
+This is indicated by annotating the return type with the term [`Core.IsDelta`]($$$OData-VocCore$$$#IsDelta).
+
+Delta payloads represent changes between two versions of data and, in addition
+to current values, MAY include deleted entities as well as changes to related
+entities and relationships, according to the format-specific delta representation.
+
## ##subsec Parameter
An action or function overload MAY specify parameters.
@@ -397,32 +406,6 @@ of the collection and specifies whether the collection MAY contain
`null` values.
:::
-::: {.varjson .example}
-Example ##ex: a function returning the top-selling products for a given
-year. In this case the year must be specified as a parameter of the
-function with the `$Parameter` member.
-```json
-"TopSellingProducts": [
- {
- "$Kind": "Function",
- "$Parameter": [
- {
- "$Name": "Year",
- "$Nullable": true,
- "$Type": "Edm.Decimal",
- "$Precision": 4,
- "$Scale": 0
- }
- ],
- "$ReturnType": {
- "$Collection": true,
- "$Type": "self.Product"
- }
- }
-]
-```
-:::
-
::: {.varxml .rep}
### ##isec Element `edm:Parameter`
@@ -454,6 +437,41 @@ The value of `Nullable` is one of the Boolean literals `true` or
The value `true` means that the parameter accepts a `null` value.
:::
+### ##subisec Annotation `Core.OptionalParameter`
+
+A parameter that is annotated with the term
+[`Core.OptionalParameter`]($$$OData-VocCore$$$#OptionalParameter) MAY be
+omitted when invoking the function or action.
+
+All parameters marked as optional MUST come after any parameters not marked as optional.
+
+The binding parameter MUST NOT be marked as optional.
+
+::: {.varjson .example}
+Example ##ex: a function returning the top-selling products for a given
+year. In this case the year must be specified as a parameter of the
+function with the `$Parameter` member.
+```json
+"TopSellingProducts": [
+ {
+ "$Kind": "Function",
+ "$Parameter": [
+ {
+ "$Name": "Year",
+ "$Nullable": true,
+ "$Type": "Edm.Decimal",
+ "$Precision": 4,
+ "$Scale": 0
+ }
+ ],
+ "$ReturnType": {
+ "$Collection": true,
+ "$Type": "self.Product"
+ }
+ }
+]
+```
+:::
::: {.varxml .example}
Example ##ex: a function returning the top-selling products for a given
year. In this case the year must be specified as a parameter of the
@@ -465,3 +483,12 @@ function with the `edm:Parameter` element.
</Function>
```
:::
+
+### ##subisec Annotation `Core.IsDelta`
+
+A parameter that accepts a single entity or a collection of entities MAY accept a delta representation.
+This is indicated by annotating the parameter with the term [`Core.IsDelta`]($$$OData-VocCore$$$#IsDelta).
+
+Deltas represent changes between two versions of data and, in addition
+to current values, MAY include deleted entities as well as changes to related
+entities and relationships, according to the format-specific delta representation.
diff --git a/odata-csdl/14 Vocabulary and Annotation.md b/odata-csdl/14 Vocabulary and Annotation.md
index c55ed3bc..73801ec6 100644
--- a/odata-csdl/14 Vocabulary and Annotation.md
+++ b/odata-csdl/14 Vocabulary and Annotation.md
@@ -324,7 +324,7 @@ Symbolic Value|Model Element
`NavigationProperty` |Navigation Property
`Null` |Null annotation expression
`OnDelete` |On-Delete Action of a navigation property
-`Parameter` |Action of Function Parameter
+`Parameter` |Action or Function Parameter
`Property` |Structural Property
`PropertyValue` |Property value of a Record annotation expression
`Record` |Record annotation expression
diff --git a/odata-protocol/10 Context URL.md b/odata-protocol/10 Context URL.md
index 890a0606..5ad8ce5a 100644
--- a/odata-protocol/10 Context URL.md
+++ b/odata-protocol/10 Context URL.md
@@ -519,7 +519,7 @@ http://host/service/$metadata#Customers
```
:::
-## ##subsec Delta Payload Response
+## ##subsec Delta Payload
Context URL template:
@@ -545,10 +545,10 @@ http://host/service/$metadata#Customers/$delta
```
:::
-The context URL of an update request body for a collection of entities
+The context URL of an [update request body for a collection of entities](#UpdateaCollectionofEntities)
is simply the fragment `#$delta`.
-## ##subsec Item in a Delta Payload Response
+## ##subsec Item in a Delta Payload
Context URL templates:
diff --git a/package-lock.json b/package-lock.json
index e8591d31..643ad09a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -3101,7 +3101,7 @@
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-1.0.2.tgz",
"integrity": "sha512-TPJXq8JqFaVYm2CWmPvnP2Iyo4ZSM7/QKcSmuMLDObfpH5fi7RUGmd/rTDf+rut/saiDiQEeVTNgAmJEdAOx0w==",
- "license": "MIT",
+ "license": "MIT",
"engines": {
"node": ">= 0.8"
}
From a3999735d2e15c46d6a73bd5e54339b14d8c6cc8 Mon Sep 17 00:00:00 2001
From: Ralf Handl <ralf.handl@sap.com>
Date: Wed, 2 Oct 2024 18:03:53 +0200
Subject: [PATCH 03/19] No duplicate nested query options in $expand (#2008)
Fixes #2004
---
docs/odata-url-conventions/odata-url-conventions.html | 7 ++++++-
docs/odata-url-conventions/odata-url-conventions.md | 3 +++
odata-url-conventions/1 Introduction.md | 3 +++
odata-url-conventions/5 Query Options.md | 2 ++
4 files changed, 14 insertions(+), 1 deletion(-)
diff --git a/docs/odata-url-conventions/odata-url-conventions.html b/docs/odata-url-conventions/odata-url-conventions.html
index a18a9242..12226e4d 100644
--- a/docs/odata-url-conventions/odata-url-conventions.html
+++ b/docs/odata-url-conventions/odata-url-conventions.html
@@ -441,6 +441,11 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/441">441</a></td>
</tr>
<tr class="odd">
+<td><a href="#SystemQueryOptionexpand">Section 5.1.3</a></td>
+<td>Nested query options can only appear once per expand item</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/2004">2004</a></td>
+</tr>
+<tr class="even">
<td><a href="#SystemQueryOptionsearch">Section 5.1.8</a></td>
<td>Allow alternative <code>$search</code> syntax</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/293">293</a></td>
@@ -2259,7 +2264,7 @@ <h3 id="513-system-query-option-expand"><a id="SystemQueryOptionexpand" href="#S
<pre><code>http://host/service/Customers?$expand=Addresses/Country</code></pre>
</div>
<p>A path MUST NOT appear in more than one expand item.</p>
-<p>Query options can be applied to an expanded navigation property by appending a semicolon-separated list of query options, enclosed in parentheses, to the navigation property name. Allowed system query options are <a href="#SystemQueryOptioncompute"><code>$compute</code></a>, <a href="#SystemQueryOptionselect"><code>$select</code></a>, <code>$expand</code>, and <a href="#ExpandOptionlevels"><code>$levels</code></a> for all navigation properties, plus <a href="#SystemQueryOptionfilter"><code>$filter</code></a>, <a href="#SystemQueryOptionorderby"><code>$orderby</code></a>, <a href="#SystemQueryOptionstopandskip"><code>$skip</code></a>, <a href="#SystemQueryOptionstopandskip"><code>$top</code></a>, <a href="#SystemQueryOptioncount"><code>$count</code></a>, and <a href="#SystemQueryOptionsearch"><code>$search</code></a> for collection-valued navigation properties.</p>
+<p>Query options can be applied to an expanded navigation property by appending a semicolon-separated list of query options, enclosed in parentheses, to the navigation property name. The system query option, irrespective of casing or whether or not it is prefixed with a <code>$</code>, MUST NOT be specified more than once in the list. Allowed system query options are <a href="#SystemQueryOptioncompute"><code>$compute</code></a>, <a href="#SystemQueryOptionselect"><code>$select</code></a>, <code>$expand</code>, and <a href="#ExpandOptionlevels"><code>$levels</code></a> for all navigation properties, plus <a href="#SystemQueryOptionfilter"><code>$filter</code></a>, <a href="#SystemQueryOptionorderby"><code>$orderby</code></a>, <a href="#SystemQueryOptionstopandskip"><code>$skip</code></a>, <a href="#SystemQueryOptionstopandskip"><code>$top</code></a>, <a href="#SystemQueryOptioncount"><code>$count</code></a>, and <a href="#SystemQueryOptionsearch"><code>$search</code></a> for collection-valued navigation properties.</p>
<div class="example">
<p>Example 124: all categories and for each category all related products with a discontinued date equal to <code>null</code></p>
<pre><code>http://host/service/Categories?$expand=Products($filter=DiscontinuedDate eq null)</code></pre>
diff --git a/docs/odata-url-conventions/odata-url-conventions.md b/docs/odata-url-conventions/odata-url-conventions.md
index 96ce04c2..7bb811cc 100644
--- a/docs/odata-url-conventions/odata-url-conventions.md
+++ b/docs/odata-url-conventions/odata-url-conventions.md
@@ -272,6 +272,7 @@ Section | Feature / Change | Issue
--------|------------------|------
[Section 4.17](#PassingQueryOptionsintheRequestBody)| `POST ~/$query` with `Content-Type: application/x-www-form-urlencoded` or `application/json`| [320](https://github.com/oasis-tcs/odata-specs/issues/320), [371](https://github.com/oasis-tcs/odata-specs/issues/371)
[Section 5.1.1.7.1](#matchespattern)| New overload for function `matchespattern` with flags| [441](https://github.com/oasis-tcs/odata-specs/issues/441)
+[Section 5.1.3](#SystemQueryOptionexpand)| Nested query options can only appear once per expand item| [2004](https://github.com/oasis-tcs/odata-specs/issues/2004)
[Section 5.1.8](#SystemQueryOptionsearch)| Allow alternative `$search` syntax| [293](https://github.com/oasis-tcs/odata-specs/issues/293)
## <a id="Glossary" href="#Glossary">1.2 Glossary</a>
@@ -3623,6 +3624,8 @@ A path MUST NOT appear in more than one expand item.
Query options can be applied to an expanded navigation property by
appending a semicolon-separated list of query options, enclosed in
parentheses, to the navigation property name.
+The system query option, irrespective of casing or whether or not it is prefixed with a `$`,
+MUST NOT be specified more than once in the list.
Allowed system query options are
[`$compute`](#SystemQueryOptioncompute),
[`$select`](#SystemQueryOptionselect),
diff --git a/odata-url-conventions/1 Introduction.md b/odata-url-conventions/1 Introduction.md
index e759d0a4..5a141e69 100644
--- a/odata-url-conventions/1 Introduction.md
+++ b/odata-url-conventions/1 Introduction.md
@@ -32,6 +32,9 @@ Section | Feature / Change | Issue
[Section ##matchespattern]|
New overload for function `matchespattern` with flags|
[441](https://github.com/oasis-tcs/odata-specs/issues/441)
+[Section ##SystemQueryOptionexpand]|
+Nested query options can only appear once per expand item|
+[2004](https://github.com/oasis-tcs/odata-specs/issues/2004)
[Section ##SystemQueryOptionsearch]|
Allow alternative `$search` syntax|
[293](https://github.com/oasis-tcs/odata-specs/issues/293)
diff --git a/odata-url-conventions/5 Query Options.md b/odata-url-conventions/5 Query Options.md
index 42354e58..4222a8dc 100644
--- a/odata-url-conventions/5 Query Options.md
+++ b/odata-url-conventions/5 Query Options.md
@@ -2050,6 +2050,8 @@ A path MUST NOT appear in more than one expand item.
Query options can be applied to an expanded navigation property by
appending a semicolon-separated list of query options, enclosed in
parentheses, to the navigation property name.
+The system query option, irrespective of casing or whether or not it is prefixed with a `$`,
+MUST NOT be specified more than once in the list.
Allowed system query options are
[`$compute`](#SystemQueryOptioncompute),
[`$select`](#SystemQueryOptionselect),
From c92ca2be67a0a9efbb4031563fc3226ab3ee53ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= <heiko.theissen@sap.com>
Date: Tue, 15 Oct 2024 13:57:56 +0200
Subject: [PATCH 04/19] Superfluous `[` (#2012)
---
docs/odata-protocol/odata-protocol.html | 2 +-
docs/odata-protocol/odata-protocol.md | 2 +-
odata-protocol/11 Data Service Requests.md | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
index a10076a8..6c3877f7 100644
--- a/docs/odata-protocol/odata-protocol.html
+++ b/docs/odata-protocol/odata-protocol.html
@@ -1788,7 +1788,7 @@ <h4 id="11251-system-query-option-select"><a id="SystemQueryOptionselect" href="
<pre><code>GET http://host/service/Products?$select=DemoService.*</code></pre>
</div>
<p>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 <a href="#SystemQueryOptionselect"><code>$select</code></a> and <a href="#SystemQueryOptioncompute"><code>$compute</code></a> for complex properties, plus <a href="#SystemQueryOptionfilter"><code>$filter</code></a>, <a href="#SystemQueryOptionsearch"><code>$search</code></a>, <a href="#SystemQueryOptioncount"><code>$count</code></a>, <a href="#SystemQueryOptionorderby"><code>$orderby</code></a>, <a href="#SystemQueryOptionskip"><code>$skip</code></a>, and <a href="#SystemQueryOptiontop"><code>$top</code></a> 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.</p>
-<p>If the <code>$select</code> query option is not specified, [the service returns the full set of properties or a default set of properties. The default set of properties MUST include all key properties. Services may change the default set of properties returned. This includes returning new properties by default and omitting properties previously returned by default. Clients that rely on specific properties in the response MUST use <code>$select</code> with the required properties or with <code>*</code>.</p>
+<p>If the <code>$select</code> query option is not specified, the service returns the full set of properties or a default set of properties. The default set of properties MUST include all key properties. Services may change the default set of properties returned. This includes returning new properties by default and omitting properties previously returned by default. Clients that rely on specific properties in the response MUST use <code>$select</code> with the required properties or with <code>*</code>.</p>
<p>If the service returns less than the full set of properties, either because the client specified a select or because the service returned a subset of properties in the absence of a select, the <a href="#ContextURL">context URL</a> MUST reflect the set of selected properties and projected <a href="#SystemQueryOptionexpand">expanded</a> navigation properties.</p>
</details>
<details open><summary>
diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index c4616c91..b1d81e3b 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -2946,7 +2946,7 @@ 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.
-If the `$select` query option is not specified, [the service returns
+If the `$select` query option is not specified, the service returns
the full set of properties or a default set of properties. The default
set of properties MUST include all key properties.
Services may change the default set of properties returned. This
diff --git a/odata-protocol/11 Data Service Requests.md b/odata-protocol/11 Data Service Requests.md
index 3a5f12d7..1af41135 100644
--- a/odata-protocol/11 Data Service Requests.md
+++ b/odata-protocol/11 Data Service Requests.md
@@ -384,7 +384,7 @@ 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.
-If the `$select` query option is not specified, [the service returns
+If the `$select` query option is not specified, the service returns
the full set of properties or a default set of properties. The default
set of properties MUST include all key properties.
Services may change the default set of properties returned. This
From c54ac7fe53a67716581688ce6b08e7d980ac6eff Mon Sep 17 00:00:00 2001
From: Michael Pizzo <mikep@microsoft.com>
Date: Wed, 16 Oct 2024 08:29:32 -0700
Subject: [PATCH 05/19] Clarify ordering constraints of deleted entity in JSON
payload (#2013)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Fixes #1985
---------
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
Co-authored-by: Heiko Theißen <heiko.theissen@sap.com>
---
docs/odata-json-format/odata-json-format.html | 14 ++++++++------
docs/odata-json-format/odata-json-format.md | 19 +++++++------------
odata-json-format/1 Introduction.md | 3 +++
odata-json-format/15 Delta Payload.md | 17 +++++------------
odata-json-format/4 Common Characteristics.md | 2 ++
5 files changed, 25 insertions(+), 30 deletions(-)
diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html
index 50fe4189..f1e59154 100644
--- a/docs/odata-json-format/odata-json-format.html
+++ b/docs/odata-json-format/odata-json-format.html
@@ -399,12 +399,13 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/456">456</a></td>
</tr>
<tr class="odd">
-<td><a href="#ActionInvocation">Section 18</a></td>
-<td>Allow common expressions in action payloads</td>
-<td><a href="https://github.com/oasis-tcs/odata-specs/issues/341">341</a></td>
+<td><a href="#DeletedEntity">Section 15.3</a></td>
+<td><code>type</code> control information, if present, must come immediately after <code>removed</code></td>
+<td></td>
</tr>
</tbody>
</table>
+<p><a href="https://github.com/oasis-tcs/odata-specs/issues/1985">1985</a> <a href="#ActionInvocation">Section 18</a>| Allow common expressions in action payloads| <a href="https://github.com/oasis-tcs/odata-specs/issues/341">341</a></p>
</details>
<details open><summary>
<h2 id="12-glossary"><a id="Glossary" href="#Glossary">1.2 Glossary</a></h2>
@@ -634,6 +635,7 @@ <h2 id="45-payload-ordering-constraints"><a id="PayloadOrderingConstraints" href
<p>To support streaming scenarios the following payload ordering constraints have to be met:</p>
<ul>
<li>If present, the <code>context</code> control information MUST be the first property in the JSON object.</li>
+<li>For 4.01 deleted entities, the <code>removed</code> control information MUST appear after <code>context</code>, if present, and before any other property or control information.</li>
<li>The <code>type</code> control information, if present, MUST appear next in the JSON object.</li>
<li>The <code>id</code> and <code>etag</code> control information MUST appear before any property, property annotation, or property control information.</li>
<li>All annotations or control information for a structural or navigation property MUST appear as a group immediately before the property itself. The one exception is the <a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a> of a collection which MAY appear after the collection it annotates.</li>
@@ -1474,10 +1476,10 @@ <h2 id="153-deleted-entity"><a id="DeletedEntity" href="#DeletedEntity">15.3 Del
<span id="cb38-4"><a href="#cb38-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"id"</span><span class="fu">:</span> <span class="st">"Customers('ANTON')"</span></span>
<span id="cb38-5"><a href="#cb38-5" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
-<p>In OData 4.01 payloads the deleted-entity object MUST include the following properties, regardless of the specified <a href="#ControllingtheAmountofControlInformationinResponses"><code>metadata</code></a> value:</p>
+<p>In OData 4.01 payloads the deleted-entity object MUST include the following properties, regardless of the specified <a href="#ControllingtheAmountofControlInformationinResponses"><code>metadata</code></a> value. For ordered payloads, this control information MUST follow the <a href="#PayloadOrderingConstraints">payload ordering constraints</a>.</p>
<ul>
-<li><p>Control information <a href="#ControlInformationremovedodataremoved"><code>removed</code></a>, whose value is an object that MAY contain a property named <code>reason</code>. If present, the value of <code>reason</code> MUST be either <code>deleted</code> if the entity was deleted (destroyed), or <code>changed</code> 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 <a href="#InstanceAnnotations">annotations</a>, and clients SHOULD NOT error due to the presence of additional properties that MAY be defined by future versions of this specification. For <a href="#PayloadOrderingConstraints">ordered payloads</a>, the control information <a href="#ControlInformationremovedodataremoved"><code>removed</code></a> MUST immediately follow the <a href="#ControlInformationcontextodatacontext"><code>context</code></a> control information, if present, otherwise it MUST be the first property in the deleted entity.</p></li>
-<li><p>Control information <a href="#ControlInformationidodataid"><code>id</code></a> or all of the entity’s primary key fields. The <code>id</code> control information MUST appear if any of the entity’s primary key fields are omitted from the response <em>or</em> the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an <a href="#UpdateaCollectionofEntities">update request</a>, an <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys">alternate key</a> (see <em>Alternate Keys</em> in <a href="#ODataURL">OData-URL</a>) 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 <code>id</code> control information and other primary key fields. For <a href="#PayloadOrderingConstraints">ordered payloads</a>, the control information <code>id</code>, if present, MUST immediately follow the control information <a href="#ControlInformationremovedodataremoved"><code>removed</code></a>.</p></li>
+<li><p>Control information <a href="#ControlInformationremovedodataremoved"><code>removed</code></a>, whose value is an object that MAY contain a property named <code>reason</code>. If present, the value of <code>reason</code> MUST be either <code>deleted</code> if the entity was deleted (destroyed), or <code>changed</code> 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 <a href="#InstanceAnnotations">annotations</a>, and clients SHOULD NOT error due to the presence of additional properties that MAY be defined by future versions of this specification.</p></li>
+<li><p>Control information <a href="#ControlInformationidodataid"><code>id</code></a> or all of the entity’s primary key fields. The <code>id</code> control information MUST appear if any of the entity’s primary key fields are omitted from the response <em>or</em> the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an <a href="#UpdateaCollectionofEntities">update request</a>, an <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys">alternate key</a> (see <em>Alternate Keys</em> in <a href="#ODataURL">OData-URL</a>) 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 <code>id</code> control information and other primary key fields.</p></li>
</ul>
<p>For full metadata the <a href="#ControlInformationcontextodatacontext"><code>context</code></a> 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.</p>
<p>The deleted-entity object MAY include additional properties of the entity, as well as <a href="#InstanceAnnotations">annotations</a>, 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.</p>
diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md
index 0dc397f1..8938de3b 100644
--- a/docs/odata-json-format/odata-json-format.md
+++ b/docs/odata-json-format/odata-json-format.md
@@ -220,6 +220,8 @@ Section | Feature / Change | Issue
[Section 4.6.8](#ControlInformationidodataid)| Transient entities can be identifiable| [1928](https://github.com/oasis-tcs/odata-specs/issues/1928)
[Section 4.6.12](#ControlInformationmediaodatamedia)| `mediaContentType` can be `null`| [536](https://github.com/oasis-tcs/odata-specs/issues/536)
[Section 7](#StructuralProperty), [Section A.2](#InformativeReferences)| Removed reference to obsolete version of GeoJSON| [456](https://github.com/oasis-tcs/odata-specs/issues/456)
+[Section 15.3](#DeletedEntity) | `type` control information, if present, must come immediately after `removed` |
+[1985](https://github.com/oasis-tcs/odata-specs/issues/1985)
[Section 18](#ActionInvocation)| Allow common expressions in action payloads| [341](https://github.com/oasis-tcs/odata-specs/issues/341)
## <a id="Glossary" href="#Glossary">1.2 Glossary</a>
@@ -711,6 +713,7 @@ constraints have to be met:
- If present, the `context` control information MUST be the first
property in the JSON object.
+- For 4.01 deleted entities, the `removed` control information MUST appear after `context`, if present, and before any other property or control information.
- The
`type` control information, if present, MUST appear next in
the JSON object.
@@ -2271,7 +2274,8 @@ a property, not control information
In OData 4.01 payloads the deleted-entity object MUST include the
following properties, regardless of the specified
-[`metadata`](#ControllingtheAmountofControlInformationinResponses) value:
+[`metadata`](#ControllingtheAmountofControlInformationinResponses) value.
+For ordered payloads, this control information MUST follow the [payload ordering constraints](#PayloadOrderingConstraints).
- Control information
[`removed`](#ControlInformationremovedodataremoved),
@@ -2284,12 +2288,7 @@ following properties, regardless of the specified
collection. The object MAY include
[annotations](#InstanceAnnotations), and clients SHOULD NOT error
due to the presence of additional properties that MAY be defined by
- future versions of this specification. For [ordered
- payloads](#PayloadOrderingConstraints), the control information
- [`removed`](#ControlInformationremovedodataremoved) MUST immediately
- follow the [`context`](#ControlInformationcontextodatacontext) control
- information, if present, otherwise it MUST be the first property in the
- deleted entity.
+ future versions of this specification.
- Control information
[`id`](#ControlInformationidodataid)
@@ -2298,11 +2297,7 @@ following properties, regardless of the specified
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))
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 [ordered
- payloads](#PayloadOrderingConstraints), the control information
- `id`, if present, MUST immediately follow the control
- information
- [`removed`](#ControlInformationremovedodataremoved).
+ MAY omit the `id` control information and other primary key fields.
For full metadata the
[`context`](#ControlInformationcontextodatacontext)
diff --git a/odata-json-format/1 Introduction.md b/odata-json-format/1 Introduction.md
index 86925999..9d8e31c5 100644
--- a/odata-json-format/1 Introduction.md
+++ b/odata-json-format/1 Introduction.md
@@ -33,6 +33,9 @@ Transient entities can be identifiable|
[Section ##StructuralProperty], [Section ##InformativeReferences]|
Removed reference to obsolete version of GeoJSON|
[456](https://github.com/oasis-tcs/odata-specs/issues/456)
+[Section ##DeletedEntity] |
+`type` control information, if present, must come immediately after `removed` |
+[1985](https://github.com/oasis-tcs/odata-specs/issues/1985)
[Section ##ActionInvocation]|
Allow common expressions in action payloads|
[341](https://github.com/oasis-tcs/odata-specs/issues/341)
diff --git a/odata-json-format/15 Delta Payload.md b/odata-json-format/15 Delta Payload.md
index 95b2bff0..d6263f85 100644
--- a/odata-json-format/15 Delta Payload.md
+++ b/odata-json-format/15 Delta Payload.md
@@ -181,7 +181,9 @@ a property, not control information
In OData 4.01 payloads the deleted-entity object MUST include the
following properties, regardless of the specified
-[`metadata`](#ControllingtheAmountofControlInformationinResponses) value:
+[`metadata`](#ControllingtheAmountofControlInformationinResponses) value.
+For ordered payloads, this control information MUST follow the
+[payload ordering constraints](#PayloadOrderingConstraints).
- Control information
[`removed`](#ControlInformationremovedodataremoved),
@@ -194,12 +196,7 @@ following properties, regardless of the specified
collection. The object MAY include
[annotations](#InstanceAnnotations), and clients SHOULD NOT error
due to the presence of additional properties that MAY be defined by
- future versions of this specification. For [ordered
- payloads](#PayloadOrderingConstraints), the control information
- [`removed`](#ControlInformationremovedodataremoved) MUST immediately
- follow the [`context`](#ControlInformationcontextodatacontext) control
- information, if present, otherwise it MUST be the first property in the
- deleted entity.
+ future versions of this specification.
- Control information
[`id`](#ControlInformationidodataid)
@@ -209,11 +206,7 @@ following properties, regardless of the specified
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))
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 [ordered
- payloads](#PayloadOrderingConstraints), the control information
- `id`, if present, MUST immediately follow the control
- information
- [`removed`](#ControlInformationremovedodataremoved).
+ MAY omit the `id` control information and other primary key fields.
For full metadata the
[`context`](#ControlInformationcontextodatacontext)
diff --git a/odata-json-format/4 Common Characteristics.md b/odata-json-format/4 Common Characteristics.md
index daa44aa1..4c32577c 100644
--- a/odata-json-format/4 Common Characteristics.md
+++ b/odata-json-format/4 Common Characteristics.md
@@ -164,6 +164,8 @@ constraints have to be met:
- If present, the `context` control information MUST be the first
property in the JSON object.
+- For 4.01 deleted entities, the `removed` control information MUST appear
+ after `context`, if present, and before any other property or control information.
- The
`type` control information, if present, MUST appear next in
the JSON object.
From 18b4c1a24bc97ec0a13df21532e5e5d322442763 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= <heiko.theissen@sap.com>
Date: Wed, 16 Oct 2024 17:31:14 +0200
Subject: [PATCH 06/19] Change related entity with PUT (#1994)
Fixes #1973
---------
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
---
docs/odata-csdl-json/styles/odata.css | 31 +-
docs/odata-csdl-xml/styles/odata.css | 31 +-
.../styles/odata.css | 31 +-
docs/odata-json-format/odata-json-format.html | 2 +-
docs/odata-json-format/odata-json-format.md | 2 +-
docs/odata-json-format/styles/odata.css | 31 +-
docs/odata-protocol/odata-protocol.html | 307 +++++++++++-------
docs/odata-protocol/odata-protocol.md | 152 +++++++--
docs/odata-protocol/styles/odata.css | 31 +-
docs/odata-temporal-ext/styles/odata.css | 31 +-
docs/odata-url-conventions/styles/odata.css | 31 +-
odata-json-format/7 Structural Property.md | 2 +-
odata-protocol/11.4 Data Modification.md | 86 +++++
package-lock.json | 15 +-
styles/odata.css | 31 +-
15 files changed, 625 insertions(+), 189 deletions(-)
diff --git a/docs/odata-csdl-json/styles/odata.css b/docs/odata-csdl-json/styles/odata.css
index aa19bb20..2b94769c 100644
--- a/docs/odata-csdl-json/styles/odata.css
+++ b/docs/odata-csdl-json/styles/odata.css
@@ -1,3 +1,7 @@
+:root {
+ --indent: 40px;
+}
+
a:target,
span:target {
background-color: yellow;
@@ -168,11 +172,31 @@ td > code {
.example pre,
.rep {
- margin-left: 40px;
+ margin-left: var(--indent);
+}
+
+.caption p {
+ margin-left: var(--indent);
+ margin-bottom: -1em;
+}
+
+.side-by-side {
+ margin: -1em 0;
+}
+
+.side-by-side:after {
+ content: "";
+ display: block;
+ clear: both;
+}
+
+.side-by-side > div {
+ width: 50%;
+ float: left;
}
.indent {
- margin-left: 40px;
+ margin-left: var(--indent);
}
td pre {
@@ -195,7 +219,7 @@ mjx-container {
mjx-container[display="true"] {
text-align: left !important;
- margin-left: 40px !important;
+ margin-left: var(--indent) !important;
}
code .er {
@@ -247,6 +271,7 @@ h6 {
page-break-after: avoid;
}
+.side-by-side,
td {
page-break-inside: avoid;
}
diff --git a/docs/odata-csdl-xml/styles/odata.css b/docs/odata-csdl-xml/styles/odata.css
index aa19bb20..2b94769c 100644
--- a/docs/odata-csdl-xml/styles/odata.css
+++ b/docs/odata-csdl-xml/styles/odata.css
@@ -1,3 +1,7 @@
+:root {
+ --indent: 40px;
+}
+
a:target,
span:target {
background-color: yellow;
@@ -168,11 +172,31 @@ td > code {
.example pre,
.rep {
- margin-left: 40px;
+ margin-left: var(--indent);
+}
+
+.caption p {
+ margin-left: var(--indent);
+ margin-bottom: -1em;
+}
+
+.side-by-side {
+ margin: -1em 0;
+}
+
+.side-by-side:after {
+ content: "";
+ display: block;
+ clear: both;
+}
+
+.side-by-side > div {
+ width: 50%;
+ float: left;
}
.indent {
- margin-left: 40px;
+ margin-left: var(--indent);
}
td pre {
@@ -195,7 +219,7 @@ mjx-container {
mjx-container[display="true"] {
text-align: left !important;
- margin-left: 40px !important;
+ margin-left: var(--indent) !important;
}
code .er {
@@ -247,6 +271,7 @@ h6 {
page-break-after: avoid;
}
+.side-by-side,
td {
page-break-inside: avoid;
}
diff --git a/docs/odata-data-aggregation-ext/styles/odata.css b/docs/odata-data-aggregation-ext/styles/odata.css
index aa19bb20..2b94769c 100644
--- a/docs/odata-data-aggregation-ext/styles/odata.css
+++ b/docs/odata-data-aggregation-ext/styles/odata.css
@@ -1,3 +1,7 @@
+:root {
+ --indent: 40px;
+}
+
a:target,
span:target {
background-color: yellow;
@@ -168,11 +172,31 @@ td > code {
.example pre,
.rep {
- margin-left: 40px;
+ margin-left: var(--indent);
+}
+
+.caption p {
+ margin-left: var(--indent);
+ margin-bottom: -1em;
+}
+
+.side-by-side {
+ margin: -1em 0;
+}
+
+.side-by-side:after {
+ content: "";
+ display: block;
+ clear: both;
+}
+
+.side-by-side > div {
+ width: 50%;
+ float: left;
}
.indent {
- margin-left: 40px;
+ margin-left: var(--indent);
}
td pre {
@@ -195,7 +219,7 @@ mjx-container {
mjx-container[display="true"] {
text-align: left !important;
- margin-left: 40px !important;
+ margin-left: var(--indent) !important;
}
code .er {
@@ -247,6 +271,7 @@ h6 {
page-break-after: avoid;
}
+.side-by-side,
td {
page-break-inside: avoid;
}
diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html
index f1e59154..66603c79 100644
--- a/docs/odata-json-format/odata-json-format.html
+++ b/docs/odata-json-format/odata-json-format.html
@@ -1168,7 +1168,7 @@ <h2 id="85-bind-operation"><a id="BindOperation" href="#BindOperation">8.5 Bind
<span id="cb23-6"><a href="#cb23-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<div class="example">
-<p>Example 22: submit a partial update request to:</p>
+<p>Example <a id="deepupdate" href="#deepupdate">22</a>: submit a partial update request to:</p>
<ul>
<li>modify the name of an existing category</li>
<li>assign an existing product with the id 42 to the category</li>
diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md
index 8938de3b..231c3291 100644
--- a/docs/odata-json-format/odata-json-format.md
+++ b/docs/odata-json-format/odata-json-format.md
@@ -1737,7 +1737,7 @@ Content-Type: application/json
:::
::: example
-Example 22: submit a partial update request to:
+Example <a id="deepupdate" href="#deepupdate">22</a>: submit a partial update request to:
- modify the name of an existing category
- assign an existing product with the id 42 to the category
- assign an existing product 57 to the category and update its name
diff --git a/docs/odata-json-format/styles/odata.css b/docs/odata-json-format/styles/odata.css
index aa19bb20..2b94769c 100644
--- a/docs/odata-json-format/styles/odata.css
+++ b/docs/odata-json-format/styles/odata.css
@@ -1,3 +1,7 @@
+:root {
+ --indent: 40px;
+}
+
a:target,
span:target {
background-color: yellow;
@@ -168,11 +172,31 @@ td > code {
.example pre,
.rep {
- margin-left: 40px;
+ margin-left: var(--indent);
+}
+
+.caption p {
+ margin-left: var(--indent);
+ margin-bottom: -1em;
+}
+
+.side-by-side {
+ margin: -1em 0;
+}
+
+.side-by-side:after {
+ content: "";
+ display: block;
+ clear: both;
+}
+
+.side-by-side > div {
+ width: 50%;
+ float: left;
}
.indent {
- margin-left: 40px;
+ margin-left: var(--indent);
}
td pre {
@@ -195,7 +219,7 @@ mjx-container {
mjx-container[display="true"] {
text-align: left !important;
- margin-left: 40px !important;
+ margin-left: var(--indent) !important;
}
code .er {
@@ -247,6 +271,7 @@ h6 {
page-break-after: avoid;
}
+.side-by-side,
td {
page-break-inside: avoid;
}
diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
index 6c3877f7..83fc639c 100644
--- a/docs/odata-protocol/odata-protocol.html
+++ b/docs/odata-protocol/odata-protocol.html
@@ -2410,6 +2410,7 @@ <h4 id="11431-update-related-entities-when-updating-an-entity"><a id="UpdateRela
</summary>
<p>Update requests with an OData-Version header with a value of <code>4.0</code> MUST NOT contain related entities as inline content. Such requests MAY contain binding information for navigation properties. For single-valued navigation properties this replaces the relationship. For collection-valued navigation properties this adds to the relationship.</p>
<p>Payloads with an <code>OData-Version</code> header with a value of <code>4.01</code> or greater MAY include nested entities and entity references that specify the full set of to be related entities, or a nested <a href="#DeltaPayloads">delta payload</a> representing the related entities that have been added, removed, or changed. Such a request is referred to as a “deep update”. If the nested collection is represented identical to an expanded navigation property, then the set of nested entities and entity references specified in a successful update request represents the full set of entities to be related according to that relationship and MUST NOT include added links, deleted links, or deleted entities.</p>
+<p>If a navigation property is absent from a <code>PUT</code> or <code>PATCH</code> request payload, the referenced or contained entity, or the collection thereof, remains unchanged by a successful update.</p>
<div class="example">
<p>Example 78: using the JSON format, a 4.01 <code>PATCH</code> request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named <code>Suzanne Brown</code>. The <code>LastName</code> of employee 6 is updated to <code>Smith</code>.</p>
<div class="sourceCode" id="cb97"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb97-1"><a href="#cb97-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
@@ -2471,6 +2472,68 @@ <h4 id="11431-update-related-entities-when-updating-an-entity"><a id="UpdateRela
<span id="cb98-28"><a href="#cb98-28" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
<span id="cb98-29"><a href="#cb98-29" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
+<div class="example">
+<p>Example 80: When updating an entity with a 4.01 <code>PUT</code> request, the target of a non-containment navigation property can be replaced if the targeted entity is specified by an entity reference (see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#EntityReference">OData-JSON, section 14</a>), without specifying all its structural properties in <code>PUT</code> semantics.</p>
+<p>The following JSON payload changes the name of a category and the products belonging to it. (Compare this to <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#deepupdate">OData-JSON, example 22</a>.) The effect would be the same if the <code>@context</code> was omitted from the request.</p>
+<div class="side-by-side">
+<div class="caption">
+<p>Request</p>
+<div class="sourceCode" id="cb99"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb99-1"><a href="#cb99-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">http://host/service/Categories(6)?$expand=Products</span></span>
+<span id="cb99-2"><a href="#cb99-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb99-3"><a href="#cb99-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb99-4"><a href="#cb99-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb99-5"><a href="#cb99-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
+<span id="cb99-6"><a href="#cb99-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb99-7"><a href="#cb99-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb99-8"><a href="#cb99-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#$ref"</span><span class="fu">,</span></span>
+<span id="cb99-9"><a href="#cb99-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(57)"</span></span>
+<span id="cb99-10"><a href="#cb99-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb99-11"><a href="#cb99-11" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb99-12"><a href="#cb99-12" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+</div>
+<div class="caption">
+<p>Response</p>
+<div class="sourceCode" id="cb100"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb100-1"><a href="#cb100-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb100-2"><a href="#cb100-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#Categories/$entity"</span><span class="fu">,</span></span>
+<span id="cb100-3"><a href="#cb100-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CategoryID"</span><span class="fu">:</span> <span class="dv">6</span><span class="fu">,</span></span>
+<span id="cb100-4"><a href="#cb100-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
+<span id="cb100-5"><a href="#cb100-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb100-6"><a href="#cb100-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb100-7"><a href="#cb100-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span><span class="fu">,</span></span>
+<span id="cb100-8"><a href="#cb100-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Widgets"</span></span>
+<span id="cb100-9"><a href="#cb100-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb100-10"><a href="#cb100-10" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb100-11"><a href="#cb100-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+</div>
+</div>
+<p>If <code>Products</code> was a containment navigation property, the request and response would be the same, except that the <code>@id</code> would likely be relative to the category, for example, <code>Categories(6)/Products(57)</code>.</p>
+<p>If the targeted entity in the payload contains some structural properties, <code>PUT</code> resets all its other structural properties. The following alternative payload resets the product name. The effect would be the same if the <code>@id</code> was omitted from the request.</p>
+<div class="side-by-side">
+<div class="sourceCode" id="cb101"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb101-1"><a href="#cb101-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">http://host/service/Categories(6)?$expand=Products</span></span>
+<span id="cb101-2"><a href="#cb101-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb101-3"><a href="#cb101-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb101-4"><a href="#cb101-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb101-5"><a href="#cb101-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
+<span id="cb101-6"><a href="#cb101-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb101-7"><a href="#cb101-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb101-8"><a href="#cb101-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(57)"</span><span class="fu">,</span></span>
+<span id="cb101-9"><a href="#cb101-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span></span>
+<span id="cb101-10"><a href="#cb101-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb101-11"><a href="#cb101-11" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb101-12"><a href="#cb101-12" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<div class="sourceCode" id="cb102"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb102-1"><a href="#cb102-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb102-2"><a href="#cb102-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#Categories/$entity"</span><span class="fu">,</span></span>
+<span id="cb102-3"><a href="#cb102-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CategoryID"</span><span class="fu">:</span> <span class="dv">6</span><span class="fu">,</span></span>
+<span id="cb102-4"><a href="#cb102-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
+<span id="cb102-5"><a href="#cb102-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb102-6"><a href="#cb102-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb102-7"><a href="#cb102-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span><span class="fu">,</span></span>
+<span id="cb102-8"><a href="#cb102-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="kw">null</span></span>
+<span id="cb102-9"><a href="#cb102-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb102-10"><a href="#cb102-10" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb102-11"><a href="#cb102-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+</div>
+</div>
<p>Clients MAY associate an id with individual nested entities in the request by using the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a>. Services that respond with <a href="#ResponseCode200OK"><code>200 OK</code></a> SHOULD annotate the entities in the response using the same <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> value as specified in the request. Services SHOULD advertise support for deep updates, including support for returning the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a>, through the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepUpdateSupport"><code>Capabilities.DeepUpdateSupport</code></a> term, defined in <a href="#ODataVocCap">OData-VocCap</a>.</p>
<p>The <code>continue-on-error</code> preference is not supported for deep update operations.</p>
<p>On failure, the service MUST NOT apply any of the changes specified in the request.</p>
@@ -2573,22 +2636,22 @@ <h3 id="1148-managing-stream-properties"><a id="ManagingStreamProperties" href="
<p>An entity may have one or more <em>stream properties</em>. Stream properties are properties of type <code>Edm.Stream</code>.</p>
<p>The values for stream properties do not usually appear in the entity payload unless explicitly requested with <a href="#SystemQueryOptionexpand"><code>$expand</code></a>. Instead, the values are generally read or written through URLs.</p>
<div class="example">
-<p>Example <a id="entityWithStreamProperty" href="#entityWithStreamProperty">80</a>: read an entity and select a stream property</p>
+<p>Example <a id="entityWithStreamProperty" href="#entityWithStreamProperty">81</a>: read an entity and select a stream property</p>
<pre><code>GET http://host/service/Products(1)?$select=Thumbnail</code></pre>
<p>would only include control information for the stream property, not the stream data itself</p>
-<div class="sourceCode" id="cb100"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb100-1"><a href="#cb100-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb100-2"><a href="#cb100-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Products/$entity"</span><span class="fu">,</span></span>
-<span id="cb100-3"><a href="#cb100-3" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
-<span id="cb100-4"><a href="#cb100-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaReadLink"</span><span class="fu">:</span> <span class="st">"http://server/Thumbnail546.jpg"</span><span class="fu">,</span></span>
-<span id="cb100-5"><a href="#cb100-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaEditLink"</span><span class="fu">:</span> <span class="st">"http://server/uploads/Thumbnail546.jpg"</span><span class="fu">,</span></span>
-<span id="cb100-6"><a href="#cb100-6" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
-<span id="cb100-7"><a href="#cb100-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<div class="sourceCode" id="cb104"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb104-1"><a href="#cb104-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb104-2"><a href="#cb104-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Products/$entity"</span><span class="fu">,</span></span>
+<span id="cb104-3"><a href="#cb104-3" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
+<span id="cb104-4"><a href="#cb104-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaReadLink"</span><span class="fu">:</span> <span class="st">"http://server/Thumbnail546.jpg"</span><span class="fu">,</span></span>
+<span id="cb104-5"><a href="#cb104-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaEditLink"</span><span class="fu">:</span> <span class="st">"http://server/uploads/Thumbnail546.jpg"</span><span class="fu">,</span></span>
+<span id="cb104-6"><a href="#cb104-6" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
+<span id="cb104-7"><a href="#cb104-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
<p>The stream data can then be requested using the media read link:</p>
<pre><code>GET http://server/Thumbnail546.jpg</code></pre>
</div>
<p>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.</p>
<div class="example">
-<p>Example 81: directly read a stream property of an entity</p>
+<p>Example 82: directly read a stream property of an entity</p>
<pre><code>GET http://host/service/Products(1)/Thumbnail</code></pre>
<p>can return <a href="#ResponseCode200OK"><code>200 OK</code></a> and the stream data (see <a href="#RequestingStreamProperties">section 11.2.4.1</a>), or a <a href="#ResponseCode3xxRedirection"><code>3xx Redirect</code></a> to the media read link of the stream property.</p>
</div>
@@ -2608,7 +2671,7 @@ <h4 id="11482-delete-stream-values"><a id="DeleteStreamValues" href="#DeleteStre
</summary>
<p>A successful <code>DELETE</code> request to the edit URL of a stream property attempts to set the property to null and results in an error if the property is non-nullable.</p>
<div class="example">
-<p>Example 82: delete the stream value using the media edit link retrieved in <a href="#entityWithStreamProperty">example 80</a></p>
+<p>Example 83: delete the stream value using the media edit link retrieved in <a href="#entityWithStreamProperty">example 81</a></p>
<pre><code>DELETE http://server/uploads/Thumbnail546.jpg</code></pre>
</div>
<p>Attempting to request a stream property whose value is null results in <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>.</p>
@@ -2670,13 +2733,13 @@ <h3 id="11411-positional-inserts"><a id="PositionalInserts" href="#PositionalIns
</summary>
<p>Collections of entity, complex, or primitive types annotated with the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#PositionalInsert"><code>Core.PositionalInsert</code></a> term (see <a href="#ODataVocCore">OData-VocCore</a>) support inserting items at a specific location via <code>POST</code> requests to the collection URL using the <code>$index</code> system query option. The value of the <code>$index</code> 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.</p>
<div class="example">
-<p>Example 83: Insert a new email address at the second position</p>
-<div class="sourceCode" id="cb104"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb104-1"><a href="#cb104-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/service/Customers('ALFKI')/EmailAddresses?$index=1</span></span>
-<span id="cb104-2"><a href="#cb104-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb104-3"><a href="#cb104-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb104-4"><a href="#cb104-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb104-5"><a href="#cb104-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"value"</span><span class="fu">:</span> <span class="st">"alfred@futterkiste.de"</span></span>
-<span id="cb104-6"><a href="#cb104-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 84: Insert a new email address at the second position</p>
+<div class="sourceCode" id="cb108"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb108-1"><a href="#cb108-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/service/Customers('ALFKI')/EmailAddresses?$index=1</span></span>
+<span id="cb108-2"><a href="#cb108-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb108-3"><a href="#cb108-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb108-4"><a href="#cb108-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb108-5"><a href="#cb108-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"value"</span><span class="fu">:</span> <span class="st">"alfred@futterkiste.de"</span></span>
+<span id="cb108-6"><a href="#cb108-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
</details>
<details open><summary>
@@ -2731,13 +2794,13 @@ <h3 id="11414-update-members-of-a-collection"><a id="UpdateMembersofaCollection"
<p>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.</p>
<p>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 <a href="#UpdateanEntity">updated</a> using <code>PATCH</code> semantics. Structured types MAY include nested collections or delta collections, in which case the semantics described in <a href="#UpdateaCollectionofEntities">Update a Collection of Entities</a> applies.</p>
<div class="example">
-<p>Example 84: change the color of all beige-brown products</p>
-<div class="sourceCode" id="cb105"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb105-1"><a href="#cb105-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/service/Products/$filter(@bar)/$each?@bar=Color</span> <span class="er">eq</span> <span class="er">'beige-brown'</span></span>
-<span id="cb105-2"><a href="#cb105-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb105-3"><a href="#cb105-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb105-4"><a href="#cb105-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb105-5"><a href="#cb105-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Color"</span><span class="fu">:</span> <span class="st">"taupe"</span></span>
-<span id="cb105-6"><a href="#cb105-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 85: change the color of all beige-brown products</p>
+<div class="sourceCode" id="cb109"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb109-1"><a href="#cb109-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/service/Products/$filter(@bar)/$each?@bar=Color</span> <span class="er">eq</span> <span class="er">'beige-brown'</span></span>
+<span id="cb109-2"><a href="#cb109-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb109-3"><a href="#cb109-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb109-4"><a href="#cb109-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb109-5"><a href="#cb109-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Color"</span><span class="fu">:</span> <span class="st">"taupe"</span></span>
+<span id="cb109-6"><a href="#cb109-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>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 <a href="#UpdateaCollectionofEntities">Update a Collection of Entities</a>.</p>
<p>Clients should note that requesting a response may be expensive for services that could otherwise efficiently apply updates to a (possibly filtered) collection.</p>
@@ -2750,7 +2813,7 @@ <h3 id="11415-delete-members-of-a-collection"><a id="DeleteMembersofaCollection"
<p>Members of a collection can be deleted by submitting a <code>DELETE</code> request to the URL constructed by appending <code>/$each</code> to the resource path of the collection. The additional path segment expresses that the collection itself is not deleted.</p>
<p>The request resource path of the collection MAY contain type-cast or filter segments to subset the collection.</p>
<div class="example">
-<p>Example 85: delete all products older than 3</p>
+<p>Example 86: delete all products older than 3</p>
<pre><code>DELETE /service/Products/$filter(Age gt 3)/$each</code></pre>
</div>
<p>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.</p>
@@ -2769,25 +2832,25 @@ <h3 id="1151-binding-an-operation-to-a-resource"><a id="BindinganOperationtoaRes
<p><a href="#Actions">Actions</a> and <a href="#Functions">Functions</a> 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 <em>binding parameter</em>.</p>
<p>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 <em>binding parameter value</em>. Only aliases defined in the metadata document of the service can be used in URLs.</p>
<div class="example">
-<p>Example 86: the function <code>MostRecentOrder</code> can be bound to any URL that identifies a <code>SampleModel.Customer</code></p>
-<div class="sourceCode" id="cb107"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb107-1"><a href="#cb107-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"MostRecentOrder"</span><span class="ot"> IsBound=</span><span class="st">"true"</span>></span>
-<span id="cb107-2"><a href="#cb107-2" aria-hidden="true" tabindex="-1"></a> <<span class="kw">Parameter</span><span class="ot"> Name=</span><span class="st">"customer"</span><span class="ot"> Type=</span><span class="st">"SampleModel.Customer"</span> /></span>
-<span id="cb107-3"><a href="#cb107-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"SampleModel.Order"</span> /></span>
-<span id="cb107-4"><a href="#cb107-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
+<p>Example 87: the function <code>MostRecentOrder</code> can be bound to any URL that identifies a <code>SampleModel.Customer</code></p>
+<div class="sourceCode" id="cb111"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb111-1"><a href="#cb111-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"MostRecentOrder"</span><span class="ot"> IsBound=</span><span class="st">"true"</span>></span>
+<span id="cb111-2"><a href="#cb111-2" aria-hidden="true" tabindex="-1"></a> <<span class="kw">Parameter</span><span class="ot"> Name=</span><span class="st">"customer"</span><span class="ot"> Type=</span><span class="st">"SampleModel.Customer"</span> /></span>
+<span id="cb111-3"><a href="#cb111-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"SampleModel.Order"</span> /></span>
+<span id="cb111-4"><a href="#cb111-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
</div>
<div class="example">
-<p>Example 87: invoke the <code>MostRecentOrder</code> function with the value of the binding parameter <code>customer</code> being the entity identified by <code>http://host/service/Customers(6)</code></p>
+<p>Example 88: invoke the <code>MostRecentOrder</code> function with the value of the binding parameter <code>customer</code> being the entity identified by <code>http://host/service/Customers(6)</code></p>
<pre><code>GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()</code></pre>
</div>
<div class="example">
-<p>Example 88: the function <code>Comparison</code> can be bound to any URL that identifies a collection of entities</p>
-<div class="sourceCode" id="cb109"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb109-1"><a href="#cb109-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"Comparison"</span><span class="ot"> IsBound=</span><span class="st">"true"</span>></span>
-<span id="cb109-2"><a href="#cb109-2" aria-hidden="true" tabindex="-1"></a> <<span class="kw">Parameter</span><span class="ot"> Name=</span><span class="st">"in"</span><span class="ot"> Type=</span><span class="st">"Collection(Edm.EntityType)"</span> /></span>
-<span id="cb109-3"><a href="#cb109-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"Diff.Overview"</span> /></span>
-<span id="cb109-4"><a href="#cb109-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
+<p>Example 89: the function <code>Comparison</code> can be bound to any URL that identifies a collection of entities</p>
+<div class="sourceCode" id="cb113"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb113-1"><a href="#cb113-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"Comparison"</span><span class="ot"> IsBound=</span><span class="st">"true"</span>></span>
+<span id="cb113-2"><a href="#cb113-2" aria-hidden="true" tabindex="-1"></a> <<span class="kw">Parameter</span><span class="ot"> Name=</span><span class="st">"in"</span><span class="ot"> Type=</span><span class="st">"Collection(Edm.EntityType)"</span> /></span>
+<span id="cb113-3"><a href="#cb113-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"Diff.Overview"</span> /></span>
+<span id="cb113-4"><a href="#cb113-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
</div>
<div class="example">
-<p>Example 89: invoke the <code>Comparison</code> function on the set of red products</p>
+<p>Example 90: invoke the <code>Comparison</code> function on the set of red products</p>
<pre><code>GET http://host/service/Products/$filter(Color eq 'Red')/Diff.Comparison()</code></pre>
</div>
</details>
@@ -2798,7 +2861,7 @@ <h3 id="1152-applying-an-operation-to-members-of-a-collection"><a id="Applyingan
<p>The resource path of the collection MAY contain type-cast or filter segments to subset the collection.</p>
<p>The response is a collection with members that are instances of the result type of the bound operation. If the bound operation returns a collection, the response is a collection of collections.</p>
<div class="example">
-<p>Example 90: invoke the <code>MostRecentOrder</code> function on each entity in the entity set <code>Customers</code></p>
+<p>Example 91: invoke the <code>MostRecentOrder</code> function on each entity in the entity set <code>Customers</code></p>
<pre><code>GET http://host/service/Customers/$each/SampleModel.MostRecentOrder()</code></pre>
</div>
<p>The client MAY specify the <code>continue-on-error</code> preference, in which case the service MAY continue processing actions after a failure. In this case, the service MUST, regardless of the <code>return</code> 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 <code>Core.DataModificationException</code> with a <code>failedOperation</code> value of <code>invoke</code>.</p>
@@ -2809,29 +2872,29 @@ <h3 id="1153-advertising-available-operations-within-a-payload"><a id="Advertisi
</summary>
<p>Services MAY return actions and/or functions bound to a particular entity or entity collection as part of the representation of the entity or entity collection within the payload. The representation of an action or function depends on the <a href="#Formats">format</a>.</p>
<div class="example">
-<p>Example 91: given a <code>GET</code> request to <code>http://host/service/Customers('ALFKI')</code>, the service might respond with a Customer that includes the <code>SampleEntities.MostRecentOrder</code> function bound to the entity</p>
-<div class="sourceCode" id="cb112"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb112-1"><a href="#cb112-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb112-2"><a href="#cb112-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="er">…</span><span class="fu">,</span></span>
-<span id="cb112-3"><a href="#cb112-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CustomerID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
-<span id="cb112-4"><a href="#cb112-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
-<span id="cb112-5"><a href="#cb112-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"#SampleEntities.MostRecentOrder"</span><span class="fu">:</span> <span class="fu">{</span></span>
-<span id="cb112-6"><a href="#cb112-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"title"</span><span class="fu">:</span> <span class="st">"Most Recent Order"</span><span class="fu">,</span></span>
-<span id="cb112-7"><a href="#cb112-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"target"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/SampleEntities.MostRecentOrder()"</span></span>
-<span id="cb112-8"><a href="#cb112-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
-<span id="cb112-9"><a href="#cb112-9" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
-<span id="cb112-10"><a href="#cb112-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 92: given a <code>GET</code> request to <code>http://host/service/Customers('ALFKI')</code>, the service might respond with a Customer that includes the <code>SampleEntities.MostRecentOrder</code> function bound to the entity</p>
+<div class="sourceCode" id="cb116"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb116-1"><a href="#cb116-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb116-2"><a href="#cb116-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="er">…</span><span class="fu">,</span></span>
+<span id="cb116-3"><a href="#cb116-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CustomerID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
+<span id="cb116-4"><a href="#cb116-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
+<span id="cb116-5"><a href="#cb116-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"#SampleEntities.MostRecentOrder"</span><span class="fu">:</span> <span class="fu">{</span></span>
+<span id="cb116-6"><a href="#cb116-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"title"</span><span class="fu">:</span> <span class="st">"Most Recent Order"</span><span class="fu">,</span></span>
+<span id="cb116-7"><a href="#cb116-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"target"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/SampleEntities.MostRecentOrder()"</span></span>
+<span id="cb116-8"><a href="#cb116-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
+<span id="cb116-9"><a href="#cb116-9" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
+<span id="cb116-10"><a href="#cb116-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>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 <a href="#ODataURL">OData-URL</a>.</p>
<p>Services can advertise that a function or action is not available for a particular instance by setting its value to null.</p>
<div class="example">
-<p>Example 92: the <code>SampleEntities.MostRecentOrder</code> function is not available for customer <code>ALFKI</code></p>
-<div class="sourceCode" id="cb113"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb113-1"><a href="#cb113-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb113-2"><a href="#cb113-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="er">…</span><span class="fu">,</span></span>
-<span id="cb113-3"><a href="#cb113-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CustomerID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
-<span id="cb113-4"><a href="#cb113-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
-<span id="cb113-5"><a href="#cb113-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"#SampleEntities.MostRecentOrder"</span><span class="fu">:</span> <span class="kw">null</span><span class="fu">,</span></span>
-<span id="cb113-6"><a href="#cb113-6" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
-<span id="cb113-7"><a href="#cb113-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 93: the <code>SampleEntities.MostRecentOrder</code> function is not available for customer <code>ALFKI</code></p>
+<div class="sourceCode" id="cb117"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb117-1"><a href="#cb117-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb117-2"><a href="#cb117-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="er">…</span><span class="fu">,</span></span>
+<span id="cb117-3"><a href="#cb117-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CustomerID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
+<span id="cb117-4"><a href="#cb117-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
+<span id="cb117-5"><a href="#cb117-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"#SampleEntities.MostRecentOrder"</span><span class="fu">:</span> <span class="kw">null</span><span class="fu">,</span></span>
+<span id="cb117-6"><a href="#cb117-6" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
+<span id="cb117-7"><a href="#cb117-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
</details>
<details open><summary>
@@ -2849,7 +2912,7 @@ <h4 id="11541-invoking-a-function"><a id="InvokingaFunction" href="#InvokingaFun
<p>To invoke a function through a function import the client issues a <code>GET</code> request to a URL identifying the function import and passing parameter values using <a href="#InlineParameterSyntax">inline parameter syntax</a>. 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.</p>
<p>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 <code>POST</code> request may be used to create a new entity in the identified collection.</p>
<div class="example">
-<p>Example 93: add a new item to the list of items of the shopping cart returned by the composable <code>MyShoppingCart</code> function import</p>
+<p>Example 94: add a new item to the list of items of the shopping cart returned by the composable <code>MyShoppingCart</code> function import</p>
<pre><code>POST http://host/service/MyShoppingCart()/Items
…</code></pre>
@@ -2866,22 +2929,22 @@ <h5 id="115411-inline-parameter-syntax"><a id="InlineParameterSyntax" href="#Inl
<p>Parameter values are specified inline by appending a comma-separated list of parameter values, enclosed by parenthesis to the function name.</p>
<p>Each parameter value is represented as a name/value pair in the format <code>Name=Value</code>, where <code>Name</code> is the name of the parameter to the function and <code>Value</code> is the parameter value.</p>
<div class="example">
-<p>Example 94: invoke a <code>Sales.EmployeesByManager</code> function which takes a single <code>ManagerID</code> parameter via the function import <code>EmployeesByManager</code></p>
+<p>Example 95: invoke a <code>Sales.EmployeesByManager</code> function which takes a single <code>ManagerID</code> parameter via the function import <code>EmployeesByManager</code></p>
<pre><code>GET http://host/service/EmployeesByManager(ManagerID=3)</code></pre>
</div>
<div class="example">
-<p>Example 95: return all Customers whose <code>City</code> property returns <code>Western</code> when passed to the <code>Sales.SalesRegion</code> function</p>
+<p>Example 96: return all Customers whose <code>City</code> property returns <code>Western</code> when passed to the <code>Sales.SalesRegion</code> function</p>
<pre><code>GET http://host/service/Customers?
$filter=Sales.SalesRegion(City=$it/City) eq 'Western'</code></pre>
</div>
<p>A <a href="#ParameterAliases">parameter alias</a> 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.</p>
<div class="example">
-<p>Example 96: invoke a <code>Sales.EmployeesByManager</code> function via the function import <code>EmployeesByManager</code>, passing 3 for the <code>ManagerID</code> parameter</p>
+<p>Example 97: invoke a <code>Sales.EmployeesByManager</code> function via the function import <code>EmployeesByManager</code>, passing 3 for the <code>ManagerID</code> parameter</p>
<pre><code>GET http://host/service/EmployeesByManager(ManagerID=@p1)?@p1=3</code></pre>
</div>
<p>Services MAY in addition allow implicit <a href="#ParameterAliases">parameter aliases</a> 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 (<code>@</code>) 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 <code>$</code> prefix), the parameter name MUST be prefixed with an at (<code>@</code>) sign.</p>
<div class="example">
-<p>Example 97: invoke a <code>Sales.EmployeesByManager</code> function via the function import <code>EmployeesByManager</code>, passing 3 for the <code>ManagerID</code> parameter using the implicit parameter alias</p>
+<p>Example 98: invoke a <code>Sales.EmployeesByManager</code> function via the function import <code>EmployeesByManager</code>, passing 3 for the <code>ManagerID</code> parameter using the implicit parameter alias</p>
<pre><code>GET http://host/service/EmployeesByManager?ManagerID=3</code></pre>
</div>
<p>Non-binding parameters annotated with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter"><code>Core.OptionalParameter</code></a> defined in <a href="#ODataVocCore">OData-VocCore</a> MAY be omitted. If it is annotated and the annotation specifies a <code>DefaultValue</code>, 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.</p>
@@ -2921,18 +2984,18 @@ <h4 id="11551-invoking-an-action"><a id="InvokinganAction" href="#InvokinganActi
<p>Actions without a return type respond with <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> on success.</p>
<p>To request processing of the action only if the binding parameter value, an entity or collection of entities, is unmodified, the client includes the <a href="#HeaderIfMatch"><code>If-Match</code></a> 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 <a href="#HeaderETag"><code>ETag</code></a> header of a collection response.</p>
<div class="example">
-<p>Example 98: invoke the <code>SampleEntities.CreateOrder</code> action using <code>Customers('ALFKI')</code> as the customer (or binding parameter). The values <code>2</code> for the <code>quantity</code> parameter and <code>BLACKFRIDAY</code> for the <code>discountCode</code> parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.</p>
-<div class="sourceCode" id="cb119"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb119-1"><a href="#cb119-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder</span></span>
-<span id="cb119-2"><a href="#cb119-2" aria-hidden="true" tabindex="-1"></a><span class="er">If-Match:</span> <span class="er">W/"MjAxOS0wMy0yMVQxMzowNVo="</span></span>
-<span id="cb119-3"><a href="#cb119-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb119-4"><a href="#cb119-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb119-5"><a href="#cb119-5" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb119-6"><a href="#cb119-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"items"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb119-7"><a href="#cb119-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"product"</span><span class="fu">:</span> <span class="dv">4001</span><span class="fu">,</span> <span class="dt">"quantity"</span><span class="fu">:</span> <span class="dv">2</span> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb119-8"><a href="#cb119-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"product"</span><span class="fu">:</span> <span class="dv">7062</span><span class="fu">,</span> <span class="dt">"quantity"</span><span class="fu">:</span> <span class="dv">1</span> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb119-9"><a href="#cb119-9" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span><span class="fu">,</span></span>
-<span id="cb119-10"><a href="#cb119-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"discountCode"</span><span class="fu">:</span> <span class="st">"BLACKFRIDAY"</span></span>
-<span id="cb119-11"><a href="#cb119-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 99: invoke the <code>SampleEntities.CreateOrder</code> action using <code>Customers('ALFKI')</code> as the customer (or binding parameter). The values <code>2</code> for the <code>quantity</code> parameter and <code>BLACKFRIDAY</code> for the <code>discountCode</code> parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.</p>
+<div class="sourceCode" id="cb123"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb123-1"><a href="#cb123-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder</span></span>
+<span id="cb123-2"><a href="#cb123-2" aria-hidden="true" tabindex="-1"></a><span class="er">If-Match:</span> <span class="er">W/"MjAxOS0wMy0yMVQxMzowNVo="</span></span>
+<span id="cb123-3"><a href="#cb123-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb123-4"><a href="#cb123-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb123-5"><a href="#cb123-5" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb123-6"><a href="#cb123-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"items"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb123-7"><a href="#cb123-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"product"</span><span class="fu">:</span> <span class="dv">4001</span><span class="fu">,</span> <span class="dt">"quantity"</span><span class="fu">:</span> <span class="dv">2</span> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb123-8"><a href="#cb123-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"product"</span><span class="fu">:</span> <span class="dv">7062</span><span class="fu">,</span> <span class="dt">"quantity"</span><span class="fu">:</span> <span class="dv">1</span> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb123-9"><a href="#cb123-9" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span><span class="fu">,</span></span>
+<span id="cb123-10"><a href="#cb123-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"discountCode"</span><span class="fu">:</span> <span class="st">"BLACKFRIDAY"</span></span>
+<span id="cb123-11"><a href="#cb123-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
</details>
<details open><summary>
@@ -2972,7 +3035,7 @@ <h3 id="1171-batch-request-headers"><a id="BatchRequestHeaders" href="#BatchRequ
</summary>
<p>A batch request using the <a href="#MultipartBatchFormat">multipart batch format</a> MUST contain a <a href="#HeaderContentType"><code>Content-Type</code></a> header specifying a content type of <code>multipart/mixed</code> and a <code>boundary</code> parameter as defined in <a href="#rfc2046">RFC2046</a>.</p>
<div class="example">
-<p>Example 99: multipart batch request</p>
+<p>Example 100: multipart batch request</p>
<pre><code>POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.0
@@ -2982,7 +3045,7 @@ <h3 id="1171-batch-request-headers"><a id="BatchRequestHeaders" href="#BatchRequ
</div>
<p>A batch request using the JSON batch format MUST contain a <code>Content-Type</code> header specifying a content type of <code>application/json</code>.</p>
<div class="example">
-<p>Example 100: JSON batch request</p>
+<p>Example 101: JSON batch request</p>
<pre><code>POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.01
@@ -3009,7 +3072,7 @@ <h3 id="1173-identifying-individual-requests"><a id="IdentifyingIndividualReques
<details open><summary>
<h3 id="1174-referencing-returned-entities"><a id="ReferencingReturnedEntities" href="#ReferencingReturnedEntities">11.7.4 Referencing Returned Entities</a></h3>
</summary>
-<p>Entities created by an <a href="#CreateanEntity">insert</a> request or an <a href="#InvokinganAction">action</a> can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a <code>$</code> character as the first segment of the request URL. Services MUST treat this segment like the URL in the <a href="#HeaderLocation"><code>Location</code></a> header of the response to the request identified by the segment. If the <code>Location</code> 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 <a href="#batchcontentid">example 105</a>.</p>
+<p>Entities created by an <a href="#CreateanEntity">insert</a> request or an <a href="#InvokinganAction">action</a> can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a <code>$</code> character as the first segment of the request URL. Services MUST treat this segment like the URL in the <a href="#HeaderLocation"><code>Location</code></a> header of the response to the request identified by the segment. If the <code>Location</code> 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 <a href="#batchcontentid">example 106</a>.</p>
<p>If the <code>$</code>-prefixed request identifier is identical to the name of a top-level system resource (<code>$batch</code>, <code>$crossjoin</code>, <code>$all</code>, <code>$entity</code>, <code>$root</code>, <code>$id</code>, <code>$metadata</code>, or other system resources defined according to the <a href="#HeaderODataVersion"><code>OData-Version</code></a> 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.</p>
<p>Services MAY also support referencing within request bodies, in which case they SHOULD advertise this support by specifying the <code>ReferencesInRequestBodiesSupported</code> property in the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#BatchSupport"><code>Capabilities.BatchSupport</code></a> term applied to the entity container, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
</details>
@@ -3043,25 +3106,25 @@ <h4 id="11771-multipart-batch-request-body"><a id="MultipartBatchRequestBody" hr
<li>Absolute URI with schema, host, port, and absolute resource path.</li>
</ul>
<div class="example">
-<p>Example 101:</p>
+<p>Example 102:</p>
<pre><code>GET https://host:1234/path/service/People(1) HTTP/1.1</code></pre>
</div>
<ul>
<li>Absolute resource path and separate <code>Host</code> header</li>
</ul>
<div class="example">
-<p>Example <a id="batchhost" href="#batchhost">102</a>:</p>
-<div class="sourceCode" id="cb123"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb123-1"><a href="#cb123-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/path/service/People(1) HTTP/1.1</span></span>
-<span id="cb123-2"><a href="#cb123-2" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">myserver.mydomain.org:1234</span></span>
-<span id="cb123-3"><a href="#cb123-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb123-4"><a href="#cb123-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb123-5"><a href="#cb123-5" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Peter"</span> <span class="fu">}</span></span></code></pre></div>
+<p>Example <a id="batchhost" href="#batchhost">103</a>:</p>
+<div class="sourceCode" id="cb127"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb127-1"><a href="#cb127-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/path/service/People(1) HTTP/1.1</span></span>
+<span id="cb127-2"><a href="#cb127-2" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">myserver.mydomain.org:1234</span></span>
+<span id="cb127-3"><a href="#cb127-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb127-4"><a href="#cb127-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb127-5"><a href="#cb127-5" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Peter"</span> <span class="fu">}</span></span></code></pre></div>
</div>
<ul>
<li>Resource path relative to the batch request URI.</li>
</ul>
<div class="example">
-<p>Example 103:</p>
+<p>Example 104:</p>
<pre><code>DELETE People(1) HTTP/1.1</code></pre>
</div>
<p>Services MUST support all three formats for URLs of individual requests.</p>
@@ -3073,7 +3136,7 @@ <h4 id="11771-multipart-batch-request-body"><a id="MultipartBatchRequestBody" hr
</ul>
<p>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.</p>
<div class="example">
-<p>Example <a id="batchRequest" href="#batchRequest">104</a>: a batch request that contains the following individual requests in the order listed</p>
+<p>Example <a id="batchRequest" href="#batchRequest">105</a>: a batch request that contains the following individual requests in the order listed</p>
<ol type="1">
<li>A query request</li>
<li>A change set that contains the following requests:
@@ -3139,7 +3202,7 @@ <h4 id="11772-referencing-new-entities"><a id="ReferencingNewEntities" href="#Re
</summary>
<p>Entities created by an <a href="#CreateanEntity">insert</a> request or an <a href="#InvokinganAction">action</a> 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 <code>ReferencesAcrossChangeSetsSupported</code> property in the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#BatchSupport"><code>Capabilities.BatchSupport</code></a> term applied to the entity container, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
<div class="example">
-<p>Example <a id="batchcontentid" href="#batchcontentid">105</a>: a batch request that contains the following operations in the order listed:</p>
+<p>Example <a id="batchcontentid" href="#batchcontentid">106</a>: a batch request that contains the following operations in the order listed:</p>
<p>A change set that contains the following requests:</p>
<ul>
<li>Insert a new entity (with <code>Content-ID = 1</code>)</li>
@@ -3199,54 +3262,54 @@ <h4 id="11772-referencing-new-entities"><a id="ReferencingNewEntities" href="#Re
…
--changeset_77162fcd-b8da-41ac-a9f8-9357efbbe--
--batch_36522ad7-fc75-4b56-8c71-56071383e77a--</code></pre>
-<p>The second <code>Location</code> URL <code>Orders(1)</code> is relative with its base URI being the second request URL <code>$1/Orders</code>. To get an absolute base URI, the client must replace the <code>$1</code> with the first <code>Location</code> URL <code>Customers('ALFKI')</code> and resolve the resulting URL <code>Customers('ALFKI')/Orders(1)</code> relative to its base URI, which is <code>http://host/service/Customers</code> (determined from the first request URL <code>/service/Customers</code> and the <code>Host: host</code> header as in <a href="#batchhost">example 102</a>). This gives the effective second request URL <code>http://host/service/Customers('ALFKI')/Orders</code> as base URI for the second <code>Location</code> URL, which therefore resolves to <code>http://host/service/Customers('ALFKI')/Orders(1)</code>.</p>
+<p>The second <code>Location</code> URL <code>Orders(1)</code> is relative with its base URI being the second request URL <code>$1/Orders</code>. To get an absolute base URI, the client must replace the <code>$1</code> with the first <code>Location</code> URL <code>Customers('ALFKI')</code> and resolve the resulting URL <code>Customers('ALFKI')/Orders(1)</code> relative to its base URI, which is <code>http://host/service/Customers</code> (determined from the first request URL <code>/service/Customers</code> and the <code>Host: host</code> header as in <a href="#batchhost">example 103</a>). This gives the effective second request URL <code>http://host/service/Customers('ALFKI')/Orders</code> as base URI for the second <code>Location</code> URL, which therefore resolves to <code>http://host/service/Customers('ALFKI')/Orders(1)</code>.</p>
</div>
</details>
<details open><summary>
<h4 id="11773-referencing-an-etag"><a id="ReferencinganETag" href="#ReferencinganETag">11.7.7.3 Referencing an ETag</a></h4>
</summary>
<div class="example">
-<p>Example 106: a batch request that contains the following operations in the order listed:</p>
+<p>Example 107: a batch request that contains the following operations in the order listed:</p>
<ul>
<li>Get an employee (with <code>Content-ID = 1</code>)</li>
<li>Update the salary only if the employee has not changed</li>
</ul>
-<div class="sourceCode" id="cb128"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb128-1"><a href="#cb128-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/service/$batch</span> <span class="er">HTTP/1.1</span></span>
-<span id="cb128-2"><a href="#cb128-2" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
-<span id="cb128-3"><a href="#cb128-3" aria-hidden="true" tabindex="-1"></a><span class="er">OData-Version:</span> <span class="er">4.0</span></span>
-<span id="cb128-4"><a href="#cb128-4" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">multipart/mixed;</span> <span class="er">boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
-<span id="cb128-5"><a href="#cb128-5" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">###</span></span>
-<span id="cb128-6"><a href="#cb128-6" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb128-7"><a href="#cb128-7" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
-<span id="cb128-8"><a href="#cb128-8" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/http</span></span>
-<span id="cb128-9"><a href="#cb128-9" aria-hidden="true" tabindex="-1"></a><span class="er">Content-ID:</span> <span class="er">1</span></span>
-<span id="cb128-10"><a href="#cb128-10" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb128-11"><a href="#cb128-11" aria-hidden="true" tabindex="-1"></a><span class="er">GET</span> <span class="er">/service/Employees(0)</span> <span class="er">HTTP/1.1</span></span>
-<span id="cb128-12"><a href="#cb128-12" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
-<span id="cb128-13"><a href="#cb128-13" aria-hidden="true" tabindex="-1"></a><span class="er">Accept:</span> <span class="er">application/json</span></span>
-<span id="cb128-14"><a href="#cb128-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb128-15"><a href="#cb128-15" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb128-16"><a href="#cb128-16" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
-<span id="cb128-17"><a href="#cb128-17" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/http</span></span>
-<span id="cb128-18"><a href="#cb128-18" aria-hidden="true" tabindex="-1"></a><span class="er">Content-ID:</span> <span class="er">2</span></span>
-<span id="cb128-19"><a href="#cb128-19" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb128-20"><a href="#cb128-20" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/service/Employees(0)</span> <span class="er">HTTP/1.1</span></span>
-<span id="cb128-21"><a href="#cb128-21" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
-<span id="cb128-22"><a href="#cb128-22" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb128-23"><a href="#cb128-23" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">###</span></span>
-<span id="cb128-24"><a href="#cb128-24" aria-hidden="true" tabindex="-1"></a><span class="er">If-Match:</span> <span class="er">$1</span></span>
-<span id="cb128-25"><a href="#cb128-25" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb128-26"><a href="#cb128-26" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb128-27"><a href="#cb128-27" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Salary"</span><span class="fu">:</span> <span class="dv">75000</span></span>
-<span id="cb128-28"><a href="#cb128-28" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>
-<span id="cb128-29"><a href="#cb128-29" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b--</span></span></code></pre></div>
+<div class="sourceCode" id="cb132"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb132-1"><a href="#cb132-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/service/$batch</span> <span class="er">HTTP/1.1</span></span>
+<span id="cb132-2"><a href="#cb132-2" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
+<span id="cb132-3"><a href="#cb132-3" aria-hidden="true" tabindex="-1"></a><span class="er">OData-Version:</span> <span class="er">4.0</span></span>
+<span id="cb132-4"><a href="#cb132-4" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">multipart/mixed;</span> <span class="er">boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
+<span id="cb132-5"><a href="#cb132-5" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">###</span></span>
+<span id="cb132-6"><a href="#cb132-6" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb132-7"><a href="#cb132-7" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
+<span id="cb132-8"><a href="#cb132-8" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/http</span></span>
+<span id="cb132-9"><a href="#cb132-9" aria-hidden="true" tabindex="-1"></a><span class="er">Content-ID:</span> <span class="er">1</span></span>
+<span id="cb132-10"><a href="#cb132-10" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb132-11"><a href="#cb132-11" aria-hidden="true" tabindex="-1"></a><span class="er">GET</span> <span class="er">/service/Employees(0)</span> <span class="er">HTTP/1.1</span></span>
+<span id="cb132-12"><a href="#cb132-12" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
+<span id="cb132-13"><a href="#cb132-13" aria-hidden="true" tabindex="-1"></a><span class="er">Accept:</span> <span class="er">application/json</span></span>
+<span id="cb132-14"><a href="#cb132-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb132-15"><a href="#cb132-15" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb132-16"><a href="#cb132-16" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
+<span id="cb132-17"><a href="#cb132-17" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/http</span></span>
+<span id="cb132-18"><a href="#cb132-18" aria-hidden="true" tabindex="-1"></a><span class="er">Content-ID:</span> <span class="er">2</span></span>
+<span id="cb132-19"><a href="#cb132-19" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb132-20"><a href="#cb132-20" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/service/Employees(0)</span> <span class="er">HTTP/1.1</span></span>
+<span id="cb132-21"><a href="#cb132-21" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
+<span id="cb132-22"><a href="#cb132-22" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb132-23"><a href="#cb132-23" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">###</span></span>
+<span id="cb132-24"><a href="#cb132-24" aria-hidden="true" tabindex="-1"></a><span class="er">If-Match:</span> <span class="er">$1</span></span>
+<span id="cb132-25"><a href="#cb132-25" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb132-26"><a href="#cb132-26" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb132-27"><a href="#cb132-27" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Salary"</span><span class="fu">:</span> <span class="dv">75000</span></span>
+<span id="cb132-28"><a href="#cb132-28" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>
+<span id="cb132-29"><a href="#cb132-29" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b--</span></span></code></pre></div>
</div>
</details>
<details open><summary>
<h4 id="11774-referencing-response-body-values"><a id="ReferencingResponseBodyValues" href="#ReferencingResponseBodyValues">11.7.7.4 Referencing Response Body Values</a></h4>
</summary>
<div class="example">
-<p>Example 107: a batch request that contains the following operations in the order listed:</p>
+<p>Example 108: a batch request that contains the following operations in the order listed:</p>
<ul>
<li>Get an employee (with <code>Content-ID = 1</code>)</li>
<li>Get all employees residing in the same building</li>
@@ -3295,9 +3358,9 @@ <h4 id="11776-multipart-batch-response"><a id="MultipartBatchResponse" href="#Mu
<li><a href="#AsynchronousBatchRequests">Asynchronously processed batch requests</a> can return interim results and end with a <code>202 Accepted</code> as the last part of the multipart response. Therefore, the <a href="#Preferencerespondasync"><code>respond-async</code></a> preference MUST NOT be applied to individual requests within a batch if the batch response is a multipart response.</li>
</ul>
<p>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 <code>Content-ID</code> header with the value of the <code>id</code> name/value pair of the corresponding request object.</p>
-<p>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 <a href="#DataServiceRequests">Data Service Requests</a>. Relative URLs in each individual response are relative to the request URL of the corresponding individual request (see <a href="#batchcontentid">example 105</a>). URLs in responses MUST NOT contain <code>$</code>-prefixed request identifiers.</p>
+<p>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 <a href="#DataServiceRequests">Data Service Requests</a>. Relative URLs in each individual response are relative to the request URL of the corresponding individual request (see <a href="#batchcontentid">example 106</a>). URLs in responses MUST NOT contain <code>$</code>-prefixed request identifiers.</p>
<div class="example">
-<p>Example 108: referencing the batch request <a href="#batchRequest">example 104</a> above, assume all the requests except the final query request succeed. In this case the response would be</p>
+<p>Example 109: referencing the batch request <a href="#batchRequest">example 105</a> above, assume all the requests except the final query request succeed. In this case the response would be</p>
<pre><code>HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
@@ -3351,7 +3414,7 @@ <h4 id="11777-asynchronous-batch-requests"><a id="AsynchronousBatchRequests" hre
<p>A service MAY return interim results to an asynchronously executing batch. It does this by responding with <a href="#ResponseCode200OK"><code>200 OK</code></a> to a <code>GET</code> request to the monitor resource and including a <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> response as the last part of the multipart response. The client can use the monitor URL returned in this <code>202 Accepted</code> response to continue processing the batch response.</p>
<p>Since a change set is executed atomically, <code>202 Accepted</code> MUST NOT be returned within a change set.</p>
<div class="example">
-<p>Example 109: referencing the <a href="#batchRequest">example 104</a> above again, assume that</p>
+<p>Example 110: referencing the <a href="#batchRequest">example 105</a> above again, assume that</p>
<pre><code>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 b1d81e3b..049d318e 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -4453,6 +4453,9 @@ references specified in a successful update request represents the full
set of entities to be related according to that relationship and MUST
NOT include added links, deleted links, or deleted entities.
+If a navigation property is absent from a `PUT` or `PATCH` request payload, the referenced
+or contained entity, or the collection thereof, remains unchanged by a successful update.
+
::: example
Example 78: using the JSON format, a 4.01 `PATCH` request can update a
manager entity. Following the update, the manager has three direct
@@ -4549,7 +4552,90 @@ nested delta representation to:
]
}
```
+:::
+
+::: example
+Example 80: 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.
+
+The following JSON payload changes the name of a category and the products belonging
+to it. (Compare this to [OData-JSON, example 22](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#deepupdate).)
+The effect would be the same if the `@context` was omitted from the request.
+:::: side-by-side
+::::: caption
+Request
+```json
+PUT http://host/service/Categories(6)?$expand=Products
+Content-Type: application/json
+
+{
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "@context": "$metadata#$ref",
+ "@id": "Products(57)"
+ }
+ ]
+}
+```
+:::::
+::::: caption
+Response
+```json
+{
+ "@context": "$metadata#Categories/$entity",
+ "CategoryID": 6,
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "ProductID": 57,
+ "Name": "Widgets"
+ }
+ ]
+}
+```
+:::::
+::::
+
+If `Products` was a containment navigation property, the request and response
+would be the same, except that the `@id` would likely be relative to the category,
+for example, `Categories(6)/Products(57)`.
+If the targeted entity in the payload contains some structural properties,
+`PUT` resets all its other structural properties. The following alternative
+payload resets the product name.
+The effect would be the same if the `@id` was omitted from the request.
+:::: side-by-side
+```json
+PUT http://host/service/Categories(6)?$expand=Products
+Content-Type: application/json
+
+{
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "@id": "Products(57)",
+ "ProductID": 57
+ }
+ ]
+}
+```
+```json
+{
+ "@context": "$metadata#Categories/$entity",
+ "CategoryID": 6,
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "ProductID": 57,
+ "Name": null
+ }
+ ]
+}
+```
+::::
:::
Clients MAY associate an id with individual nested entities in the
@@ -4796,7 +4882,7 @@ payload unless explicitly requested with [`$expand`](#SystemQueryOptionexpand).
Instead, the values are generally read or written through URLs.
::: example
-Example <a id="entityWithStreamProperty" href="#entityWithStreamProperty">80</a>: read an entity and select a stream property
+Example <a id="entityWithStreamProperty" href="#entityWithStreamProperty">81</a>: read an entity and select a stream property
```
GET http://host/service/Products(1)?$select=Thumbnail
@@ -4827,7 +4913,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 81: directly read a stream property of an entity
+Example 82: directly read a stream property of an entity
```
GET http://host/service/Products(1)/Thumbnail
@@ -4878,7 +4964,7 @@ attempts to set the property to null and results in an error if the
property is non-nullable.
::: example
-Example 82: delete the stream value using the media edit link retrieved in [example 80](#entityWithStreamProperty)
+Example 83: delete the stream value using the media edit link retrieved in [example 81](#entityWithStreamProperty)
```
DELETE http://server/uploads/Thumbnail546.jpg
@@ -5032,7 +5118,7 @@ ordinal number indexes from the end of the collection, with -1
representing an insert as the last item in the collection.
::: example
-Example 83: Insert a new email address at the second position
+Example 84: Insert a new email address at the second position
```json
POST /service/Customers('ALFKI')/EmailAddresses?$index=1
@@ -5194,7 +5280,7 @@ semantics described in [Update a Collection of
Entities](#UpdateaCollectionofEntities) applies.
::: example
-Example 84: change the color of all beige-brown products
+Example 85: change the color of all beige-brown products
```json
PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
@@ -5240,7 +5326,7 @@ The request resource path of the collection MAY contain type-cast or
filter segments to subset the collection.
::: example
-Example 85: delete all products older than 3
+Example 86: delete all products older than 3
```
DELETE /service/Products/$filter(Age gt 3)/$each
@@ -5292,7 +5378,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 86: the function `MostRecentOrder` can be bound to any URL that
+Example 87: the function `MostRecentOrder` can be bound to any URL that
identifies a `SampleModel.Customer`
```xml
<Function Name="MostRecentOrder" IsBound="true">
@@ -5303,7 +5389,7 @@ identifies a `SampleModel.Customer`
:::
::: example
-Example 87: invoke the `MostRecentOrder` function with the value of the
+Example 88: invoke the `MostRecentOrder` function with the value of the
binding parameter `customer` being the entity identified by
`http://host/service/Customers(6)`
```
@@ -5312,7 +5398,7 @@ GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()
:::
::: example
-Example 88: the function `Comparison` can be bound to any URL that
+Example 89: the function `Comparison` can be bound to any URL that
identifies a collection of entities
```xml
<Function Name="Comparison" IsBound="true">
@@ -5323,7 +5409,7 @@ identifies a collection of entities
:::
::: example
-Example 89: invoke the `Comparison` function on the set of red products
+Example 90: invoke the `Comparison` function on the set of red products
```
GET http://host/service/Products/$filter(Color eq 'Red')/Diff.Comparison()
```
@@ -5346,7 +5432,7 @@ result type of the bound operation. If the bound operation returns a
collection, the response is a collection of collections.
::: example
-Example 90: invoke the `MostRecentOrder` function on each entity in the
+Example 91: invoke the `MostRecentOrder` function on each entity in the
entity set `Customers`
```
GET http://host/service/Customers/$each/SampleModel.MostRecentOrder()
@@ -5374,7 +5460,7 @@ or entity collection within the payload. The representation of an action
or function depends on the [format](#Formats).
::: example
-Example 91: given a `GET` request to
+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
@@ -5401,7 +5487,7 @@ Services can advertise that a function or action is not available for a
particular instance by setting its value to null.
::: example
-Example 92: the `SampleEntities.MostRecentOrder` function is not
+Example 93: the `SampleEntities.MostRecentOrder` function is not
available for customer `ALFKI`
```json
{
@@ -5485,7 +5571,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 93: add a new item to the list of items of the shopping cart
+Example 94: 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
@@ -5534,7 +5620,7 @@ Each parameter value is represented as a name/value pair in the format
and `Value` is the parameter value.
::: example
-Example 94: invoke a `Sales.EmployeesByManager` function which takes a
+Example 95: invoke a `Sales.EmployeesByManager` function which takes a
single `ManagerID` parameter via the function import
`EmployeesByManager`
```
@@ -5543,7 +5629,7 @@ GET http://host/service/EmployeesByManager(ManagerID=3)
:::
::: example
-Example 95: return all Customers whose `City` property returns
+Example 96: return all Customers whose `City` property returns
`Western` when passed to the `Sales.SalesRegion` function
```
GET http://host/service/Customers?
@@ -5556,7 +5642,7 @@ parameter value. The value for the alias is specified as a separate
query option using the name of the parameter alias.
::: example
-Example 96: invoke a `Sales.EmployeesByManager` function via the
+Example 97: invoke a `Sales.EmployeesByManager` function via the
function import `EmployeesByManager`, passing 3 for the `ManagerID`
parameter
```
@@ -5576,7 +5662,7 @@ optional `$` prefix), the parameter name MUST be prefixed with an at
(`@`) sign.
::: example
-Example 97: invoke a `Sales.EmployeesByManager` function via the
+Example 98: invoke a `Sales.EmployeesByManager` function via the
function import `EmployeesByManager`, passing 3 for the `ManagerID`
parameter using the implicit parameter alias
```
@@ -5716,7 +5802,7 @@ collection as a whole is transported in the [`ETag`](#HeaderETag) header of a
collection response.
::: example
-Example 98: invoke the `SampleEntities.CreateOrder` action using
+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
@@ -5863,7 +5949,7 @@ format](#MultipartBatchFormat) MUST contain a
[RFC2046](#rfc2046).
::: example
-Example 99: multipart batch request
+Example 100: multipart batch request
```
POST /service/$batch HTTP/1.1
Host: odata.org
@@ -5878,7 +5964,7 @@ A batch request using the JSON batch format MUST contain a
`Content-Type` header specifying a content type of `application/json`.
::: example
-Example 100: JSON batch request
+Example 101: JSON batch request
```
POST /service/$batch HTTP/1.1
Host: odata.org
@@ -5933,7 +6019,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 105](#batchcontentid).
+that contains such a reference. See [example 106](#batchcontentid).
If the `$`-prefixed request identifier is identical to the name of a
top-level system resource (`$batch`, `$crossjoin`, `$all`, `$entity`,
@@ -6034,7 +6120,7 @@ set can use one of the following three formats:
- Absolute URI with schema, host, port, and absolute resource path.
::: example
-Example 101:
+Example 102:
```
GET https://host:1234/path/service/People(1) HTTP/1.1
```
@@ -6043,7 +6129,7 @@ GET https://host:1234/path/service/People(1) HTTP/1.1
- Absolute resource path and separate `Host` header
::: example
-Example <a id="batchhost" href="#batchhost">102</a>:
+Example <a id="batchhost" href="#batchhost">103</a>:
```json
PATCH /path/service/People(1) HTTP/1.1
Host: myserver.mydomain.org:1234
@@ -6056,7 +6142,7 @@ Content-Type: application/json
- Resource path relative to the batch request URI.
::: example
-Example 103:
+Example 104:
```
DELETE People(1) HTTP/1.1
```
@@ -6081,7 +6167,7 @@ processor may choose to disallow chunked encoding to be used by such
HTTP requests.
::: example
-Example <a id="batchRequest" href="#batchRequest">104</a>: a batch request that contains the following individual
+Example <a id="batchRequest" href="#batchRequest">105</a>: a batch request that contains the following individual
requests in the order listed
1. A query request
@@ -6160,7 +6246,7 @@ which case they SHOULD advertise this support by specifying the
term applied to the entity container, see [OData-VocCap](#ODataVocCap).
::: example
-Example <a id="batchcontentid" href="#batchcontentid">105</a>: a batch request that contains the following operations in
+Example <a id="batchcontentid" href="#batchcontentid">106</a>: a batch request that contains the following operations in
the order listed:
A change set that contains the following requests:
@@ -6232,7 +6318,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 102](#batchhost)). This gives the effective second request URL
+as in [example 103](#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)`.
:::
@@ -6240,7 +6326,7 @@ URL, which therefore resolves to `http://host/service/Customers('ALFKI')/Orders(
#### <a id="ReferencinganETag" href="#ReferencinganETag">11.7.7.3 Referencing an ETag</a>
::: example
-Example 106: a batch request that contains the following operations in
+Example 107: a batch request that contains the following operations in
the order listed:
- Get an employee (with `Content-ID = 1`)
@@ -6281,7 +6367,7 @@ If-Match: $1
#### <a id="ReferencingResponseBodyValues" href="#ReferencingResponseBodyValues">11.7.7.4 Referencing Response Body Values</a>
::: example
-Example 107: a batch request that contains the following operations in
+Example 108: a batch request that contains the following operations in
the order listed:
- Get an employee (with `Content-ID = 1`)
@@ -6374,11 +6460,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 105](#batchcontentid)).
+URL of the corresponding individual request (see [example 106](#batchcontentid)).
URLs in responses MUST NOT contain `$`-prefixed request identifiers.
::: example
-Example 108: referencing the batch request [example 104](#batchRequest) above, assume all
+Example 109: referencing the batch request [example 105](#batchRequest) above, assume all
the requests except the final query request succeed. In this case the
response would be
```
@@ -6454,7 +6540,7 @@ Since a change set is executed atomically,
a change set.
::: example
-Example 109: referencing the [example 104](#batchRequest) above again, assume that
+Example 110: referencing the [example 105](#batchRequest) above again, assume that
```
HTTP/1.1 202 Accepted
Location: http://service-root/async-monitor-0
diff --git a/docs/odata-protocol/styles/odata.css b/docs/odata-protocol/styles/odata.css
index aa19bb20..2b94769c 100644
--- a/docs/odata-protocol/styles/odata.css
+++ b/docs/odata-protocol/styles/odata.css
@@ -1,3 +1,7 @@
+:root {
+ --indent: 40px;
+}
+
a:target,
span:target {
background-color: yellow;
@@ -168,11 +172,31 @@ td > code {
.example pre,
.rep {
- margin-left: 40px;
+ margin-left: var(--indent);
+}
+
+.caption p {
+ margin-left: var(--indent);
+ margin-bottom: -1em;
+}
+
+.side-by-side {
+ margin: -1em 0;
+}
+
+.side-by-side:after {
+ content: "";
+ display: block;
+ clear: both;
+}
+
+.side-by-side > div {
+ width: 50%;
+ float: left;
}
.indent {
- margin-left: 40px;
+ margin-left: var(--indent);
}
td pre {
@@ -195,7 +219,7 @@ mjx-container {
mjx-container[display="true"] {
text-align: left !important;
- margin-left: 40px !important;
+ margin-left: var(--indent) !important;
}
code .er {
@@ -247,6 +271,7 @@ h6 {
page-break-after: avoid;
}
+.side-by-side,
td {
page-break-inside: avoid;
}
diff --git a/docs/odata-temporal-ext/styles/odata.css b/docs/odata-temporal-ext/styles/odata.css
index aa19bb20..2b94769c 100644
--- a/docs/odata-temporal-ext/styles/odata.css
+++ b/docs/odata-temporal-ext/styles/odata.css
@@ -1,3 +1,7 @@
+:root {
+ --indent: 40px;
+}
+
a:target,
span:target {
background-color: yellow;
@@ -168,11 +172,31 @@ td > code {
.example pre,
.rep {
- margin-left: 40px;
+ margin-left: var(--indent);
+}
+
+.caption p {
+ margin-left: var(--indent);
+ margin-bottom: -1em;
+}
+
+.side-by-side {
+ margin: -1em 0;
+}
+
+.side-by-side:after {
+ content: "";
+ display: block;
+ clear: both;
+}
+
+.side-by-side > div {
+ width: 50%;
+ float: left;
}
.indent {
- margin-left: 40px;
+ margin-left: var(--indent);
}
td pre {
@@ -195,7 +219,7 @@ mjx-container {
mjx-container[display="true"] {
text-align: left !important;
- margin-left: 40px !important;
+ margin-left: var(--indent) !important;
}
code .er {
@@ -247,6 +271,7 @@ h6 {
page-break-after: avoid;
}
+.side-by-side,
td {
page-break-inside: avoid;
}
diff --git a/docs/odata-url-conventions/styles/odata.css b/docs/odata-url-conventions/styles/odata.css
index aa19bb20..2b94769c 100644
--- a/docs/odata-url-conventions/styles/odata.css
+++ b/docs/odata-url-conventions/styles/odata.css
@@ -1,3 +1,7 @@
+:root {
+ --indent: 40px;
+}
+
a:target,
span:target {
background-color: yellow;
@@ -168,11 +172,31 @@ td > code {
.example pre,
.rep {
- margin-left: 40px;
+ margin-left: var(--indent);
+}
+
+.caption p {
+ margin-left: var(--indent);
+ margin-bottom: -1em;
+}
+
+.side-by-side {
+ margin: -1em 0;
+}
+
+.side-by-side:after {
+ content: "";
+ display: block;
+ clear: both;
+}
+
+.side-by-side > div {
+ width: 50%;
+ float: left;
}
.indent {
- margin-left: 40px;
+ margin-left: var(--indent);
}
td pre {
@@ -195,7 +219,7 @@ mjx-container {
mjx-container[display="true"] {
text-align: left !important;
- margin-left: 40px !important;
+ margin-left: var(--indent) !important;
}
code .er {
@@ -247,6 +271,7 @@ h6 {
page-break-after: avoid;
}
+.side-by-side,
td {
page-break-inside: avoid;
}
diff --git a/odata-json-format/7 Structural Property.md b/odata-json-format/7 Structural Property.md
index 7942d320..b09ce931 100644
--- a/odata-json-format/7 Structural Property.md
+++ b/odata-json-format/7 Structural Property.md
@@ -381,7 +381,7 @@ Content-Type: application/json
:::
::: example
-Example ##ex: submit a partial update request to:
+Example ##ex_deepupdate: submit a partial update request to:
- modify the name of an existing category
- assign an existing product with the id 42 to the category
- assign an existing product 57 to the category and update its name
diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md
index addff612..4c61d0e7 100644
--- a/odata-protocol/11.4 Data Modification.md
+++ b/odata-protocol/11.4 Data Modification.md
@@ -449,6 +449,9 @@ references specified in a successful update request represents the full
set of entities to be related according to that relationship and MUST
NOT include added links, deleted links, or deleted entities.
+If a navigation property is absent from a `PUT` or `PATCH` request payload, the referenced
+or contained entity, or the collection thereof, remains unchanged by a successful update.
+
::: example
Example ##ex: using the JSON format, a 4.01 `PATCH` request can update a
manager entity. Following the update, the manager has three direct
@@ -545,7 +548,90 @@ nested delta representation to:
]
}
```
+:::
+::: example
+Example ##ex: 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#EntityReference]), without specifying all
+its structural properties in `PUT` semantics.
+
+The following JSON payload changes the name of a category and the products belonging
+to it. (Compare this to [OData-JSON, example #OData-JSON#deepupdate].)
+The effect would be the same if the `@context` was omitted from the request.
+:::: side-by-side
+::::: caption
+Request
+```json
+PUT http://host/service/Categories(6)?$expand=Products
+Content-Type: application/json
+
+{
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "@context": "$metadata#$ref",
+ "@id": "Products(57)"
+ }
+ ]
+}
+```
+:::::
+::::: caption
+Response
+```json
+{
+ "@context": "$metadata#Categories/$entity",
+ "CategoryID": 6,
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "ProductID": 57,
+ "Name": "Widgets"
+ }
+ ]
+}
+```
+:::::
+::::
+
+If `Products` was a containment navigation property, the request and response
+would be the same, except that the `@id` would likely be relative to the category,
+for example, `Categories(6)/Products(57)`.
+
+If the targeted entity in the payload contains some structural properties,
+`PUT` resets all its other structural properties. The following alternative
+payload resets the product name.
+The effect would be the same if the `@id` was omitted from the request.
+:::: side-by-side
+```json
+PUT http://host/service/Categories(6)?$expand=Products
+Content-Type: application/json
+
+{
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "@id": "Products(57)",
+ "ProductID": 57
+ }
+ ]
+}
+```
+```json
+{
+ "@context": "$metadata#Categories/$entity",
+ "CategoryID": 6,
+ "Name": "UpdatedCategory",
+ "Products": [
+ {
+ "ProductID": 57,
+ "Name": null
+ }
+ ]
+}
+```
+::::
:::
Clients MAY associate an id with individual nested entities in the
diff --git a/package-lock.json b/package-lock.json
index 643ad09a..791d70a2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -993,9 +993,10 @@
"integrity": "sha512-ASFBup0Mz1uyiIjANan1jzLQami9z1PoYSZCiiYW2FczPbenXc45FZdBZLzOT+r6+iciuEModtmCti+hjaAk0A=="
},
"node_modules/cookie": {
- "version": "0.6.0",
- "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.6.0.tgz",
- "integrity": "sha512-U71cyTamuh1CRNCfpGY6to28lxvNwPG4Guz/EVjgf3Jmzv0vlDp1atT9eS5dDjMYHucpHbWns6Lwf3BKz6svdw==",
+ "version": "0.7.1",
+ "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.1.tgz",
+ "integrity": "sha512-6DnInpx7SJ2AK3+CTUE/ZM0vWTUboZCegxhC2xiIydHR9jNuTAASBrfEpHhiGOZw/nX51bHt6YQl8jsGo4y/0w==",
+ "license": "MIT",
"engines": {
"node": ">= 0.6"
}
@@ -1351,9 +1352,9 @@
}
},
"node_modules/express": {
- "version": "4.21.0",
- "resolved": "https://registry.npmjs.org/express/-/express-4.21.0.tgz",
- "integrity": "sha512-VqcNGcj/Id5ZT1LZ/cfihi3ttTn+NJmkli2eZADigjq29qTlWi/hAQ43t/VLPq8+UX06FCEx3ByOYet6ZFblng==",
+ "version": "4.21.1",
+ "resolved": "https://registry.npmjs.org/express/-/express-4.21.1.tgz",
+ "integrity": "sha512-YSFlK1Ee0/GC8QaO91tHcDxJiE/X4FbpAyQWkxAvG6AXCuR65YzK8ua6D9hvi/TzUfZMpc+BwuM1IPw8fmQBiQ==",
"license": "MIT",
"dependencies": {
"accepts": "~1.3.8",
@@ -1361,7 +1362,7 @@
"body-parser": "1.20.3",
"content-disposition": "0.5.4",
"content-type": "~1.0.4",
- "cookie": "0.6.0",
+ "cookie": "0.7.1",
"cookie-signature": "1.0.6",
"debug": "2.6.9",
"depd": "2.0.0",
diff --git a/styles/odata.css b/styles/odata.css
index aa19bb20..2b94769c 100644
--- a/styles/odata.css
+++ b/styles/odata.css
@@ -1,3 +1,7 @@
+:root {
+ --indent: 40px;
+}
+
a:target,
span:target {
background-color: yellow;
@@ -168,11 +172,31 @@ td > code {
.example pre,
.rep {
- margin-left: 40px;
+ margin-left: var(--indent);
+}
+
+.caption p {
+ margin-left: var(--indent);
+ margin-bottom: -1em;
+}
+
+.side-by-side {
+ margin: -1em 0;
+}
+
+.side-by-side:after {
+ content: "";
+ display: block;
+ clear: both;
+}
+
+.side-by-side > div {
+ width: 50%;
+ float: left;
}
.indent {
- margin-left: 40px;
+ margin-left: var(--indent);
}
td pre {
@@ -195,7 +219,7 @@ mjx-container {
mjx-container[display="true"] {
text-align: left !important;
- margin-left: 40px !important;
+ margin-left: var(--indent) !important;
}
code .er {
@@ -247,6 +271,7 @@ h6 {
page-break-after: avoid;
}
+.side-by-side,
td {
page-break-inside: avoid;
}
From d6793e40332b6c2db9bcfc9aaa6ce0f7e5457051 Mon Sep 17 00:00:00 2001
From: Ralf Handl <ralf.handl@sap.com>
Date: Tue, 29 Oct 2024 14:25:59 +0100
Subject: [PATCH 07/19] Add Node 22 (#2020)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Node 22 is now current, Node 20 is active LTS, see
https://github.com/nodejs/release?tab=readme-ov-file#release-schedule
---------
Co-authored-by: Heiko Theißen <heiko.theissen@sap.com>
---
.github/workflows/nodejs.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml
index 20d0fa87..17c6e6e0 100644
--- a/.github/workflows/nodejs.yml
+++ b/.github/workflows/nodejs.yml
@@ -8,7 +8,7 @@ jobs:
strategy:
matrix:
- node-version: [20.x]
+ node-version: [20.x, 22.x]
steps:
- uses: actions/checkout@v4
From f4ad5e1e4665e1a69f63c357d5a082f6edccbb3d Mon Sep 17 00:00:00 2001
From: Ralf Handl <ralf.handl@sap.com>
Date: Tue, 29 Oct 2024 17:29:13 +0100
Subject: [PATCH 08/19] Only Node 22 (#2022)
---
.github/workflows/nodejs.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml
index 17c6e6e0..ab9be05d 100644
--- a/.github/workflows/nodejs.yml
+++ b/.github/workflows/nodejs.yml
@@ -8,7 +8,7 @@ jobs:
strategy:
matrix:
- node-version: [20.x, 22.x]
+ node-version: [22.x]
steps:
- uses: actions/checkout@v4
From d3177e0b009ab58818d56a4ed3912eaf0ea6f67e Mon Sep 17 00:00:00 2001
From: Ralf Handl <ralf.handl@sap.com>
Date: Wed, 6 Nov 2024 18:30:07 +0100
Subject: [PATCH 09/19] 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 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/348">348</a></td>
</tr>
<tr class="odd">
+<td><a href="#ReturnType">Section 12.8</a></td>
+<td>Returned collections of entities may contain <code>null</code> values</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/1983">1983</a></td>
+</tr>
+<tr class="even">
<td><a href="#GeoValues">Section 14.3.13</a></td>
<td>Constant Geo values in annotations</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/654">654</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#StreamValues">Section 14.3.14</a></td>
<td>Constant Stream values in annotations</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/654">654</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#PathEvaluation">Section 14.4.1.2</a></td>
<td>New path evaluation rules for annotations targeting annotations and external targeting via container</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/575">575</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#IfThenElse">Section 14.4.7</a></td>
<td>Nested <code>If</code> without else part in collections</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/326">326</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#Conformance">Section 17</a></td>
<td>Additional conformance clauses for version 4.02</td>
<td></td>
@@ -2011,8 +2016,7 @@ <h3><a id="Type.13.5" href="#Type.13.5"><code>$Type</code></a> and <a id="Collec
<p>Absence of the <code>$Type</code> member means the type is <code>Edm.String</code>.</p>
<h3><a id="Nullable.13.7" href="#Nullable.13.7"><code>$Nullable</code></a></h3>
<p>The value of <code>$Nullable</code> is one of the Boolean literals <code>true</code> or <code>false</code>. Absence of the member means <code>false</code>.</p>
-<p>If the return type is a collection of entity types, the <code>$Nullable</code> member has no meaning and MUST NOT be specified.</p>
-<p>For other collection-valued return types the result will always be a collection that MAY be empty. In this case <code>$Nullable</code> applies to items of the collection and specifies whether the collection MAY contain <code>null</code> values.</p>
+<p>For collection-valued return types the result will always be a collection that MAY be empty. In this case <code>$Nullable</code> applies to items of the collection and specifies whether the collection MAY contain <code>null</code> values.</p>
<p>For single-valued return types the value <code>true</code> means that the action or function MAY return a single <code>null</code> value. The value <code>false</code> means that the action or function will never return a <code>null</code> value and instead will fail with an error response if it cannot compute a result.</p>
</div>
<h3><a id="AnnotationCoreIsDelta.13.8" href="#AnnotationCoreIsDelta.13.8">Annotation <code>Core.IsDelta</code></a></h3>
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 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/348">348</a></td>
</tr>
<tr class="even">
+<td><a href="#ReturnType">Section 12.8</a></td>
+<td>Returned collections of entities may contain <code>null</code> values</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/1983">1983</a></td>
+</tr>
+<tr class="odd">
<td><a href="#GeoValues">Section 14.3.13</a></td>
<td>Constant Geo values in annotations</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/654">654</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#StreamValues">Section 14.3.14</a></td>
<td>Constant Stream values in annotations</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/654">654</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#PathEvaluation">Section 14.4.1.2</a></td>
<td>New path evaluation rules for annotations targeting annotations and external targeting via container</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/575">575</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#IfThenElse">Section 14.4.7</a></td>
<td>Nested <code>If</code> without else part in collections</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/326">326</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#Conformance">Section 17</a></td>
<td>Additional conformance clauses for version 4.02</td>
<td></td>
@@ -1897,8 +1902,7 @@ <h3><a id="AttributeType.22.1" href="#AttributeType.22.1">Attribute <code>Type</
<p>For collection-valued return types the value of <code>Type</code> is the character sequence <code>Collection(</code> followed by the qualified name of the return item type, followed by a closing parenthesis <code>)</code>.</p>
<h3><a id="AttributeNullable.22.2" href="#AttributeNullable.22.2">Attribute <code>Nullable</code></a></h3>
<p>The value of <code>Nullable</code> is one of the Boolean literals <code>true</code> or <code>false</code>. Absence of the attribute means <code>true</code>.</p>
-<p>If the return type is a collection of entity types, the <code>Nullable</code> attribute has no meaning and MUST NOT be specified.</p>
-<p>For other collection-valued return types the result will always be a collection that MAY be empty. In this case the <code>Nullable</code> attribute applies to items of the collection and specifies whether the collection MAY contain <code>null</code> values.</p>
+<p>For collection-valued return types the result will always be a collection that MAY be empty. In this case the <code>Nullable</code> attribute applies to items of the collection and specifies whether the collection MAY contain <code>null</code> values.</p>
<p>For single-valued return types the value <code>true</code> means that the action or function MAY return a single <code>null</code> value. The value <code>false</code> means that the action or function will never return a <code>null</code> value and instead will fail with an error response if it cannot compute a result.</p>
</div>
<h3><a id="AnnotationCoreIsDelta.22.3" href="#AnnotationCoreIsDelta.22.3">Annotation <code>Core.IsDelta</code></a></h3>
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?= <heiko.theissen@sap.com>
Date: Wed, 6 Nov 2024 18:35:34 +0100
Subject: [PATCH 10/19] 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 <ralf.handl@sap.com>
---
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 @@ <h3 id="341-maxlength"><a id="MaxLength" href="#MaxLength">3.4.1 MaxLength</a></
<h3><a id="TypeFacetMembers.1" href="#TypeFacetMembers.1">Type Facet Members</a></h3>
<h3><a id="MaxLength.1.1" href="#MaxLength.1.1"><code>$MaxLength</code></a></h3>
<p>The value of <code>$MaxLength</code> is a positive integer.</p>
-<p>Note: <a href="#ODataCSDL">OData-CSDL-XML</a> defines a symbolic value <code>max</code> 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.</p>
+<p>Note: <a href="https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#MaxLength">OData-CSDLXML, section 3.4.1</a> defines a symbolic value <code>max</code> 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.</p>
</div>
</details>
<details open><summary>
@@ -1014,7 +1014,7 @@ <h2 id="41-reference"><a id="Reference" href="#Reference">4.1 Reference</a></h2>
<p>A reference to an external CSDL document allows to bring part of the referenced document’s content into the scope of the referencing document.</p>
<p>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.</p>
<p>A reference MAY be annotated.</p>
-<p>The <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation, defined in <a href="#ODataVocCore">OData-VocCore</a>, MAY be used to indicate a particular version of the referenced document. If the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation is present, the <code>$schemaversion</code> system query option, defined <a href="#ODataProtocol">OData-Protocol</a>, SHOULD be used when retrieving the referenced schema document.</p>
+<p>The <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation, defined in <a href="#ODataVocCore">OData-VocCore</a>, MAY be used to indicate a particular version of the referenced document. If the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation is present, the <code>$schemaversion</code> system query option, defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion">OData-Protocol, section 11.2.12</a>, SHOULD be used when retrieving the referenced schema document.</p>
<div class="varjson rep">
<h3><a id="Reference.2.3" href="#Reference.2.3"><code>$Reference</code></a></h3>
<p>The value of <code>$Reference</code> 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 <code>$Reference</code>. The value of each member is a reference object.</p>
@@ -1295,7 +1295,7 @@ <h2 id="63-open-entity-type"><a id="OpenEntityType" href="#OpenEntityType">6.3 O
</summary>
<p>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.</p>
<p>An entity type derived from an open entity type MUST indicate that it is also open.</p>
-<p>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 <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel">OData-Protocol, section 3</a>.</p>
<section class="varjson rep">
<h3><a id="OpenType.5.3" href="#OpenType.5.3"><code>$OpenType</code></a></h3>
<p>The value of <code>$OpenType</code> is one of the Boolean literals <code>true</code> or <code>false</code>. Absence of the member means <code>false</code>.</p>
@@ -1304,7 +1304,7 @@ <h3><a id="OpenType.5.3" href="#OpenType.5.3"><code>$OpenType</code></a></h3>
<details open><summary>
<h2 id="64-media-entity-type"><a id="MediaEntityType" href="#MediaEntityType">6.4 Media Entity Type</a></h2>
</summary>
-<p>An entity type that does not specify a base type MAY indicate that it is a media entity type. <em>Media entities</em> 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 <code>Edm.Stream</code> 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 <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>An entity type that does not specify a base type MAY indicate that it is a media entity type. <em>Media entities</em> 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 <code>Edm.Stream</code> 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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#RequestingtheMediaStreamofaMediaEntityusingvalue">OData-Protocol, section 11.2.3</a>.</p>
<p>An entity type derived from a media entity type MUST indicate that it is also a media entity type.</p>
<p>Media entity types MAY specify a list of acceptable media types using an annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AcceptableMediaTypes"><code>Core.AcceptableMediaTypes</code></a>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
<section class="varjson rep">
@@ -1335,7 +1335,7 @@ <h2 id="65-key"><a id="Key" href="#Key">6.5 Key</a></h2>
<li><code>Edm.String</code></li>
<li><code>Edm.TimeOfDay</code></li>
</ul>
-<p>Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in <a href="#ODataProtocol">OData-Protocol</a>) MUST be language independent.</p>
+<p>Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences">OData-Protocol, section 4.1</a>) MUST be language independent.</p>
<p>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.</p>
<p>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.</p>
<p>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 <a href="#SimpleIdentifier">simple identifier</a> and MUST be unique within the set of aliases, structural and navigation properties of the declaring entity type and any of its base types.</p>
@@ -1490,7 +1490,7 @@ <h2 id="73-default-value"><a id="DefaultValue" href="#DefaultValue">7.3 Default
<p>If no value is specified, the client SHOULD NOT assume a default value.</p>
<section class="varjson rep">
<h3><a id="DefaultValue.6.4" href="#DefaultValue.6.4"><code>$DefaultValue</code></a></h3>
-<p>The value of <code>$DefaultValue</code> is the type-specific JSON representation of the default value of the property, see <a href="#ODataJSON">OData-JSON</a>. For properties of type <code>Edm.Decimal</code> and <code>Edm.Int64</code> the representation depends on the media type parameter <a href="#ControllingtheRepresentationofNumbers"><code>IEEE754Compatible</code></a>.</p>
+<p>The value of <code>$DefaultValue</code> is the type-specific JSON representation of the default value of the property, see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue">OData-JSON, section 7.1</a>. For properties of type <code>Edm.Decimal</code> and <code>Edm.Int64</code> the representation depends on the media type parameter <a href="#ControllingtheRepresentationofNumbers"><code>IEEE754Compatible</code></a>.</p>
</section>
</details>
</details>
@@ -1583,7 +1583,7 @@ <h2 id="84-containment-navigation-property"><a id="ContainmentNavigationProperty
</summary>
<p>A navigation property MAY indicate that instances of its declaring structured type contain the targets of the navigation property, in which case the navigation property is called a <em>containment navigation property</em>.</p>
<p>Containment navigation properties define an implicit entity set for each instance of its declaring structured type. This implicit entity set is identified by the read URL of the navigation property for that structured type instance.</p>
-<p>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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURLforContainedEntities">OData-URL, section 4.3.2</a>.</p>
<p>Entity types used in collection-valued containment navigation properties MUST have a <a href="#Key">key</a> defined.</p>
<p>For items of an ordered collection of complex types (those annotated with the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Ordered"><code>Core.Ordered</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a> 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.</p>
<p>OData 4.0 responses MUST NOT specify a complex type declaring a containment navigation property as the type of a collection-valued property.</p>
@@ -1751,7 +1751,7 @@ <h2 id="93-open-complex-type"><a id="OpenComplexType" href="#OpenComplexType">9.
</summary>
<p>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.</p>
<p>A complex type derived from an open complex type MUST indicate that it is also open.</p>
-<p>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 <a href="#ODataProtocol">OData‑Protocol</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel">OData-Protocol, section 3</a>.</p>
<section class="varjson rep">
<h3><a id="OpenType.8.3" href="#OpenType.8.3"><code>$OpenType</code></a></h3>
<p>The value of <code>$OpenType</code> is one of the Boolean literals <code>true</code> or <code>false</code>. Absence of the member means <code>false</code>.</p>
@@ -2335,7 +2335,7 @@ <h1 id="14-vocabulary-and-annotation"><a id="VocabularyandAnnotation" href="#Voc
</summary>
<p>Vocabularies and annotations provide the ability to annotate metadata as well as instance data, and define a powerful extensibility point for OData. An <a href="#Annotation"><em>annotation</em></a> applies a <a href="#Term"><em>term</em></a> to a model element and defines how to calculate a value for the applied term.</p>
<p><em>Metadata annotations</em> 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.</p>
-<p><em>Instance annotations</em> are terms applied to a particular instance within an OData payload, such as described in <a href="#ODataJSON">OData-JSON</a>. 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.</p>
+<p><em>Instance annotations</em> are terms applied to a particular instance within an OData payload, such as described in <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InstanceAnnotations">OData-JSON, section 20</a>. 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.</p>
<p>A <em>vocabulary</em> is a schema containing a set of terms where each <a href="#Term">term</a> 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 <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p>A <a href="#Term">term</a> can be used to:</p>
<ul>
@@ -2408,8 +2408,8 @@ <h3><a id="Nullable.20.3" href="#Nullable.20.3"><code>$Nullable</code></a></h3>
<p>For single-valued terms the value <code>true</code> means that annotations may have the <code>null</code> value.</p>
<p>For collection-valued terms the annotation value will always be a collection that MAY be empty. In this case <code>$Nullable</code> applies to items of the collection and specifies whether the collection MAY contain <code>null</code> values.</p>
<h3><a id="DefaultValue.20.4" href="#DefaultValue.20.4"><code>$DefaultValue</code></a></h3>
-<p>The value of <code>$DefaultValue</code> is the type-specific JSON representation of the default value of the term, see <a href="#ODataJSON">OData-JSON</a>.</p>
-<p>Note: the <code>$DefaultValue</code> member is purely for documentation and isomorphy to <a href="#ODataCSDL">OData-CSDLXML</a>. Annotations in CSDL JSON documents MUST always specify an explicit value.</p>
+<p>The value of <code>$DefaultValue</code> is the type-specific JSON representation of the default value of the term, see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue">OData-JSON, section 7.1</a>.</p>
+<p>Note: the <code>$DefaultValue</code> member is purely for documentation and isomorphy to <a href="https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#DefaultValue">OData-CSDLXML, section 7.3</a>. Annotations in CSDL JSON documents MUST always specify an explicit value.</p>
</div>
<details open><summary>
<h3 id="1411-specialized-term"><a id="SpecializedTerm" href="#SpecializedTerm">14.1.1 Specialized Term</a></h3>
@@ -2935,7 +2935,7 @@ <h3 id="14312-time-of-day"><a id="TimeofDay" href="#TimeofDay">14.3.12 Time of D
<h3 id="14313-geo-values"><a id="GeoValues" href="#GeoValues">14.3.13 Geo Values</a></h3>
</summary>
<div class="varjson rep">
-<p>Values are represented as GeoJSON, see <a href="#ODataJSON">OData-JSON</a>.</p>
+<p>Values are represented as GeoJSON, see <a href="#rfc7946">RFC7946</a>.</p>
</div>
<div class="varjson example">
<p>Example 58:</p>
@@ -2946,7 +2946,7 @@ <h3 id="14313-geo-values"><a id="GeoValues" href="#GeoValues">14.3.13 Geo Values
<h3 id="14314-stream-values"><a id="StreamValues" href="#StreamValues">14.3.14 Stream Values</a></h3>
</summary>
<div class="varjson rep">
-<p>Constant values of type <code>Edm.Stream</code> are represented according to <a href="#ODataJSON">OData-JSON</a> and MUST be accompanied by the <code>mediaContentType</code> control information to indicate how the stream value is to be interpreted.</p>
+<p>Constant values of type <code>Edm.Stream</code> are represented according to <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#StreamProperty">OData-JSON, section 9</a> and MUST be accompanied by the <code>mediaContentType</code> control information to indicate how the stream value is to be interpreted.</p>
</div>
<p>The annotation (property) being assigned a stream value MUST be annotated with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#MediaType"><code>Core.MediaType</code></a> and the media type of the stream as its value.</p>
<div class="varjson example">
@@ -2977,7 +2977,7 @@ <h3 id="1441-path-expressions"><a id="PathExpressions" href="#PathExpressions">1
<details open><summary>
<h4 id="14411-path-syntax"><a id="PathSyntax" href="#PathSyntax">14.4.1.1 Path Syntax</a></h4>
</summary>
-<p>Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see <a href="#ODataURL">OData-URL</a>.</p>
+<p>Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#PathExpressions">OData-URL, section 5.1.1.15</a>.</p>
<p>A path MUST be composed of zero or more path segments joined together by forward slashes (<code>/</code>).</p>
<p>Paths starting with a forward slash (<code>/</code>) 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.</p>
<div class="example">
@@ -3024,7 +3024,7 @@ <h4 id="14411-path-syntax"><a id="PathSyntax" href="#PathSyntax">14.4.1.1 Path S
<pre><code>…/Items@Core.Description</code></pre>
<pre><code>…/Items/@Core.Description</code></pre>
</div>
-<p>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 <a href="#ODataURL">OData-URL</a>. 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, <em>not</em> relative to the instance identified by the preceding path part.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL">OData-URL, section 4.3.1</a>. 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, <em>not</em> relative to the instance identified by the preceding path part.</p>
<div class="example">
<p>Example 67: instance path with entity set and key predicate</p>
<pre><code>/self.container/SettingsCollection('FeatureXxx')/IsAvailable</code></pre>
@@ -3237,7 +3237,7 @@ <h3 id="1442-comparison-and-logical-operators"><a id="ComparisonandLogicalOperat
<tr><td><code>In</code></td><td>Is in collection </td></tr>
</table>
-<p>The <code>And</code> and <code>Or</code> operators require two operand expressions that evaluate to Boolean values. The <code>Not</code> operator requires a single operand expression that evaluates to a Boolean value. For details on null handling for comparison operators see <a href="#ODataURL">OData-URL</a>.</p>
+<p>The <code>And</code> and <code>Or</code> operators require two operand expressions that evaluate to Boolean values. The <code>Not</code> operator requires a single operand expression that evaluates to a Boolean value. For details on null handling for comparison operators see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LogicalOperators">OData-URL, section 5.1.1.1</a>.</p>
<p>The other comparison operators require two operand expressions that evaluate to comparable values.</p>
<div class="varjson rep">
<h3><a id="And.21.2" href="#And.21.2"><code>$And</code></a> and <a id="Or.21.3" href="#Or.21.3"><code>$Or</code></a></h3>
@@ -3349,7 +3349,7 @@ <h3><a id="Eq.21.5" href="#Eq.21.5"><code>$Eq</code></a>, <a id="Ne.21.6" href="
<details open><summary>
<h3 id="1443-arithmetic-operators"><a id="ArithmeticOperators" href="#ArithmeticOperators">14.4.3 Arithmetic Operators</a></h3>
</summary>
-<p>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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ArithmeticOperators">OData-URL, section 5.1.1.2</a>.</p>
<table>
<thead>
<tr class="header">
@@ -3479,7 +3479,7 @@ <h3><a id="Apply.21.20" href="#Apply.21.20"><code>$Apply</code></a> and <a id="F
<details open><summary>
<h4 id="14441-canonical-functions"><a id="CanonicalFunctions" href="#CanonicalFunctions">14.4.4.1 Canonical Functions</a></h4>
</summary>
-<p>All canonical functions defined in <a href="#ODataURL">OData-URL</a> can be used as client-side functions, qualified with the namespace <code>odata</code>. The semantics of these client-side functions is identical to their counterpart function defined in <a href="#ODataURL">OData-URL</a>.</p>
+<p>All canonical functions defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions">OData-URL, section 5.1.1.4</a> can be used as client-side functions, qualified with the namespace <code>odata</code>. The semantics of these client-side functions is identical to their counterpart function defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions">OData-URL, section 5.1.1.4</a>.</p>
<p>For example, the <code>odata.concat</code> client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or enumeration type. It returns a value of type <code>Edm.String</code> that is the concatenation of the literal representations of the results of the argument expressions. Values of primitive types other than <code>Edm.String</code> are represented according to the appropriate alternative in the <code>primitiveValue</code> rule of <a href="#ODataABNF">OData-ABNF</a>, i.e. <code>Edm.Binary</code> as <code>binaryValue</code>, <code>Edm.Boolean</code> as <code>booleanValue</code> etc.</p>
<div class="varjson example">
<p>Example 77:</p>
@@ -3602,7 +3602,7 @@ <h4 id="14444-function-odatauriencode"><a id="FunctionodatauriEncode" href="#Fun
<details open><summary>
<h3 id="1445-cast"><a id="Cast" href="#Cast">14.4.5 Cast</a></h3>
</summary>
-<p>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 <code>cast</code> canonical function defined in <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <code>cast</code> canonical function defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#cast">OData-URL, section 5.1.1.10.1</a>.</p>
<section class="varjson rep">
<h3><a id="Cast.21.22" href="#Cast.21.22"><code>$Cast</code></a></h3>
<p>Cast expressions are represented as an object with a member <code>$Cast</code> whose value is an annotation expression, a member <code>$Type</code> whose value is a string containing the qualified type name, and optionally a member <code>$Collection</code> with a value of <code>true</code>.</p>
@@ -3790,7 +3790,7 @@ <h3 id="14412-record"><a id="Record" href="#Record">14.4.12 Record</a></h3>
<p>For collection-valued properties the absence of a property value expression is equivalent to specifying an empty collection as its value.</p>
<div class="varjson rep">
<p>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.</p>
-<p>The type of a record expression is represented as the <code>type</code> control information, see <a href="#ODataJSON">OData-JSON</a>.</p>
+<p>The type of a record expression is represented as the <code>type</code> control information, see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationtypeodatatype">OData-JSON, section 4.6.3</a>.</p>
<p>It MAY contain <a href="#Annotation">annotations</a> for itself and its members. Annotations for record members are prefixed with the member name.</p>
</div>
<div class="varjson example">
@@ -4283,6 +4283,8 @@ <h6><span id="rfc6570">RFC6570</span></h6>
<h6><span id="rfc7493">RFC7493</span></h6>
<p><em>The I-JSON Message Format“, RFC 7493, DOI 10.17487/RFC7493, March 2015</em>.<br />
<a href="https://www.rfc-editor.org/info/rfc7493">https://www.rfc-editor.org/info/rfc7493</a>.</p>
+<h6><span id="rfc7946">RFC7946</span></h6>
+<p><em>Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, “The GeoJSON Format”, RFC 7946, DOI 10.17487/RFC7946, August 2016</em>. <a href="https://www.rfc-editor.org/info/rfc7946">https://www.rfc-editor.org/info/rfc7946</a>.</p>
<h6><span id="rfc8174">RFC8174</span></h6>
<p><em>Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017</em>.<br />
<a href="https://www.rfc-editor.org/info/rfc8174">https://www.rfc-editor.org/info/rfc8174</a>.</p>
@@ -4482,7 +4484,7 @@ <h2 id="c1-special-thanks"><a id="SpecialThanks" href="#SpecialThanks">C.1 Speci
<li>Jens Ittel (SAP SE)</li>
<li>Patric Ksinsik (SAP SE)</li>
</ul>
-<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="#ODataProtocol">ODataProtocol</a>, are gratefully acknowledged.</p>
+<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants">OData-Protocol, section C.2</a>, are gratefully acknowledged.</p>
</details>
<details open><summary>
<h2 id="c2-participants"><a id="Participants" href="#Participants">C.2 Participants</a></h2>
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}
### <a id="OpenType.5.3" href="#OpenType.5.3">`$OpenType`</a>
@@ -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}
### <a id="OpenType.8.3" href="#OpenType.8.3">`$OpenType`</a>
@@ -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:
### <a id="GeoValues" href="#GeoValues">14.3.13 Geo Values</a>
::: {.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:
### <a id="StreamValues" href="#StreamValues">14.3.14 Stream Values</a>
::: {.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.
#### <a id="PathSyntax" href="#PathSyntax">14.4.1.1 Path Syntax</a>
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.
#### <a id="CanonicalFunctions" href="#CanonicalFunctions">14.4.4.1 Canonical Functions</a>
-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}
### <a id="Cast.21.22" href="#Cast.21.22">`$Cast`</a>
@@ -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.
## <a id="Participants" href="#Participants">C.2 Participants</a>
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 @@ <h2 id="41-reference"><a id="Reference" href="#Reference">4.1 Reference</a></h2>
<p>A reference to an external CSDL document allows to bring part of the referenced document’s content into the scope of the referencing document.</p>
<p>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.</p>
<p>A reference MAY be annotated.</p>
-<p>The <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation, defined in <a href="#ODataVocCore">OData-VocCore</a>, MAY be used to indicate a particular version of the referenced document. If the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation is present, the <code>$schemaversion</code> system query option, defined <a href="#ODataProtocol">OData-Protocol</a>, SHOULD be used when retrieving the referenced schema document.</p>
+<p>The <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation, defined in <a href="#ODataVocCore">OData-VocCore</a>, MAY be used to indicate a particular version of the referenced document. If the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion"><code>Core.SchemaVersion</code></a> annotation is present, the <code>$schemaversion</code> system query option, defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion">OData-Protocol, section 11.2.12</a>, SHOULD be used when retrieving the referenced schema document.</p>
<div class="varxml rep">
<h3><a id="ElementedmxReference.4" href="#ElementedmxReference.4">Element <code>edmx:Reference</code></a></h3>
<p>The <code>edmx:Reference</code> element specifies external CSDL documents referenced by the referencing document. The child elements <a href="#IncludedSchema"><code>edmx:Include</code></a> and <a href="#IncludedAnnotations"><code>edmx:IncludeAnnotations</code></a> specify which parts of the referenced document are available for use in the referencing document.</p>
@@ -1238,7 +1238,7 @@ <h2 id="63-open-entity-type"><a id="OpenEntityType" href="#OpenEntityType">6.3 O
</summary>
<p>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.</p>
<p>An entity type derived from an open entity type MUST indicate that it is also open.</p>
-<p>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 <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel">OData-Protocol, section 3</a>.</p>
<section class="varxml rep">
<h3><a id="AttributeOpenType.9.4" href="#AttributeOpenType.9.4">Attribute <code>OpenType</code></a></h3>
<p>The value of <code>OpenType</code> is one of the Boolean literals <code>true</code> or <code>false</code>. Absence of the attribute means <code>false</code>.</p>
@@ -1247,7 +1247,7 @@ <h3><a id="AttributeOpenType.9.4" href="#AttributeOpenType.9.4">Attribute <code>
<details open><summary>
<h2 id="64-media-entity-type"><a id="MediaEntityType" href="#MediaEntityType">6.4 Media Entity Type</a></h2>
</summary>
-<p>An entity type that does not specify a base type MAY indicate that it is a media entity type. <em>Media entities</em> 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 <code>Edm.Stream</code> 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 <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>An entity type that does not specify a base type MAY indicate that it is a media entity type. <em>Media entities</em> 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 <code>Edm.Stream</code> 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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#RequestingtheMediaStreamofaMediaEntityusingvalue">OData-Protocol, section 11.2.3</a>.</p>
<p>An entity type derived from a media entity type MUST indicate that it is also a media entity type.</p>
<p>Media entity types MAY specify a list of acceptable media types using an annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AcceptableMediaTypes"><code>Core.AcceptableMediaTypes</code></a>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
<section class="varxml rep">
@@ -1278,7 +1278,7 @@ <h2 id="65-key"><a id="Key" href="#Key">6.5 Key</a></h2>
<li><code>Edm.String</code></li>
<li><code>Edm.TimeOfDay</code></li>
</ul>
-<p>Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in <a href="#ODataProtocol">OData-Protocol</a>) MUST be language independent.</p>
+<p>Key property values MAY be language-dependent, but their values MUST be unique across all languages and the entity-ids (defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences">OData-Protocol, section 4.1</a>) MUST be language independent.</p>
<p>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.</p>
<p>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.</p>
<p>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 <a href="#SimpleIdentifier">simple identifier</a> and MUST be unique within the set of aliases, structural and navigation properties of the declaring entity type and any of its base types.</p>
@@ -1486,7 +1486,7 @@ <h2 id="84-containment-navigation-property"><a id="ContainmentNavigationProperty
</summary>
<p>A navigation property MAY indicate that instances of its declaring structured type contain the targets of the navigation property, in which case the navigation property is called a <em>containment navigation property</em>.</p>
<p>Containment navigation properties define an implicit entity set for each instance of its declaring structured type. This implicit entity set is identified by the read URL of the navigation property for that structured type instance.</p>
-<p>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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURLforContainedEntities">OData-URL, section 4.3.2</a>.</p>
<p>Entity types used in collection-valued containment navigation properties MUST have a <a href="#Key">key</a> defined.</p>
<p>For items of an ordered collection of complex types (those annotated with the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Ordered"><code>Core.Ordered</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a> 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.</p>
<p>OData 4.0 responses MUST NOT specify a complex type declaring a containment navigation property as the type of a collection-valued property.</p>
@@ -1637,7 +1637,7 @@ <h2 id="93-open-complex-type"><a id="OpenComplexType" href="#OpenComplexType">9.
</summary>
<p>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.</p>
<p>A complex type derived from an open complex type MUST indicate that it is also open.</p>
-<p>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 <a href="#ODataProtocol">OData‑Protocol</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel">OData-Protocol, section 3</a>.</p>
<section class="varxml rep">
<h3><a id="AttributeOpenType.16.4" href="#AttributeOpenType.16.4">Attribute <code>OpenType</code></a></h3>
<p>The value of <code>OpenType</code> is one of the Boolean literals <code>true</code> or <code>false</code>. Absence of the attribute means <code>false</code>.</p>
@@ -2163,7 +2163,7 @@ <h1 id="14-vocabulary-and-annotation"><a id="VocabularyandAnnotation" href="#Voc
</summary>
<p>Vocabularies and annotations provide the ability to annotate metadata as well as instance data, and define a powerful extensibility point for OData. An <a href="#Annotation"><em>annotation</em></a> applies a <a href="#Term"><em>term</em></a> to a model element and defines how to calculate a value for the applied term.</p>
<p><em>Metadata annotations</em> 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.</p>
-<p><em>Instance annotations</em> are terms applied to a particular instance within an OData payload, such as described in <a href="#ODataJSON">OData-JSON</a>. 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.</p>
+<p><em>Instance annotations</em> are terms applied to a particular instance within an OData payload, such as described in <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InstanceAnnotations">OData-JSON, section 20</a>. 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.</p>
<p>A <em>vocabulary</em> is a schema containing a set of terms where each <a href="#Term">term</a> 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 <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p>A <a href="#Term">term</a> can be used to:</p>
<ul>
@@ -2870,7 +2870,7 @@ <h3 id="1441-path-expressions"><a id="PathExpressions" href="#PathExpressions">1
<details open><summary>
<h4 id="14411-path-syntax"><a id="PathSyntax" href="#PathSyntax">14.4.1.1 Path Syntax</a></h4>
</summary>
-<p>Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see <a href="#ODataURL">OData-URL</a>.</p>
+<p>Model paths and instance paths share a common syntax which is derived from the path expression syntax of URLs, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#PathExpressions">OData-URL, section 5.1.1.15</a>.</p>
<p>A path MUST be composed of zero or more path segments joined together by forward slashes (<code>/</code>).</p>
<p>Paths starting with a forward slash (<code>/</code>) 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.</p>
<div class="example">
@@ -2917,7 +2917,7 @@ <h4 id="14411-path-syntax"><a id="PathSyntax" href="#PathSyntax">14.4.1.1 Path S
<pre><code>…/Items@Core.Description</code></pre>
<pre><code>…/Items/@Core.Description</code></pre>
</div>
-<p>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 <a href="#ODataURL">OData-URL</a>. 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, <em>not</em> relative to the instance identified by the preceding path part.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL">OData-URL, section 4.3.1</a>. 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, <em>not</em> relative to the instance identified by the preceding path part.</p>
<div class="example">
<p>Example 67: instance path with entity set and key predicate</p>
<pre><code>/self.container/SettingsCollection('FeatureXxx')/IsAvailable</code></pre>
@@ -3132,7 +3132,7 @@ <h3 id="1442-comparison-and-logical-operators"><a id="ComparisonandLogicalOperat
<tr><td><code>In</code></td><td>Is in collection </td></tr>
</table>
-<p>The <code>And</code> and <code>Or</code> operators require two operand expressions that evaluate to Boolean values. The <code>Not</code> operator requires a single operand expression that evaluates to a Boolean value. For details on null handling for comparison operators see <a href="#ODataURL">OData-URL</a>.</p>
+<p>The <code>And</code> and <code>Or</code> operators require two operand expressions that evaluate to Boolean values. The <code>Not</code> operator requires a single operand expression that evaluates to a Boolean value. For details on null handling for comparison operators see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LogicalOperators">OData-URL, section 5.1.1.1</a>.</p>
<p>The other comparison operators require two operand expressions that evaluate to comparable values.</p>
<div class="varxml rep">
<h3><a id="ExpressionsedmAnd.49" href="#ExpressionsedmAnd.49">Expressions <code>edm:And</code></a> and <a id="edmOr.49.1" href="#edmOr.49.1"><code>edm:Or</code></a></h3>
@@ -3198,7 +3198,7 @@ <h3><a id="ExpressionsedmEq.51" href="#ExpressionsedmEq.51">Expressions <code>ed
<details open><summary>
<h3 id="1443-arithmetic-operators"><a id="ArithmeticOperators" href="#ArithmeticOperators">14.4.3 Arithmetic Operators</a></h3>
</summary>
-<p>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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ArithmeticOperators">OData-URL, section 5.1.1.2</a>.</p>
<table>
<thead>
<tr class="header">
@@ -3292,7 +3292,7 @@ <h3><a id="AttributeFunction.54.1" href="#AttributeFunction.54.1">Attribute <cod
<details open><summary>
<h4 id="14441-canonical-functions"><a id="CanonicalFunctions" href="#CanonicalFunctions">14.4.4.1 Canonical Functions</a></h4>
</summary>
-<p>All canonical functions defined in <a href="#ODataURL">OData-URL</a> can be used as client-side functions, qualified with the namespace <code>odata</code>. The semantics of these client-side functions is identical to their counterpart function defined in <a href="#ODataURL">OData-URL</a>.</p>
+<p>All canonical functions defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions">OData-URL, section 5.1.1.4</a> can be used as client-side functions, qualified with the namespace <code>odata</code>. The semantics of these client-side functions is identical to their counterpart function defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions">OData-URL, section 5.1.1.4</a>.</p>
<p>For example, the <code>odata.concat</code> client-side function takes two expressions as arguments. Each argument MUST evaluate to a primitive or enumeration type. It returns a value of type <code>Edm.String</code> that is the concatenation of the literal representations of the results of the argument expressions. Values of primitive types other than <code>Edm.String</code> are represented according to the appropriate alternative in the <code>primitiveValue</code> rule of <a href="#ODataABNF">OData-ABNF</a>, i.e. <code>Edm.Binary</code> as <code>binaryValue</code>, <code>Edm.Boolean</code> as <code>booleanValue</code> etc.</p>
<div class="varxml example">
<p>Example 77:</p>
@@ -3371,7 +3371,7 @@ <h4 id="14444-function-odatauriencode"><a id="FunctionodatauriEncode" href="#Fun
<details open><summary>
<h3 id="1445-cast"><a id="Cast" href="#Cast">14.4.5 Cast</a></h3>
</summary>
-<p>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 <code>cast</code> canonical function defined in <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <code>cast</code> canonical function defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#cast">OData-URL, section 5.1.1.10.1</a>.</p>
<div class="varxml rep">
<h3><a id="ExpressionedmCast.55" href="#ExpressionedmCast.55">Expression <code>edm:Cast</code></a></h3>
<p>The <code>edm:Cast</code> element MUST contain the <code>Type</code> attribute and MUST contain exactly one expression.</p>
@@ -4194,7 +4194,7 @@ <h1 id="appendix-c-acknowledgments"><a id="Acknowledgments" href="#Acknowledgmen
<details open><summary>
<h2 id="c1-special-thanks"><a id="SpecialThanks" href="#SpecialThanks">C.1 Special Thanks</a></h2>
</summary>
-<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="#ODataProtocol">ODataProtocol</a>, are gratefully acknowledged.</p>
+<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants">OData-Protocol, section C.2</a>, are gratefully acknowledged.</p>
</details>
<details open><summary>
<h2 id="c2-participants"><a id="Participants" href="#Participants">C.2 Participants</a></h2>
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.
#### <a id="PathSyntax" href="#PathSyntax">14.4.1.1 Path Syntax</a>
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.
#### <a id="CanonicalFunctions" href="#CanonicalFunctions">14.4.4.1 Canonical Functions</a>
-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.
## <a id="Participants" href="#Participants">C.2 Participants</a>
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 @@ <h2 id="39-abnf-for-extended-url-conventions"><a id="ABNFforExtendedURLConventio
<h1 id="4-cross-joins-and-aggregation"><a id="CrossJoinsandAggregation" href="#CrossJoinsandAggregation">4 Cross-Joins and Aggregation</a></h1>
</summary>
<p>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.</p>
-<p>In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource <code>$crossjoin</code> 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 <a href="#ODataURL">OData-URL</a> for details.</p>
+<p>In some cases, however, requests need to span entity sets with no predefined associations. Such requests can be sent to the special resource <code>$crossjoin</code> 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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets">OData-URL, section 4.15</a> for details.</p>
<p>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.</p>
<div class="example">
<p>Example 47: if <code>Sale</code> had a string property <code>ProductID</code> instead of the navigation property <code>Product</code>, a “join” between <code>Sales</code> and <code>Products</code> could be accessed via the <code>$crossjoin</code> resource</p>
@@ -2674,7 +2674,7 @@ <h1 id="5-vocabulary-for-data-aggregation"><a id="VocabularyforDataAggregation"
<details open><summary>
<h2 id="51-aggregation-capabilities"><a id="AggregationCapabilities" href="#AggregationCapabilities">5.1 Aggregation Capabilities</a></h2>
</summary>
-<p>The term <code>ApplySupported</code> 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 <a href="#containerrooted">example 50</a>). 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 <code>$apply</code> even if they do not specify the <code>OpenType</code> attribute, see <a href="#ODataCSDL">OData-CSDL</a>. The term has a complex type with the following properties:</p>
+<p>The term <code>ApplySupported</code> 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 <a href="#containerrooted">example 50</a>). 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 <code>$apply</code> even if they do not specify the <code>OpenType</code> attribute, see <a href="https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#OpenEntityType">OData-CSDL, section 6.3</a>. The term has a complex type with the following properties:</p>
<ul>
<li>The <code>Transformations</code> 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 <code>Transformations</code> is omitted the server supports all transformations defined by this specification.</li>
<li>The <code>CustomAggregationMethods</code> 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.</li>
@@ -4922,7 +4922,7 @@ <h1 id="appendix-b-acknowledgments"><a id="Acknowledgments" href="#Acknowledgmen
<details open><summary>
<h2 id="b1-special-thanks"><a id="SpecialThanks" href="#SpecialThanks">B.1 Special Thanks</a></h2>
</summary>
-<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="#ODataProtocol">OData-Protocol</a>, are gratefully acknowledged.</p>
+<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants">OData-Protocol, section C.2</a>, are gratefully acknowledged.</p>
</details>
<details open><summary>
<h2 id="b2-participants"><a id="Participants" href="#Participants">B.2 Participants</a></h2>
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
## <a id="AggregationCapabilities" href="#AggregationCapabilities">5.1 Aggregation Capabilities</a>
-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.
## <a id="SpecialThanks" href="#SpecialThanks">B.1 Special Thanks</a>
-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.
## <a id="Participants" href="#Participants">B.2 Participants</a>
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 @@ <h2 id="42-message-body"><a id="MessageBody" href="#MessageBody">4.2 Message Bod
<details open><summary>
<h2 id="43-urls-in-message-bodies"><a id="URLsinMessageBodies" href="#URLsinMessageBodies">4.3 URLs in Message Bodies</a></h2>
</summary>
-<p>URLs represented as a string within a JSON payload, including <a href="#BatchRequest">batch requests</a>, must follow standard OData encoding rules as defined in <a href="#ODataURL">OData-URL</a>.</p>
+<p>URLs represented as a string within a JSON payload, including <a href="#BatchRequest">batch requests</a>, must follow standard OData encoding rules as defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#URLParsing">OData-URL, section 2.1</a>.</p>
<p>For <a href="#RelativeURLs">relative URLs</a> this means that colons (<code>:</code>) 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 (<code>?</code>), need not be percent-encoded.</p>
</details>
<details open><summary>
@@ -654,10 +654,10 @@ <h2 id="46-control-information"><a id="ControlInformation" href="#ControlInforma
<details open><summary>
<h3 id="461-control-information-context-odatacontext"><a id="ControlInformationcontextodatacontext" href="#ControlInformationcontextodatacontext">4.6.1 Control Information: <code>context</code> (<code>odata.context</code>)</a></h3>
</summary>
-<p>The <code>context</code> control information returns the context URL (see <a href="#ODataProtocol">OData-Protocol</a>) for the payload. This URL can be absolute or <a href="#RelativeURLs">relative</a>. The fragment portion of the context URL MUST NOT be percent-encoded.</p>
+<p>The <code>context</code> control information returns the context URL (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL">OData-Protocol, section 10</a>) for the payload. This URL can be absolute or <a href="#RelativeURLs">relative</a>. The fragment portion of the context URL MUST NOT be percent-encoded.</p>
<p>The <code>context</code> control information is not returned if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested. Otherwise it MUST be the first property of any JSON response that allows this control information (this excludes for example <a href="#ErrorResponse">error responses</a>).</p>
<p>The <code>context</code> 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.</p>
-<p>For more information on the format of the context URL, see <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>For more information on the format of the context URL, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL">OData-Protocol, section 10</a>.</p>
<p>Request payloads MAY include a context URL as a base URL for <a href="#RelativeURLs">relative URLs</a> in the request payload.</p>
<div class="example">
<p>Example 4:</p>
@@ -672,14 +672,14 @@ <h3 id="461-control-information-context-odatacontext"><a id="ControlInformationc
<h3 id="462-control-information-metadataetag-odatametadataetag"><a id="ControlInformationmetadataEtagodatametadataEtag" href="#ControlInformationmetadataEtagodatametadataEtag">4.6.2 Control Information: <code>metadataEtag</code> (<code>odata.metadataEtag</code>)</a></h3>
</summary>
<p>The <code>metadataEtag</code> 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 <code>metadataEtag</code> control information to the metadata document’s ETag in all responses when using <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> or <a href="#metadatafullodatametadatafull"><code>metadata=full</code></a>. If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the <code>metadataEtag</code> control information in any responses.</p>
-<p>For details on how ETags are used, see <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>For details on how ETags are used, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts">OData-Protocol, section 11.4.1.1</a>.</p>
</details>
<details open><summary>
<h3 id="463-control-information-type-odatatype"><a id="ControlInformationtypeodatatype" href="#ControlInformationtypeodatatype">4.6.3 Control Information: <code>type</code> (<code>odata.type</code>)</a></h3>
</summary>
<p>The <code>type</code> 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 <code>OData-Version</code> header with a value of <code>4.0</code>, this name MUST be prefixed with the hash symbol (<code>#</code>); 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 <code>type</code> of the containing object. The root <code>type</code> may be absolute or relative to the root <a href="#ControlInformationcontextodatacontext">context URL</a>.</p>
-<p>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 <code>$schemaversion</code> system query option defined in <a href="#ODataProtocol">OData-Protocol</a>.</p>
-<p>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 <code>Collection</code>. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a>.</p>
+<p>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 <code>$schemaversion</code> system query option defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion">OData-Protocol, section 11.2.12</a>.</p>
+<p>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 <code>Collection</code>. The namespace or alias MUST be defined or the namespace referenced in the metadata document of the service, see <a href="#ODataCSDL">OData-CSDL</a>.</p>
<p>The <code>type</code> control information MUST appear in requests and in responses with <a href="#metadataminimalodatametadataminimal">minimal</a> or <a href="#metadatafullodatametadatafull">full</a> metadata, if the type cannot be heuristically determined, as described below, and one of the following is true:</p>
<ul>
<li>The type is derived from the type specified for the (collection of) entities or (collection of) complex type instances, or</li>
@@ -694,7 +694,7 @@ <h3 id="463-control-information-type-odatatype"><a id="ControlInformationtypeoda
<li>String values do have a first class representation in JSON, but there is an obvious collision: OData also encodes a number of other primitive types as strings, e.g. <code>DateTimeOffset</code>, <code>Int64</code> in the presence of the <a href="#ControllingtheRepresentationofNumbers"><code>IEEE754Compatible</code></a> 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.</li>
</ul>
<p>The <code>type</code> control information can be absent in properties nested in an instance of type <code>Edm.Untyped</code>. In particular, individual primitive values within a collection cannot have <code>type</code> control information.</p>
-<p>For more information on namespace- and alias-qualified names, see <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a>.</p>
+<p>For more information on namespace- and alias-qualified names, see <a href="#ODataCSDL">OData-CSDL</a>.</p>
<div class="example">
<p>Example 5: entity of type <code>Model.VipCustomer</code> defined in the metadata document of the same service with a dynamic property of type <code>Edm.Date</code></p>
<div class="sourceCode" id="cb7"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
@@ -740,7 +740,7 @@ <h3 id="467-control-information-deltalink-odatadeltalink"><a id="ControlInformat
<details open><summary>
<h3 id="468-control-information-id-odataid"><a id="ControlInformationidodataid" href="#ControlInformationidodataid">4.6.8 Control Information: <code>id</code> (<code>odata.id</code>)</a></h3>
</summary>
-<p>The <code>id</code> control information contains the entity-id, see <a href="#ODataProtocol">OData-Protocol</a>. By convention the entity-id is identical to the canonical URL of the entity, as defined in <a href="#ODataURL">OData-URL</a>.</p>
+<p>The <code>id</code> control information contains the entity-id, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences">OData-Protocol, section 4.1</a>. By convention the entity-id is identical to the canonical URL of the entity, as defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL">OData-URL, section 4.3.1</a>.</p>
<p>The <code>id</code> control information MUST appear in responses if <a href="#metadatafullodatametadatafull"><code>metadata=full</code></a> is requested, or if <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> is requested and any of a non-transient entity’s key fields are omitted from the response <em>or</em> the entity-id is not identical to the canonical URL of the entity after</p>
<ul>
<li>IRI-to-URI conversion as defined in <a href="#rfc3987">RFC3987</a>,</li>
@@ -748,14 +748,14 @@ <h3 id="468-control-information-id-odataid"><a id="ControlInformationidodataid"
<li>percent-encoding normalization as defined in section 6 of <a href="#rfc3986">RFC3986</a>.</li>
</ul>
<p>Note that the entity-id MUST be invariant across languages, so if key values are language dependent then the <code>id</code> MUST be included if it does not match convention for the localized key values. If the <code>id</code> is represented, it MAY be a <a href="#RelativeURLs">relative URL</a>.</p>
-<p>If the entity is transient (see <a href="#ODataProtocol">OData-Protocol</a>), the <code>id</code> control information MUST appear in OData 4.0 payloads and have the <code>null</code> value. In 4.01 or greater payloads transient entities need not have the <code>id</code> control information, and clients receiving such payloads MUST treat entities with neither <code>id</code> control information nor a full set of key properties as transient entities. In 4.02 payloads transient entities MAY have the <code>id</code> control information with a non-null URI value, for example to allow solving a circular dependency by injecting an <a href="#EntityReference">entity reference</a> instead of repeating the transient entity. The URI value SHOULD follow the pattern <code>odata:transient:{some-generated-identifier-unique-within-the-response}</code>, and if the transient entity cannot be re-read its <code>readLink</code> control information SHOULD have the <code>null</code> value.</p>
+<p>If the entity is transient (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#TransientEntities">OData-Protocol, section 4.3</a>), the <code>id</code> control information MUST appear in OData 4.0 payloads and have the <code>null</code> value. In 4.01 or greater payloads transient entities need not have the <code>id</code> control information, and clients receiving such payloads MUST treat entities with neither <code>id</code> control information nor a full set of key properties as transient entities. In 4.02 payloads transient entities MAY have the <code>id</code> control information with a non-null URI value, for example to allow solving a circular dependency by injecting an <a href="#EntityReference">entity reference</a> instead of repeating the transient entity. The URI value SHOULD follow the pattern <code>odata:transient:{some-generated-identifier-unique-within-the-response}</code>, and if the transient entity cannot be re-read its <code>readLink</code> control information SHOULD have the <code>null</code> value.</p>
<p>The <code>id</code> control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification.</p>
</details>
<details open><summary>
<h3 id="469-control-information-editlink-and-readlink-odataeditlink-and-odatareadlink"><a id="ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink" href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">4.6.9 Control Information: <code>editLink</code> and <code>readLink</code> (<code>odata.editLink</code> and <code>odata.readLink</code>)</a></h3>
</summary>
-<p>The <code>editLink</code> control information contains the edit <a href="URLsinMessageBodies">URL</a> of the entity; see <a href="#ODataProtocol">OData-Protocol</a>.</p>
-<p>The <code>readLink</code> control information contains the read URL of the entity or collection; see <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>The <code>editLink</code> control information contains the edit <a href="URLsinMessageBodies">URL</a> of the entity; see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ReadURLsandEditURLs">OData-Protocol, section 4.2</a>.</p>
+<p>The <code>readLink</code> control information contains the read URL of the entity or collection; see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ReadURLsandEditURLs">OData-Protocol, section 4.2</a>.</p>
<p>The <code>editLink</code> and <code>readLink</code> control information is ignored in request payloads and not written in responses if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested.</p>
<p>The default value of both the edit URL and read URL is the entity’s <a href="#ControlInformationidodataid">entity-id</a> 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 <code>editLink</code> nor the <code>readLink</code> control information is present in an entity, the client uses this default value for the edit URL.</p>
<p>For updatable entities:</p>
@@ -778,7 +778,7 @@ <h3 id="469-control-information-editlink-and-readlink-odataeditlink-and-odatarea
<h3 id="4610-control-information-etag-odataetag"><a id="ControlInformationetagodataetag" href="#ControlInformationetagodataetag">4.6.10 Control Information: <code>etag</code> (<code>odata.etag</code>)</a></h3>
</summary>
<p>The <code>etag</code> control information MAY be applied to an <a href="#Entity">entity</a> 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.</p>
-<p>For details on how ETags are used, see <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>For details on how ETags are used, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts">OData-Protocol, section 11.4.1.1</a>.</p>
<p>The <code>etag</code> control information is ignored in request payloads for single entities and not written in responses if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested.</p>
</details>
<details open><summary>
@@ -854,7 +854,7 @@ <h1 id="5-service-document"><a id="ServiceDocument" href="#ServiceDocument">5 Se
</summary>
<p>A service document in JSON is represented as a single JSON object with at least the <a href="#ControlInformationcontextodatacontext"><code>context</code></a> control information and a property <code>value</code>.</p>
<p>The value of the <a href="#ControlInformationcontextodatacontext"><code>context</code></a> control information MUST be the URL of the metadata document, without any fragment part.</p>
-<p>The value of the <code>value</code> property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of <code>true</code> for the attribute <code>IncludeInServiceDocument</code> and each singleton exposed by the service, see <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a>.</p>
+<p>The value of the <code>value</code> property MUST be a JSON array containing one element for each entity set and function import with an explicit or default value of <code>true</code> for the attribute <code>IncludeInServiceDocument</code> and each singleton exposed by the service, see <a href="#ODataCSDL">OData-CSDL</a>.</p>
<p>Each element MUST be a JSON object with at least two name/value pairs, one with name <code>name</code> containing the name of the entity set, function import, or singleton, and one with name <code>url</code> containing the URL of the entity set, which may be an absolute or a <a href="#RelativeURLs">relative URL</a>. It MAY contain a name/value pair with name <code>title</code> containing a human-readable, language-dependent title for the object.</p>
<p>JSON objects representing an entity set MAY contain an additional name/value pair with name <code>kind</code> and a value of <code>EntitySet</code>. If the <code>kind</code> name/value pair is not present, the object MUST represent an entity set.</p>
<p>JSON objects representing a function import MUST contain the <code>kind</code> name/value pair with a value of <code>FunctionImport</code>.</p>
@@ -904,7 +904,7 @@ <h1 id="6-entity"><a id="Entity" href="#Entity">6 Entity</a></h1>
</summary>
<p>An entity is serialized as a JSON object. It MAY contain <a href="#ControlInformationcontextodatacontext"><code>context</code></a>, <a href="#ControlInformationtypeodatatype"><code>type</code></a>, or <a href="#ControlInformationdeltaLinkodatadeltaLink"><code>deltaLink</code></a> control information.</p>
<p>Each <a href="#StructuralProperty">property</a> to be transmitted is represented as a name/value pair within the object. The order properties appear within the object is considered insignificant.</p>
-<p>An entity in a payload may be a complete entity, a projected entity (see <em>System Query Option</em> <code>$select</code> in <a href="#ODataProtocol">OData-Protocol</a>), or a partial entity update (see <em>Update an Entity</em> in <a href="#ODataProtocol">OData-Protocol</a>).</p>
+<p>An entity in a payload may be a complete entity, a projected entity (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionselect">OData-Protocol, section 11.2.5.1</a>), or a partial entity update (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity">OData-Protocol, section 11.4.3</a>).</p>
<p>An entity representation can be (modified and) round-tripped to the service directly. The <a href="#ControlInformationcontextodatacontext">context URL</a> is used in requests only as a base for <a href="#RelativeURLs">relative URLs</a>.</p>
<div class="example">
<p>Example 10: entity with <code>metadata=minimal</code></p>
@@ -1058,9 +1058,10 @@ <h2 id="75-untyped-value"><a id="UntypedValue" href="#UntypedValue">7.5 Untyped
<p>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.</p>
<p>All children of an untyped property are assumed to be untyped unless they are annotated with the <a href="#ControlInformationtypeodatatype"><code>type</code></a> control information, in which case they MUST conform to the type described by the control information.</p>
<p>A primitive value within an untyped collection is interpreted as an <code>Edm.Boolean</code>, <code>Edm.String</code>, or <code>Edm.Decimal</code> value, depending on the JavaScript type.</p>
-<h2>Collections directly contained within an untyped collection are themselves untyped.</h2>
+<p>Collections directly contained within an untyped collection are themselves untyped.</p>
</details>
</details>
+<hr />
<details open><summary>
<h1 id="8-navigation-property"><a id="NavigationProperty" href="#NavigationProperty">8 Navigation Property</a></h1>
</summary>
@@ -1228,7 +1229,7 @@ <h1 id="9-stream-property"><a id="StreamProperty" href="#StreamProperty">9 Strea
<li>Stream properties requested with <code>$select</code> or included in the default selection are represented by <a href="#ControlInformationmediaodatamedia"><code>media*</code></a> control information.</li>
<li>Stream properties requested with <code>$expand</code> or implicitly expanded are represented as a property with its value.</li>
</ul>
-<p>See <a href="#ODataProtocol">OData-Protocol</a> for details on the system query options <code>$select</code> and <code>$expand</code>.</p>
+<p>See <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionselect">OData-Protocol, section 11.2.5.1</a> for details on the system query options <code>$select</code> and <code>$expand</code>.</p>
<p>Depending on the <a href="#ControllingtheAmountofControlInformationinResponses">metadata level</a>, the stream property MAY be annotated to provide the read link, edit link, media type, and ETag of the media stream through their <code>media*</code> control information.</p>
<p>If the actual stream data is included inline, the control information <a href="#ControlInformationmediaodatamedia"><code>mediaContentType</code></a> MUST be present to indicate how the included stream property value is represented. Stream property values of media type <code>application/json</code> or one of its subtypes, optionally with format parameters, are represented as native JSON. Values of top-level type <code>text</code> with an explicit or default <code>charset</code> of <code>utf-8</code> or <code>us-ascii</code>, for example <code>text/plain</code>, 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 <a href="#rfc4648">RFC4648</a>, section 5.</p>
<p>If the included stream property has no value, the non-existing stream data is represented as <code>null</code> and the control information <a href="#ControlInformationmediaodatamedia"><code>mediaContentType</code></a> is not necessary.</p>
@@ -1269,7 +1270,7 @@ <h1 id="10-media-entity"><a id="MediaEntity" href="#MediaEntity">10 Media Entity
<h1 id="11-individual-property-or-operation-response"><a id="IndividualPropertyorOperationResponse" href="#IndividualPropertyorOperationResponse">11 Individual Property or Operation Response</a></h1>
</summary>
<p>An individual property or operation response is represented as a JSON object.</p>
-<p>A single-valued property or operation response that has the <code>null</code> value does not have a representation; see <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>A single-valued property or operation response that has the <code>null</code> value does not have a representation; see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ResponseCode204NoContent">OData-Protocol, section 9.1.4</a>.</p>
<p>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 <code>value</code> and whose value is a <a href="#PrimitiveValue">primitive value</a>.</p>
<p>A property or operation response that is of complex type is represented as a <a href="#ComplexValue">complex value</a>.</p>
<p>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 <code>value</code>. Its value is the JSON representation of a <a href="#CollectionofComplexValues">collection of complex type values</a> or <a href="#CollectionofPrimitiveValues">collection of primitive values</a>.</p>
@@ -1351,7 +1352,7 @@ <h1 id="13-collection-of-entities"><a id="CollectionofEntities" href="#Collectio
<details open><summary>
<h1 id="14-entity-reference"><a id="EntityReference" href="#EntityReference">14 Entity Reference</a></h1>
</summary>
-<p>An entity reference (see <a href="#ODataProtocol">OData-Protocol</a>) 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 <a href="#ControlInformationidodataid">id</a> of the referenced entity and MAY contain the <a href="#ControlInformationtypeodatatype"><code>type</code></a> control information and <a href="#InstanceAnnotations">instance annotations</a>, but no additional properties or control information.</p>
+<p>An entity reference (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences">OData-Protocol, section 4.1</a>) 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 <a href="#ControlInformationidodataid">id</a> of the referenced entity and MAY contain the <a href="#ControlInformationtypeodatatype"><code>type</code></a> control information and <a href="#InstanceAnnotations">instance annotations</a>, but no additional properties or control information.</p>
<p>A collection of entity references is represented as a <a href="#CollectionofEntities">collection of entities</a>, with entity reference representations instead of entity representations as items in the array value of the <code>value</code> name/value pair.</p>
<p>The outermost JSON object in a response MUST contain a <a href="#ControlInformationcontextodatacontext"><code>context</code></a> control information and MAY contain <a href="#ControlInformationcountodatacount"><code>count</code></a>, <a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a>, or <a href="#ControlInformationdeltaLinkodatadeltaLink"><code>deltaLink</code></a> control information.</p>
<div class="example">
@@ -1447,7 +1448,7 @@ <h2 id="151-delta-responses"><a id="DeltaResponses" href="#DeltaResponses">15.1
<h2 id="152-addedchanged-entity"><a id="AddedChangedEntity" href="#AddedChangedEntity">15.2 Added/Changed Entity</a></h2>
</summary>
<p>Added or changed entities within a delta payload are represented as <a href="#Entity">entities</a>. All entities within a delta response payload MUST include the control information <a href="#ControlInformationidodataid"><code>id</code></a> or all of the entity’s primary key fields. The <code>id</code> control information MUST appear if any of the entity’s primary key fields are omitted from the response <em>or</em> the entity-id is not identical to the canonical URL of the entity.</p>
-<p>When using a delta payload in an <a href="#UpdateaCollectionofEntities">update request</a>, an <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys">alternate key</a> (see <em>Alternate Keys</em> in <a href="#ODataURL">OData-URL</a>) 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 <code>id</code> control information and other primary key fields.</p>
+<p>When using a delta payload in an <a href="#UpdateaCollectionofEntities">update request</a>, an <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys">alternate key</a> (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AlternateKeys">OData-URL, section 4.3.5</a>) 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 <code>id</code> control information and other primary key fields.</p>
<p>Any entity in an update request that has neither the <code>id</code> control information, nor the primary or alternate key values of an existing entity, are treated as an added entity.</p>
<p>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.</p>
<p>Changed entities MUST include all available selected properties that have changed, and MAY include additional properties.</p>
@@ -1479,7 +1480,7 @@ <h2 id="153-deleted-entity"><a id="DeletedEntity" href="#DeletedEntity">15.3 Del
<p>In OData 4.01 payloads the deleted-entity object MUST include the following properties, regardless of the specified <a href="#ControllingtheAmountofControlInformationinResponses"><code>metadata</code></a> value. For ordered payloads, this control information MUST follow the <a href="#PayloadOrderingConstraints">payload ordering constraints</a>.</p>
<ul>
<li><p>Control information <a href="#ControlInformationremovedodataremoved"><code>removed</code></a>, whose value is an object that MAY contain a property named <code>reason</code>. If present, the value of <code>reason</code> MUST be either <code>deleted</code> if the entity was deleted (destroyed), or <code>changed</code> 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 <a href="#InstanceAnnotations">annotations</a>, and clients SHOULD NOT error due to the presence of additional properties that MAY be defined by future versions of this specification.</p></li>
-<li><p>Control information <a href="#ControlInformationidodataid"><code>id</code></a> or all of the entity’s primary key fields. The <code>id</code> control information MUST appear if any of the entity’s primary key fields are omitted from the response <em>or</em> the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an <a href="#UpdateaCollectionofEntities">update request</a>, an <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys">alternate key</a> (see <em>Alternate Keys</em> in <a href="#ODataURL">OData-URL</a>) 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 <code>id</code> control information and other primary key fields.</p></li>
+<li><p>Control information <a href="#ControlInformationidodataid"><code>id</code></a> or all of the entity’s primary key fields. The <code>id</code> control information MUST appear if any of the entity’s primary key fields are omitted from the response <em>or</em> the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an <a href="#UpdateaCollectionofEntities">update request</a>, an <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#AlternateKeys">alternate key</a> (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AlternateKeys">OData-URL, section 4.3.5</a>) 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 <code>id</code> control information and other primary key fields.</p></li>
</ul>
<p>For full metadata the <a href="#ControlInformationcontextodatacontext"><code>context</code></a> 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.</p>
<p>The deleted-entity object MAY include additional properties of the entity, as well as <a href="#InstanceAnnotations">annotations</a>, 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.</p>
@@ -1911,7 +1912,7 @@ <h2 id="155-update-a-collection-of-entities"><a id="UpdateaCollectionofEntities"
<details open><summary>
<h1 id="16-bound-function"><a id="BoundFunction" href="#BoundFunction">16 Bound Function</a></h1>
</summary>
-<p>A bound function is advertised via a name/value pair where the name is a hash (<code>#</code>) 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 <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a> 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 <code>qualifiedFunctionName</code> in <a href="#ODataABNF">OData-ABNF</a>.</p>
+<p>A bound function is advertised via a name/value pair where the name is a hash (<code>#</code>) 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 <a href="#ODataCSDL">OData-CSDL</a>. 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 <code>qualifiedFunctionName</code> in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>A function that is bound to a single structured type MAY be advertised within the JSON object representing that structured type.</p>
<p>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 <code>value</code> 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, <a href="#ExpandedNavigationProperty">expanded navigation property</a>, or <a href="#NavigationLink"><code>navigationLink</code></a> control information, if present. 4.0 payloads MUST NOT advertise functions prefixed with property names.</p>
<p>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 <code>null</code>.</p>
@@ -1967,7 +1968,7 @@ <h1 id="16-bound-function"><a id="BoundFunction" href="#BoundFunction">16 Bound
<details open><summary>
<h1 id="17-bound-action"><a id="BoundAction" href="#BoundAction">17 Bound Action</a></h1>
</summary>
-<p>A bound action is advertised via a name/value pair where the name is a hash (<code>#</code>) 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 <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a></p>
+<p>A bound action is advertised via a name/value pair where the name is a hash (<code>#</code>) 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 <a href="#ODataCSDL">OData-CSDL</a>.</p>
<p>An action that is bound to a single structured type is advertised within the JSON object representing that structured type.</p>
<p>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 <code>value</code> 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, <a href="#ExpandedNavigationProperty">expanded navigation property</a>, or <a href="#NavigationLink"><code>navigationLink</code></a> control information, if present. 4.0 payloads MUST NOT advertise actions prefixed with property names.</p>
<p>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 <code>null</code>.</p>
@@ -2113,16 +2114,16 @@ <h2 id="191-batch-request"><a id="BatchRequest" href="#BatchRequest">19.1 Batch
<p>A JSON batch request body consists of a single JSON object that MUST contain the name/value pair <code>requests</code> and MAY contain <a href="#InstanceAnnotations">annotations</a>. It does not contain the <code>context</code> control information.</p>
<p>The value of <code>requests</code> is an array of request objects, each representing an individual request. Note: an individual request MUST NOT itself be a batch request.</p>
<p>A <em>request object</em> MUST contain the name/value pairs <code>id</code>, <code>method</code> and <code>url</code>, and it MAY contain the name/value pairs <code>atomicityGroup</code>, <code>dependsOn</code>, <code>if</code>, <code>headers</code>, and <code>body</code>.</p>
-<p>The value of <code>id</code> is a string containing the request identifier of the individual request, see <a href="#ODataProtocol">OData-Protocol</a>. It MUST NOT be identical to the value of any other request identifier nor any <code>atomicityGroup</code> within the batch request.</p>
-<p>Note: the <code>id</code> name/value pair corresponds to the <code>Content-ID</code> header in the multipart batch format specified in <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>The value of <code>id</code> is a string containing the request identifier of the individual request, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#IdentifyingIndividualRequests">OData-Protocol, section 11.7.3</a>. It MUST NOT be identical to the value of any other request identifier nor any <code>atomicityGroup</code> within the batch request.</p>
+<p>Note: the <code>id</code> name/value pair corresponds to the <code>Content-ID</code> header in the multipart batch format specified in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchRequestBody">OData-Protocol, section 11.7.7.1</a>.</p>
<p>The value of <code>method</code> is a string that MUST contain one of the literals <code>delete</code>, <code>get</code>, <code>patch</code>, <code>post</code>, or <code>put</code>. These literals are case-insensitive.</p>
<p>The value of <code>url</code> is a string containing the individual request URL. The URL MAY be an absolute path (starting with a forward slash <code>/</code>) which is appended to scheme, host, and port of the batch request URL, or a relative path (not starting with a forward slash <code>/</code>).</p>
<p>If the first segment of a relative path starts with a <code>$</code> character and is not identical to the name of a top-level system resource (<code>$batch</code>, <code>$crossjoin</code>, <code>$all</code>, <code>$entity</code>, <code>$root</code>, <code>$id</code>, <code>$metadata</code>, or other system resources defined according to the <code>OData-Version</code> 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 <code>id</code> value is identical to the value of the first segment with the leading <code>$</code> character removed. The <code>id</code> of this request MUST be specified in the <code>dependsOn</code> name/value pair.</p>
<p>Otherwise, the relative path is resolved relative to the batch request URL (i.e. relative to the service root).</p>
<p>The value of <code>atomicityGroup</code> is a string whose content MUST NOT be identical to any value of <code>id</code> within the batch request, and which MUST satisfy the rule <code>request-id</code> in <a href="#ODataABNF">OData-ABNF</a>. All request objects with the same value for <code>atomicityGroup</code> MUST be adjacent in the <code>requests</code> array. These requests are processed as an atomic operation and MUST either all succeed, or all fail.</p>
-<p>Note: the atomicity group is a generalization of the change set in the multipart batch format specified in <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>Note: the atomicity group is a generalization of the change set in the multipart batch format specified in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchRequestBody">OData-Protocol, section 11.7.7.1</a>.</p>
<p>The value of <code>dependsOn</code> is an array of strings whose values MUST be values of either <code>id</code> or <code>atomicityGroup</code> 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 <code>dependsOn</code>. In the absence of the optional <code>if</code> member a request that depends on other requests or atomicity groups is only executed if those requests were executed successfully, i.e. with a <code>2xx</code> 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 <code>424 Failed Dependency</code> is returned for it as part of the batch response.</p>
-<p>The <code>if</code> member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see <a href="#ODataURL">OData-URL</a>) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows</p>
+<p>The <code>if</code> member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CommonExpressionSyntax">OData-URL, section 5.1.1</a>) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows</p>
<ul>
<li><code>$<content-id>/$succeeded</code> to check if the referenced request has succeeded</li>
<li><code>$<content-id></code> to reference the response body of the referenced request</li>
@@ -2316,7 +2317,7 @@ <h2 id="196-batch-response"><a id="BatchResponse" href="#BatchResponse">19.6 Bat
<p>A JSON batch response body consists of a single JSON object that MUST contain the name/value pair <code>responses</code> and MAY contain <a href="#InstanceAnnotations">annotations</a>. It does not contain the <code>context</code> control information.</p>
<p>The value of <code>responses</code> is an array of response objects, each representing an individual response.</p>
<p>A JSON batch response MAY be a partial result containing the <a href="#ControlInformationnextLinkodatanextLink"><code>nextLink</code></a> 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 <code>GET</code> request to the next link.</p>
-<p>In a response to a batch request using the multipart format defined in <a href="#ODataProtocol">OData-Protocol</a> the response objects MUST appear in the same order as required for multipart batch responses because the <code>Content-ID</code> header is not required outside of change sets. Response objects corresponding to requests that specify a <code>Content-ID</code> header MUST contain the <code>id</code> name/value pair, and the value of <code>id</code> MUST be the value of the <code>Content-ID</code> 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 <code>atomicityGroup</code> name/value pair with a value common within a change set and unique across change sets.</p>
+<p>In a response to a batch request using the multipart format defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#MultipartBatchFormat">OData-Protocol, section 11.7.7</a> the response objects MUST appear in the same order as required for multipart batch responses because the <code>Content-ID</code> header is not required outside of change sets. Response objects corresponding to requests that specify a <code>Content-ID</code> header MUST contain the <code>id</code> name/value pair, and the value of <code>id</code> MUST be the value of the <code>Content-ID</code> 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 <code>atomicityGroup</code> name/value pair with a value common within a change set and unique across change sets.</p>
<p>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 <code>id</code> name/value pair with the same value as in the corresponding request object. If the corresponding request object contains the <code>atomicityGroup</code> name/value pair, it MUST also be present in the response object with the same value.</p>
<p>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 <code>424 Failed Dependency</code> for statements within an atomicity group that fail or are not attempted due to other failures within the same atomicity group.</p>
<p>A response object MUST contain the name/value pair <code>status</code> whose value is a number representing the HTTP status code of the response to the individual request.</p>
@@ -2450,7 +2451,7 @@ <h2 id="197-asynchronous-batch-requests"><a id="AsynchronousBatchRequests" href=
<h1 id="20-instance-annotations"><a id="InstanceAnnotations" href="#InstanceAnnotations">20 Instance Annotations</a></h1>
</summary>
<p>Annotations are an extensibility mechanism that allows services and clients to include information other than the raw data in the request or response.</p>
-<p>Annotations are name/value pairs that have an at (<code>@</code>) and a dot (<code>.</code>) as part of the name. The part after the “at” sign (<code>@</code>) is the <em>annotation identifier</em>. It consists of the namespace or alias of the schema that defines the term, followed by a dot (<code>.</code>), followed by the name of the term, optionally followed by a hash (<code>#</code>) and a qualifier. The namespace or alias MUST be defined in the metadata document, see <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a></p>
+<p>Annotations are name/value pairs that have an at (<code>@</code>) and a dot (<code>.</code>) as part of the name. The part after the “at” sign (<code>@</code>) is the <em>annotation identifier</em>. It consists of the namespace or alias of the schema that defines the term, followed by a dot (<code>.</code>), followed by the name of the term, optionally followed by a hash (<code>#</code>) and a qualifier. The namespace or alias MUST be defined in the metadata document, see <a href="#ODataCSDL">OData-CSDL</a>.</p>
<p>The annotation identifier <code>odata</code> is reserved for future extensions of the protocol and format. Instance annotations MUST have a namespace or alias that is different from <code>odata</code>.</p>
<p>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.</p>
<p>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 <code>@</code>. An annotation in the latter format can also take the place of an absent property. When annotating a payload that represents a <a href="#IndividualPropertyorOperationResponse">single primitive or collection value</a>, the annotations for the value appear next to the <code>value</code> property and are not prefixed with a property name.</p>
@@ -2534,7 +2535,7 @@ <h2 id="211-error-response"><a id="ErrorResponse" href="#ErrorResponse">21.1 Err
<h2 id="212-in-stream-error"><a id="InStreamError" href="#InStreamError">21.2 In-Stream Error</a></h2>
</summary>
<p>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.</p>
-<p>Services MAY include the header <code>OData-Error</code> 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 <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>Services MAY include the header <code>OData-Error</code> 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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#HeaderODataError">OData-Protocol, section 8.3.5</a>.</p>
<p>The value of the <code>OData-Error</code> trailing header is an OData error object as defined in the preceding chapter, represented in a header-appropriate way:</p>
<ul>
<li><p>All optional whitespace (indentation and line breaks) is removed, especially (in hex notation) <code>09</code>, <code>0A</code> and <code>0D</code></p></li>
@@ -2643,7 +2644,7 @@ <h1 id="23-conformance"><a id="Conformance" href="#Conformance">23 Conformance</
</ol>
<p>In addition, in order to conform to the OData JSON format, a service:</p>
<ol start="11" type="1">
-<li>MUST comply with one of the conformance levels defined in <a href="#ODataProtocol">OData-Protocol</a></li>
+<li>MUST comply with one of the conformance levels defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Conformance">OData-Protocol, section 12</a></li>
<li>MUST support the <code>application/json</code> media type in the <code>Accept</code> header (<a href="#RequestingtheJSONFormat">section 3</a>)</li>
<li>MUST return well-formed JSON payloads</li>
<li>MUST support <code>odata.metadata=full</code> (<a href="#metadatafullodatametadatafull">section 3.1.2</a>)</li>
@@ -2738,7 +2739,7 @@ <h1 id="appendix-c-acknowledgments"><a id="Acknowledgments" href="#Acknowledgmen
<details open><summary>
<h2 id="c1-special-thanks"><a id="SpecialThanks" href="#SpecialThanks">C.1 Special Thanks</a></h2>
</summary>
-<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="#ODataProtocol">OData-Protocol</a> are gratefully acknowledged.</p>
+<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants">OData-Protocol, section C.2</a>, are gratefully acknowledged.</p>
</details>
<details open><summary>
<h2 id="c2-participants"><a id="Participants" href="#Participants">C.2 Participants</a></h2>
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.
## <a id="URLsinMessageBodies" href="#URLsinMessageBodies">4.3 URLs in Message Bodies</a>
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.
### <a id="ControlInformationcontextodatacontext" href="#ControlInformationcontextodatacontext">4.6.1 Control Information: `context` (`odata.context`)</a>
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).
### <a id="ControlInformationtypeodatatype" href="#ControlInformationtypeodatatype">4.6.3 Control Information: `type` (`odata.type`)</a>
@@ -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.
### <a id="ControlInformationidodataid" href="#ControlInformationidodataid">4.6.8 Control Information: `id` (`odata.id`)</a>
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.
### <a id="ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink" href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">4.6.9 Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`)</a>
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.
+
-------
# <a id="NavigationProperty" href="#NavigationProperty">8 Navigation Property</a>
@@ -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:
# <a id="EntityReference" href="#EntityReference">14 Entity Reference</a>
-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
- `$<content-id>/$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
## <a id="SpecialThanks" href="#SpecialThanks">C.1 Special Thanks</a>
-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.
## <a id="Participants" href="#Participants">C.2 Participants</a>
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 @@ <h1 id="1-introduction"><a id="Introduction" href="#Introduction">1 Introduction
<p>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.</p>
<p>The <a href="#ODataURL">OData-URL</a> 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.</p>
<p>The <a href="#ODataCSDL">OData-CSDLJSON</a> specification defines a JSON representation of the entity data model exposed by an OData service.</p>
-<p>The <a href="#ODataCSDL">OData-CSDLXML</a> specification defines an XML representation of the entity data model exposed by an OData service.</p>
+<p>The <a href="#ODataCSDLXML">OData-CSDLXML</a> specification defines an XML representation of the entity data model exposed by an OData service.</p>
<p>The <a href="#ODataJSON">OData-JSON</a> document specifies the JSON format of the resource representations that are exchanged using OData.</p>
<details open><summary>
<h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" href="#ChangesfromEarlierVersions">1.1 Changes from Earlier Versions</a></h2>
@@ -704,7 +704,7 @@ <h1 id="3-data-model"><a id="DataModel" href="#DataModel">3 Data Model</a></h1>
<p><em>Operations</em> allow the execution of custom logic on parts of a data model. <a href="#Functions"><em>Functions</em></a> are operations that do not have side effects and may support further composition, for example, with additional filter operations, functions or an action. <a href="#Actions"><em>Actions</em></a> 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 <em>bound</em> 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. <em>Action imports</em> and <em>function imports</em> enable unbound actions and functions to be called from the service root.</p>
<p><em>Singletons</em> 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.</p>
<p>An OData <em>resource</em> is anything in the model that can be addressed (an entity set, entity, property, or operation).</p>
-<p>Refer to <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a> for more information on the OData entity data model.</p>
+<p>Refer to <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDLXML">OData-CSDLXML</a> for more information on the OData entity data model.</p>
<details open><summary>
<h2 id="31-annotations"><a id="Annotations" href="#Annotations">3.1 Annotations</a></h2>
</summary>
@@ -729,7 +729,7 @@ <h1 id="4-service-model"><a id="ServiceModel" href="#ServiceModel">4 Service Mod
<h2 id="41-entity-ids-and-entity-references"><a id="EntityIdsandEntityReferences" href="#EntityIdsandEntityReferences">4.1 Entity-Ids and Entity References</a></h2>
</summary>
<p>Whereas entities within an entity set are uniquely identified by their key values, entities are also uniquely identified by a durable, opaque, globally unique <em>entity-id</em>. The entity-id MUST be an IRI as defined in <a href="#rfc3987">RFC3987</a> 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 <a href="#HeaderODataEntityId"><code>EntityId</code></a> header.</p>
-<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <a href="#ODataURL">OData-URL</a> as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DereferenceableIDs"><code>Core.DereferenceableIDs</code></a> term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource <code>$entity</code> provides a general mechanism for <a href="#ResolvinganEntityId">resolving an entity-id</a> into an entity representation.</p>
+<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL">OData-URL, section 4.3.1</a> as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DereferenceableIDs"><code>Core.DereferenceableIDs</code></a> term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource <code>$entity</code> provides a general mechanism for <a href="#ResolvinganEntityId">resolving an entity-id</a> into an entity representation.</p>
<p>Services that use the standard URL conventions for entity-ids annotate their entity container with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ConventionalIDs"><code>Core.ConventionalIDs</code></a>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p><em>Entity references</em> refer to an entity using the entity’s entity-id.</p>
</details>
@@ -739,7 +739,7 @@ <h2 id="42-read-urls-and-edit-urls"><a id="ReadURLsandEditURLs" href="#ReadURLsa
<p>The read URL of an entity is the URL that can be used to read the entity.</p>
<p>The edit URL of an entity is the URL that can be used to update or delete the entity.</p>
<p>The edit URL of a property is the edit URL of the entity with appended segment(s) containing the path to the property.</p>
-<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <a href="#ODataURL">OData-URL</a> 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.</p>
+<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL">OData-URL, section 4.3.1</a> 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.</p>
</details>
<details open><summary>
<h2 id="43-transient-entities"><a id="TransientEntities" href="#TransientEntities">4.3 Transient Entities</a></h2>
@@ -868,7 +868,7 @@ <h3 id="811-header-content-type"><a id="HeaderContentType" href="#HeaderContentT
</summary>
<p>The format of a non-empty individual request or response body, alone or within a batch, MUST be specified in the <code>Content-Type</code> header of a request or response. The exception to this is if the body represents the media stream of a <a href="#RequestingtheMediaStreamofaMediaEntityusingvalue">media entity</a> or <a href="#ManagingStreamProperties">stream property</a>, in which case the <code>Content-Type</code> header SHOULD be present.</p>
<p>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 <code>odata</code> and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload.</p>
-<p>See <a href="#ODataJSON">OData-JSON</a> for format-specific details about format parameters within the <code>Content-Type</code> header.</p>
+<p>See <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#HeaderContentType">OData-JSON, section 4.1</a> for format-specific details about format parameters within the <code>Content-Type</code> header.</p>
</details>
<details open><summary>
<h3 id="812-header-content-encoding"><a id="HeaderContentEncoding" href="#HeaderContentEncoding">8.1.2 Header <code>Content-Encoding</code></a></h3>
@@ -1158,7 +1158,7 @@ <h3 id="834-header-odata-entityid"><a id="HeaderODataEntityId" href="#HeaderODat
<h3 id="835-header-odata-error"><a id="HeaderODataError" href="#HeaderODataError">8.3.5 Header <code>OData-Error</code></a></h3>
</summary>
<p>A response with an <a href="#InStreamErrors">in-stream error</a> MAY include an <code>OData-Error</code> trailing header if the transport protocol supports trailing headers (e.g. HTTP/1.1 with chunked transfer encoding, or HTTP/2).</p>
-<p>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. <a href="#ODataJSON">OData-JSON</a>.</p>
+<p>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. <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InStreamError">OData-JSON, section 21.2</a>.</p>
</details>
<details open><summary>
<h3 id="836-header-preference-applied"><a id="HeaderPreferenceApplied" href="#HeaderPreferenceApplied">8.3.6 Header <code>Preference-Applied</code></a></h3>
@@ -1593,14 +1593,14 @@ <h2 id="1019-all-response"><a id="allResponse" href="#allResponse">10.19 <code>$
</summary>
<p>Context URL template:</p>
<pre><code>{context-url}#Collection(Edm.EntityType)</code></pre>
-<p>Responses to requests to the virtual collection <code>$all</code> (see <a href="#ODataURL">OData-URL</a>) 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.</p>
+<p>Responses to requests to the virtual collection <code>$all</code> (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingAllEntitiesinaService">OData-URL, section 4.16</a>) 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.</p>
</details>
<details open><summary>
<h2 id="1020-crossjoin-response"><a id="crossjoinResponse" href="#crossjoinResponse">10.20 <code>$crossjoin</code> Response</a></h2>
</summary>
<p>Context URL template:</p>
<pre><code>{context-url}#Collection(Edm.ComplexType)</code></pre>
-<p>Responses to requests to the virtual collections <code>$crossjoin(…)</code> (see <a href="#ODataURL">OData-URL</a>) use the built-in abstract complex type. Single instances in these responses do not have a context URL.</p>
+<p>Responses to requests to the virtual collections <code>$crossjoin(…)</code> (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets">OData-URL, section 4.15</a>) use the built-in abstract complex type. Single instances in these responses do not have a context URL.</p>
</details>
</details>
<hr />
@@ -1661,7 +1661,7 @@ <h3 id="1112-metadata-document-request"><a id="MetadataDocumentRequest" href="#M
</summary>
<p>An OData <em>metadata document</em> is a representation of the <a href="#DataModel">data model</a> that describes the data and operations exposed by an OData service.</p>
<p><a href="#ODataCSDL">OData-CSDLJSON</a> 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 <code>application/json</code>.</p>
-<p><a href="#ODataCSDL">OData-CSDLXML</a> 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 <code>application/xml</code>.</p>
+<p><a href="#ODataCSDLXML">OData-CSDLXML</a> 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 <code>application/xml</code>.</p>
<p>OData services can expose a metadata document that describes the data model exposed by the service. The <em>metadata document URL</em> MUST be the root URL of the service with <code>$metadata</code> appended. To retrieve this document the client issues a <code>GET</code> request to the metadata document URL.</p>
<p>If a request for metadata does not specify a format preference (via <a href="#HeaderAccept"><code>Accept</code></a> header or <a href="#SystemQueryOptionformat"><code>$format</code></a>) then the XML representation MUST be returned.</p>
</details>
@@ -1704,7 +1704,7 @@ <h3 id="1121-system-query-options"><a id="SystemQueryOptions" href="#SystemQuery
<h3 id="1122-requesting-individual-entities"><a id="RequestingIndividualEntities" href="#RequestingIndividualEntities">11.2.2 Requesting Individual Entities</a></h3>
</summary>
<p>To retrieve an individual entity, the client makes a <code>GET</code> request to a URL that identifies the entity, e.g. its read URL.</p>
-<p>The read URL can be obtained from a response payload containing that instance, for example as a <code>readLink</code> or <code>editLink</code> in an <a href="#ODataJSON">OData-JSON</a> payload. In addition, services MAY support conventions for constructing a read URL using the entity’s key value(s), as described in <a href="#ODataURL">OData-URL</a>.</p>
+<p>The read URL can be obtained from a response payload containing that instance, for example as a <code>readLink</code> or <code>editLink</code> in an <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">OData-JSON, section 4.6.9</a> payload. In addition, services MAY support conventions for constructing a read URL using the entity’s key value(s), as described in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL">OData-URL, section 4.3.1</a>.</p>
<p>The set of structural or navigation properties to return may be specified through <a href="#SystemQueryOptionselect"><code>$select</code></a> or <a href="#SystemQueryOptionexpand"><code>$expand</code></a> system query options.</p>
<p>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.</p>
<p>Properties that are not available are not returned. If their unavailability is due to permissions, the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Permissions"><code>Core.Permissions</code></a> annotation, defined in <a href="#ODataVocCore">OData-VocCore</a> MUST be returned for the property with a value of <code>None</code>. If the <a href="#Preferenceomitvalues"><code>omit-values</code></a> preference is applied, <code>Core.Permissions</code> or another specific annotation that explains the reason MUST be returned for every unavailable property.</p>
@@ -1724,7 +1724,7 @@ <h3 id="1124-requesting-individual-properties"><a id="RequestingIndividualProper
</summary>
<p>To retrieve an individual property, the client issues a <code>GET</code> request to the property URL. The property URL is the entity read URL with <code>/</code> and the property name appended.</p>
<p>For complex typed properties, the path can be further extended with the name of an individual property of the complex type.</p>
-<p>See <a href="#ODataURL">OData-URL</a> for details.</p>
+<p>See <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaProperty">OData-URL, section 4.6</a> for details.</p>
<p>If the property is single-valued and has the <code>null</code> value, the service responds with <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>.</p>
<p>If the property is not available, for example due to permissions, the service responds with <a href="#ResponseCode404NotFound"><code>404 Not Found</code></a>.</p>
<div class="example">
@@ -1740,7 +1740,7 @@ <h4 id="11241-requesting-stream-properties"><a id="RequestingStreamProperties" h
<details open><summary>
<h4 id="11242-requesting-a-raw-value-using-value"><a id="RequestingaRawValueusingvalue" href="#RequestingaRawValueusingvalue">11.2.4.2 Requesting a Raw Value using <code>$value</code></a></h4>
</summary>
-<p>To retrieve the raw value of a primitive property or operation result, the client sends a <code>GET</code> request to the raw value URL. See the <a href="#ODataURL">OData-URL</a> document for details.</p>
+<p>To retrieve the raw value of a primitive property or operation result, the client sends a <code>GET</code> request to the raw value URL. See <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaRawValue">OData-URL, section 4.7</a> for details.</p>
<p>The <code>Content-Type</code> of the response is determined using the <code>Accept</code> header and the <a href="#SystemQueryOptionformat"><code>$format</code></a> system query option.</p>
<p>The default format for <code>Edm.Binary</code> is the format specified by the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#MediaType"><code>Core.MediaType</code></a> annotation (see <a href="#ODataVocCore">OData-VocCore</a>) if this annotation is present. If not annotated, the format cannot be predicted by the client.</p>
<p>The default format for <code>Edm.Geo</code> types is <code>text/plain</code> using the WKT (well-known text) format, see rules <code>fullCollectionLiteral</code>, <code>fullLineStringLiteral</code>, <code>fullMultiPointLiteral</code>, <code>fullMultiLineStringLiteral</code>, <code>fullMultiPolygonLiteral</code>, <code>fullPointLiteral</code>, and <code>fullPolygonLiteral</code> in <a href="#ODataABNF">OData-ABNF</a>.</p>
@@ -1812,7 +1812,7 @@ <h4 id="11252-system-query-option-expand"><a id="SystemQueryOptionexpand" href="
<details open><summary>
<h5 id="112521-expand-options"><a id="ExpandOptions" href="#ExpandOptions">11.2.5.2.1 Expand Options</a></h5>
</summary>
-<p>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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionexpand">OData-URL, section 5.1.3</a>.</p>
<p>Allowed system query options are <a href="#SystemQueryOptioncompute"><code>$compute</code></a>, <a href="#SystemQueryOptionselect"><code>$select</code></a>, <code>$expand</code>, and <a href="#ExpandOptionlevels"><code>$levels</code></a> for all navigation properties, plus <a href="#SystemQueryOptionfilter"><code>$filter</code></a>, <a href="#SystemQueryOptionorderby"><code>$orderby</code></a>, <a href="#SystemQueryOptionskip"><code>$skip</code></a>, <a href="#SystemQueryOptiontop"><code>$top</code></a>, <a href="#SystemQueryOptioncount"><code>$count</code></a>, and <a href="#SystemQueryOptionsearch"><code>$search</code></a> for collection-valued navigation properties.</p>
<div class="example">
<p>Example 41: for each customer entity within the <code>Customers</code> entity set, the value of those related <code>Orders</code> whose <code>Amount</code> is greater than 100 will be represented inline</p>
@@ -2200,12 +2200,12 @@ <h3 id="11211-system-query-option-format"><a id="SystemQueryOptionformat" href="
<p>Example 74: the request</p>
<pre><code>GET http://host/service/Orders?$format=application/json;metadata=full</code></pre>
</div>
-<p>is equivalent to a request with an <code>Accept</code> 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 <a href="#ODataJSON">OData-JSON</a>.</p>
+<p>is equivalent to a request with an <code>Accept</code> 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 <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadatafullodatametadatafull">OData-JSON, section 3.1.2</a>.</p>
<div class="example">
<p>Example 75: the request</p>
<pre><code>GET http://host/service/Orders?$format=json</code></pre>
</div>
-<p>is equivalent to a request with the <code>Accept</code> header set to <code>application/json</code>; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in <a href="#ODataJSON">OData-JSON</a>.</p>
+<p>is equivalent to a request with the <code>Accept</code> header set to <code>application/json</code>; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadataminimalodatametadataminimal">OData-JSON, section 3.1.1</a>.</p>
<p>In <a href="#MetadataDocumentRequest">metadata document requests</a>, the values <code>application/xml</code> and <code>application/json</code>, along with their subtypes and parameterized variants, as well as the format-specific abbreviations <code>xml</code> and <code>json</code>, are reserved for this specification.</p>
</details>
<details open><summary>
@@ -2569,7 +2569,7 @@ <h3 id="1145-delete-an-entity"><a id="DeleteanEntity" href="#DeleteanEntity">11.
<details open><summary>
<h3 id="1146-modifying-relationships-between-entities"><a id="ModifyingRelationshipsbetweenEntities" href="#ModifyingRelationshipsbetweenEntities">11.4.6 Modifying Relationships between Entities</a></h3>
</summary>
-<p>Relationships between entities are represented by navigation properties as described in <a href="#DataModel">Data Model</a>. URL conventions for navigation properties are described in <a href="#ODataURL">OData-URL</a>.</p>
+<p>Relationships between entities are represented by navigation properties as described in <a href="#DataModel">Data Model</a>. URL conventions for navigation properties are described in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#URLsforRelatedEntitieswithReferentialConstraints">OData-URL, section 4.3.3</a>.</p>
<details open><summary>
<h4 id="11461-add-a-reference-to-a-collection-valued-navigation-property"><a id="AddaReferencetoaCollectionValuedNavigationProperty" href="#AddaReferencetoaCollectionValuedNavigationProperty">11.4.6.1 Add a Reference to a Collection-Valued Navigation Property</a></h4>
</summary>
@@ -2581,7 +2581,7 @@ <h4 id="11461-add-a-reference-to-a-collection-valued-navigation-property"><a id=
<h4 id="11462-remove-a-reference-to-an-entity"><a id="RemoveaReferencetoanEntity" href="#RemoveaReferencetoanEntity">11.4.6.2 Remove a Reference to an Entity</a></h4>
</summary>
<p>A successful <code>DELETE</code> request to the URL that represents a reference to a related entity removes the relationship to that entity.</p>
-<p>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 <a href="#ResolvinganEntityId"><code>$id</code></a> 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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="#ResolvinganEntityId"><code>$id</code></a> 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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingReferencesbetweenEntities">OData-URL, section 4.4</a>.</p>
<p>For single-valued navigation properties, the <a href="#ResolvinganEntityId"><code>$id</code></a> query option MUST NOT be specified.</p>
<p>The <code>DELETE</code> request MUST NOT violate any <a href="#HandlingofIntegrityConstraints">integrity constraints</a> in the data model.</p>
<p>On successful completion, the response MUST be <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> and contain an empty body.</p>
@@ -2591,7 +2591,7 @@ <h4 id="11463-change-the-reference-in-a-single-valued-navigation-property"><a id
</summary>
<p>A successful <code>PUT</code> 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.</p>
<p>On successful completion, the response MUST be <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> and contain an empty body.</p>
-<p>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 <a href="#ODataJSON">OData-JSON</a> for details.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#RelatedEntities">OData-JSON, section 15.4</a> for details.</p>
<p>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 <a href="#ResponseCode405MethodNotAllowed"><code>405 Method Not Allowed</code></a> or an other appropriate error.</p>
</details>
<details open><summary>
@@ -2680,7 +2680,7 @@ <h4 id="11482-delete-stream-values"><a id="DeleteStreamValues" href="#DeleteStre
<details open><summary>
<h3 id="1149-managing-values-and-properties-directly"><a id="ManagingValuesandPropertiesDirectly" href="#ManagingValuesandPropertiesDirectly">11.4.9 Managing Values and Properties Directly</a></h3>
</summary>
-<p>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 <a href="#ODataURL">OData-URL</a> for details on addressing individual properties.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaProperty">OData-URL, section 4.6</a> for details on addressing individual properties.</p>
<details open><summary>
<h4 id="11491-update-a-primitive-property"><a id="UpdateaPrimitiveProperty" href="#UpdateaPrimitiveProperty">11.4.9.1 Update a Primitive Property</a></h4>
</summary>
@@ -2790,7 +2790,7 @@ <h4 id="114131-error-handling-when-replacing-a-collection-of-entities"><a id="Er
<h3 id="11414-update-members-of-a-collection"><a id="UpdateMembersofaCollection" href="#UpdateMembersofaCollection">11.4.14 Update Members of a Collection</a></h3>
</summary>
<p>Members of a collection can be updated by submitting a <code>PATCH</code> request to the URL constructed by appending <code>/$each</code> 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.</p>
-<p>The resource path of the collection MAY contain type-cast or filter segments to subset the collection, see <a href="#ODataURL">OData-URL</a>.</p>
+<p>The resource path of the collection MAY contain type-cast or filter segments to subset the collection, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes">OData-URL, section 4.11</a> and <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingaSubsetofaCollection">OData-URL, section 4.12</a>.</p>
<p>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.</p>
<p>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 <a href="#UpdateanEntity">updated</a> using <code>PATCH</code> semantics. Structured types MAY include nested collections or delta collections, in which case the semantics described in <a href="#UpdateaCollectionofEntities">Update a Collection of Entities</a> applies.</p>
<div class="example">
@@ -2825,7 +2825,7 @@ <h3 id="11415-delete-members-of-a-collection"><a id="DeleteMembersofaCollection"
<details open><summary>
<h2 id="115-operations"><a id="Operations" href="#Operations">11.5 Operations</a></h2>
</summary>
-<p>Custom operations (<a href="#Actions">Actions</a> and <a href="#Functions">Functions</a>) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See <code>Action</code>, <code>ActionImport</code>, <code>Function</code>, and <code>FunctionImport</code> in <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a>.</p>
+<p>Custom operations (<a href="#Actions">Actions</a> and <a href="#Functions">Functions</a>) allow encapsulating logic for modifying or requesting data that goes beyond simple CRUD described in the preceding sections of this chapter. See <code>Action</code>, <code>ActionImport</code>, <code>Function</code>, and <code>FunctionImport</code> in <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDLXML">OData-CSDLXML</a>.</p>
<details open><summary>
<h3 id="1151-binding-an-operation-to-a-resource"><a id="BindinganOperationtoaResource" href="#BindinganOperationtoaResource">11.5.1 Binding an Operation to a Resource</a></h3>
</summary>
@@ -2884,7 +2884,7 @@ <h3 id="1153-advertising-available-operations-within-a-payload"><a id="Advertisi
<span id="cb116-9"><a href="#cb116-9" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
<span id="cb116-10"><a href="#cb116-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
-<p>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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingOperations">OData-URL, section 4.5</a>.</p>
<p>Services can advertise that a function or action is not available for a particular instance by setting its value to null.</p>
<div class="example">
<p>Example 93: the <code>SampleEntities.MostRecentOrder</code> function is not available for customer <code>ALFKI</code></p>
@@ -2922,7 +2922,7 @@ <h4 id="11541-invoking-a-function"><a id="InvokingaFunction" href="#InvokingaFun
<p>If a collection-valued function has no result for a given parameter value combination, the response is the format-specific representation of an empty collection. If a single-valued function with a nullable return-type has no result, the service returns <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>.</p>
<p>If a single-valued function with a non-nullable return type has no result, the service returns <code>4xx</code>. For functions that return a single entity <a href="#ResponseCode404NotFound"><code>404 Not Found</code></a> is the appropriate response code.</p>
<p>For a composable function the processing is stopped when the function result requires a <code>4xx</code> response, and continues otherwise.</p>
-<p>Function imports preceded by the <code>$root</code> literal MAY be used in the <a href="#SystemQueryOptionfilter"><code>$filter</code></a> or <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> system query options, see <a href="#ODataURL">OData-URL</a>.</p>
+<p>Function imports preceded by the <code>$root</code> literal MAY be used in the <a href="#SystemQueryOptionfilter"><code>$filter</code></a> or <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> system query options, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionfilter">OData-URL, section 5.1.2</a> and <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionorderby">OData-URL, section 5.1.5</a>.</p>
<details open><summary>
<h5 id="115411-inline-parameter-syntax"><a id="InlineParameterSyntax" href="#InlineParameterSyntax">11.5.4.1.1 Inline Parameter Syntax</a></h5>
</summary>
@@ -2955,7 +2955,7 @@ <h4 id="11542-function-overload-resolution"><a id="Functionoverloadresolution" h
</summary>
<p>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.</p>
<p>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.</p>
-<p>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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes">OData-URL, section 4.11</a>.</p>
<p>Non-binding parameters MAY be marked as optional by annotating them with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter"><code>Core.OptionalParameter</code></a> defined in <a href="#ODataVocCore">OData-VocCore</a>. All parameters marked as optional MUST come after any parameters not marked as optional.</p>
<p>A function overload is selected if</p>
<ul>
@@ -3002,7 +3002,7 @@ <h4 id="11551-invoking-an-action"><a id="InvokinganAction" href="#InvokinganActi
<h4 id="11552-action-overload-resolution"><a id="ActionOverloadResolution" href="#ActionOverloadResolution">11.5.5.2 Action Overload Resolution</a></h4>
</summary>
<p>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.</p>
-<p>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 <a href="#ODataURL">OData-URL</a>.</p>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes">OData-URL, section 4.11</a>.</p>
</details>
</details>
</details>
@@ -3027,7 +3027,7 @@ <h2 id="117-batch-requests"><a id="BatchRequests" href="#BatchRequests">11.7 Bat
<p>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 <a href="#MetadataRequests">Metadata Request</a>, <a href="#RequestingData">Data Request</a>, <a href="#DataModification">Data Modification Request</a>, <a href="#InvokinganAction">Action invocation</a> request, or <a href="#InvokingaFunction">Function invocation</a> request.</p>
<p>Batch requests are submitted as a single HTTP <code>POST</code> request to the batch endpoint of a service, located at the URL <code>$batch</code> relative to the service root.</p>
<p>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.</p>
-<p>A batch request is represented using either the <a href="#MultipartBatchFormat">multipart batch format</a> defined in this document or the JSON batch format defined in <a href="#ODataJSON">OData-JSON</a>.</p>
+<p>A batch request is represented using either the <a href="#MultipartBatchFormat">multipart batch format</a> defined in this document or the JSON batch format defined in <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses">OData-JSON, section 19</a>.</p>
<p>If the set of request headers of a batch request are valid the service MUST return a <a href="#ResponseCode200OK"><code>200 OK</code></a> 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.</p>
<p>If the service receives a batch request with an invalid set of headers it MUST return a <a href="#ClientErrorResponses"><code>4xx</code> response code</a> and perform no further processing of the batch request.</p>
<details open><summary>
@@ -3516,12 +3516,12 @@ <h3 id="1211-odata-40-minimal-conformance-level"><a id="OData40MinimalConformanc
</ol></li>
<li>MUST follow OData guidelines for extensibility (<a href="#Extensibility">section 6</a> and all subsections)</li>
<li>MUST successfully parse the request according to <a href="#ODataABNF">OData-ABNF</a> for any supported system query options and follow the specification or fail the request</li>
-<li>MUST expose only data types defined in <a href="#ODataCSDL">OData-CSDLXML</a></li>
+<li>MUST expose only data types defined in <a href="#ODataCSDLXML">OData-CSDLXML</a></li>
<li>MUST NOT require clients to understand any metadata or instance annotations (<a href="#VocabularyExtensibility">section 6.4</a>), custom headers (<a href="#HeaderFieldExtensibility">section 6.5</a>), or custom content (<a href="#PayloadExtensibility">section 6.2</a>) in the payload in order to correctly consume the service</li>
<li>MUST NOT violate any OData update semantics (<a href="#DataModification">section 11.4</a> and all subsections)</li>
<li>MUST NOT violate any other OData-defined semantics</li>
<li>SHOULD support <code>$expand</code> (<a href="#SystemQueryOptionexpand">section 11.2.5.2</a>)</li>
-<li>SHOULD publish metadata at <code>$metadata</code> according to <a href="#ODataCSDL">OData-CSDLXML</a> and MAY publish metadata according to <a href="#ODataCSDL">OData-CSDLJSON</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
+<li>SHOULD publish metadata at <code>$metadata</code> according to <a href="#ODataCSDLXML">OData-CSDLXML</a> and MAY publish metadata according to <a href="#ODataCSDL">OData-CSDLJSON</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
<li>MUST support prefixed variants of supported headers and preference values</li>
<li>MUST support enumeration and duration literals in URLs with the type prefix</li>
</ol>
@@ -3532,7 +3532,7 @@ <h3 id="1211-odata-40-minimal-conformance-level"><a id="OData40MinimalConformanc
</ol>
<p>To be considered an <em>Updatable OData Service</em>, the service additionally:</p>
<ol start="18" type="1">
-<li>MUST include edit links (explicitly or implicitly) for all updatable or deletable resources according to <a href="#ODataJSON">OData-JSON</a></li>
+<li>MUST include edit links (explicitly or implicitly) for all updatable or deletable resources according to <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">OData-JSON, section 4.6.9</a></li>
<li>MUST support <code>POST</code> of new entities to insertable entity sets (<a href="#ReturningResultsfromDataModificationRequests">section 11.4.1.5</a>)</li>
<li>MUST support <code>POST</code> of new related entities to updatable navigation properties (<a href="#CreateanEntity">section 11.4.2</a>)</li>
<li>MUST support <code>POST</code> to <code>$ref</code> to add an existing entity to an updatable related collection (<a href="#AddaReferencetoaCollectionValuedNavigationProperty">section 11.4.6.1</a>)</li>
@@ -3558,7 +3558,7 @@ <h3 id="1212-odata-40-intermediate-conformance-level"><a id="OData40Intermediate
<li>MUST conform to the <a href="#OData40MinimalConformanceLevel">OData 4.0 Minimal Conformance Level</a></li>
<li>MUST successfully parse the request according to <a href="#ODataABNF">OData-ABNF</a> and follow the specification or fail the request</li>
<li>MUST support <code>$select</code> (<a href="#SystemQueryOptionselect">section 11.2.5.1</a>)</li>
-<li>MUST support casting to a derived type according to <a href="#ODataURL">OData-URL</a> if derived types are present in the model</li>
+<li>MUST support casting to a derived type according to <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes">OData-URL, section 4.11</a> if derived types are present in the model</li>
<li>MUST support <code>$top</code> (<a href="#SystemQueryOptiontop">section 11.2.6.3</a>)</li>
<li>MUST support <code>/$value</code> on media entities (<a href="#MetadataDocumentRequest">section 11.1.2</a>) and individual properties (<a href="#RequestingaRawValueusingvalue">section 11.2.4.2</a>)</li>
<li>MUST support <code>$filter</code> (<a href="#SystemQueryOptionfilter">section 11.2.6.1</a>)
@@ -3569,7 +3569,7 @@ <h3 id="1212-odata-40-intermediate-conformance-level"><a id="OData40Intermediate
<li>SHOULD support the canonical functions (<a href="#BuiltinQueryFunctions">section 11.2.6.1.2</a>) and MUST fail the request for any unsupported canonical functions</li>
<li>SHOULD support <code>$filter</code> on expanded entities (<a href="#ExpandOptions">section 11.2.5.2.1</a>)</li>
</ol></li>
-<li>SHOULD publish metadata at <code>$metadata</code> according to <a href="#ODataCSDL">OData-CSDLXML</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
+<li>SHOULD publish metadata at <code>$metadata</code> according to <a href="#ODataCSDLXML">OData-CSDLXML</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
<li>SHOULD support the <a href="#ODataJSON">OData-JSON</a> format</li>
<li>SHOULD consider supporting basic authentication as defined in <a href="#rfc7617">RFC7617</a> over HTTPS for the highest level of interoperability with generic clients</li>
<li>SHOULD support the <code>$search</code> system query option (<a href="#SystemQueryOptionsearch">section 11.2.6.6</a>)</li>
@@ -3587,7 +3587,7 @@ <h3 id="1213-odata-40-advanced-conformance-level"><a id="OData40AdvancedConforma
<p>In order to conform to the OData Advanced Conformance Level, a service:</p>
<ol type="1">
<li>MUST conform to at least the <a href="#OData40IntermediateConformanceLevel">OData 4.0 Intermediate Conformance Level</a></li>
-<li>MUST publish metadata at <code>$metadata</code> according to <a href="#ODataCSDL">OData-CSDLXML</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
+<li>MUST publish metadata at <code>$metadata</code> according to <a href="#ODataCSDLXML">OData-CSDLXML</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
<li>MUST support the <a href="#ODataJSON">OData-JSON</a> format</li>
<li>MUST support the <code>/$count</code> segment on navigation and collection properties (<a href="#RequestingtheNumberofItemsinaCollection">section 11.2.10</a>)</li>
<li>MUST support the lambda operators <code>any</code> and <code>all</code> on navigation- and and collection-valued properties (<a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LambdaOperators">OData-URL, section 5.1.1.13</a>)</li>
@@ -3607,11 +3607,11 @@ <h3 id="1213-odata-40-advanced-conformance-level"><a id="OData40AdvancedConforma
<li>MAY support <code>$compute</code> on expanded properties</li>
</ol></li>
<li>MUST support the <code>$search</code> system query option (<a href="#SystemQueryOptionsearch">section 11.2.6.6</a>)</li>
-<li>MUST support batch requests according to the multipart format (<a href="#BatchRequests">section 11.7</a> and all subsections) and MAY support batch requests according to the JSON Batch format defined in <a href="#ODataJSON">OData-JSON</a></li>
-<li>MUST support the resource path conventions defined in <a href="#ODataURL">OData-URL</a></li>
+<li>MUST support batch requests according to the multipart format (<a href="#BatchRequests">section 11.7</a> and all subsections) and MAY support batch requests according to the JSON Batch format defined in <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses">OData-JSON, section 19</a></li>
+<li>MUST support the resource path conventions defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ResourcePath">OData-URL, section 4</a></li>
<li>SHOULD support asynchronous requests (<a href="#AsynchronousRequests">section 11.6</a>)</li>
<li>SHOULD support Delta change tracking (<a href="#RequestingChanges">section 11.3</a>)</li>
-<li>SHOULD support cross-join queries defined in <a href="#ODataURL">OData-URL</a></li>
+<li>SHOULD support cross-join queries defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingtheCrossJoinofEntitySets">OData-URL, section 4.15</a></li>
<li>MAY support the <code>$compute</code> system query option (<a href="#SystemQueryOptioncompute">section 11.2.5.3</a>)</li>
</ol>
</details>
@@ -3648,12 +3648,12 @@ <h3 id="1221-odata-401-minimal-conformance-level"><a id="OData401MinimalConforma
<li>SHOULD support negative indexes for the substring function</li>
<li>MAY support Key-As-Segment URL convention
<ol type="1">
-<li>MUST also support canonical URL conventions (described in <a href="#ODataURL">OData-URL</a>) or include URLs in payload</li>
+<li>MUST also support canonical URL conventions (described in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL">OData-URL, section 4.3.1</a>) or include URLs in payload</li>
</ol></li>
<li>MAY support the count of a filtered collection in a common expression</li>
<li>MAY support equal and non-equal structural comparison</li>
</ol></li>
-<li>SHOULD publish metadata at <code>$metadata</code> according to both <a href="#ODataCSDL">OData-CSDLXML</a> and <a href="#ODataCSDL">OData-CSDLJSON</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
+<li>SHOULD publish metadata at <code>$metadata</code> according to both <a href="#ODataCSDLXML">OData-CSDLXML</a> and <a href="#ODataCSDL">OData-CSDLJSON</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
<li>SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case</li>
<li>SHOULD return the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ODataVersions"><code>Core.ODataVersions</code></a> annotation</li>
<li>SHOULD report capabilities through the Capabilities vocabulary</li>
@@ -3712,7 +3712,7 @@ <h3 id="1223-odata-401-advanced-conformance-level"><a id="OData401AdvancedConfor
<li>SHOULD support <code>$search</code> on selected collection-valued properties</li>
</ol></li>
<li>MUST publish metadata at <code>$metadata</code> according to <a href="#ODataCSDL">OData-CSDLJSON</a> (<a href="#MetadataDocumentRequest">section 11.1.2</a>)</li>
-<li>MUST support batch requests according both to the multipart format (<a href="#BatchRequests">section 11.7</a> and all subsections) and the JSON Batch format defined in <a href="#ODataJSON">OData-JSON</a></li>
+<li>MUST support batch requests according both to the multipart format (<a href="#BatchRequests">section 11.7</a> and all subsections) and the JSON Batch format defined in <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#BatchRequestsandResponses">OData-JSON, section 19</a></li>
<li>SHOULD support filtering a collection using a <code>/$filter</code> path segment</li>
<li>SHOULD support nested parameter alias assignments in <code>$select</code> and <code>$expand</code></li>
<li>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 <a href="#DefaultNamespaces">default namespaces</a> with a case-insensitive comparison</li>
@@ -3727,7 +3727,7 @@ <h2 id="123-interoperable-odata-clients"><a id="InteroperableODataClients" href=
<ol type="1">
<li>MUST specify the <code>OData-MaxVersion</code> header in requests (<a href="#HeaderODataMaxVersion">section 8.2.7</a>)</li>
<li>MUST specify <code>OData-Version</code> (<a href="#HeaderODataVersion">section 8.1.5</a>) and <code>Content-Type</code> (<a href="#HeaderContentType">section 8.1.1</a>) in any request with a payload</li>
-<li>MUST be a conforming consumer of OData as defined in <a href="#ODataJSON">OData-JSON</a></li>
+<li>MUST be a conforming consumer of OData as defined in <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#Conformance">OData-JSON, section 23</a></li>
<li>MUST follow redirects (<a href="#ResponseCode3xxRedirection">section 9.1.5</a>)</li>
<li>MUST correctly handle next links (<a href="#ServerDrivenPaging">section 11.2.6.7</a>)</li>
<li>MUST support instances returning properties and navigation properties not specified in metadata (<a href="#RequestingData">section 11.2</a>)</li>
@@ -3739,8 +3739,8 @@ <h2 id="123-interoperable-odata-clients"><a id="InteroperableODataClients" href=
<li>MAY request entity references in place of entities previously returned in the response (<a href="#RequestingEntityReferences">section 11.2.8</a>)</li>
<li>MAY support deleted entities, link entities, deleted link entities in a delta response (<a href="#RequestingChanges">section 11.3</a>)</li>
<li>MAY support asynchronous responses (<a href="#AsynchronousRequests">section 11.6</a>)</li>
-<li>MAY support <code>metadata=minimal</code> in a JSON response (see <a href="#ODataJSON">OData-JSON</a>)</li>
-<li>MAY support <code>streaming</code> in a JSON response (see <a href="#ODataJSON">OData-JSON</a>)</li>
+<li>MAY support <code>metadata=minimal</code> in a JSON response (see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadataminimalodatametadataminimal">OData-JSON, section 3.1.1</a>)</li>
+<li>MAY support <code>streaming</code> in a JSON response (see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PayloadOrderingConstraints">OData-JSON, section 4.5</a>)</li>
</ol>
<p>In addition, interoperable OData 4.01 clients</p>
<ol start="17" type="1">
@@ -3768,9 +3768,10 @@ <h6><span id="ODataABNF">OData-ABNF</span></h6>
<h6><span id="ODataAggregation">OData-Aggregation</span></h6>
<p><em>OData Extension for Data Aggregation Version 4.02.</em><br />
See link in “<a href="#RelatedWork">Related work</a>” section on cover page.</p>
-<h6><span id="ODataCSDL">OData-CSDL</span></h6>
+<h6><span id="ODataCSDL">OData-CSDLJSON</span></h6>
<p><em>OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02.</em><br />
See link in “<a href="#RelatedWork">Related work</a>” section on cover page.</p>
+<h6><span id="ODataCSDLXML">OData-CSDLXML</span></h6>
<p><em>OData Common Schema Definition Language (CSDL) XML Representation Version 4.02.</em><br />
See link in “<a href="#RelatedWork">Related work</a>” section on cover page.</p>
<h6><span id="ODataJSON">OData-JSON</span></h6>
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.
## <a id="Annotations" href="#Annotations">3.1 Annotations</a>
@@ -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.
### <a id="HeaderContentEncoding" href="#HeaderContentEncoding">8.1.2 Header `Content-Encoding`</a>
@@ -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).
### <a id="HeaderPreferenceApplied" href="#HeaderPreferenceApplied">8.3.6 Header `Preference-Applied`</a>
@@ -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.
#### <a id="RequestingaRawValueusingvalue" href="#RequestingaRawValueusingvalue">11.2.4.2 Requesting a Raw Value using `$value`</a>
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).
#### <a id="AddaReferencetoaCollectionValuedNavigationProperty" href="#AddaReferencetoaCollectionValuedNavigationProperty">11.4.6.1 Add a Reference to a Collection-Valued Navigation Property</a>
@@ -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.
#### <a id="UpdateaPrimitiveProperty" href="#UpdateaPrimitiveProperty">11.4.9.1 Update a Primitive Property</a>
@@ -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).
### <a id="BindinganOperationtoaResource" href="#BindinganOperationtoaResource">11.5.1 Binding an Operation to a Resource</a>
@@ -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).
##### <a id="InlineParameterSyntax" href="#InlineParameterSyntax">11.5.4.1.1 Inline Parameter Syntax</a>
@@ -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).
## <a id="AsynchronousRequests" href="#AsynchronousRequests">11.6 Asynchronous Requests</a>
@@ -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))
## <a id="OData401ServiceConformanceLevels" href="#OData401ServiceConformanceLevels">12.2 OData 4.01 Service Conformance Levels</a>
@@ -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 @@ <h3 id="432-operations-on-temporal-objects"><a id="OperationsonTemporalObjects"
</summary>
<p>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.</p>
<p>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.</p>
-<p>These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data <a href="#ODataVocTemporal">OData-VocTemporal</a>. Implementations SHOULD consider the preferences <code>return=representation</code> and <code>return=minimal</code> as specified inv<a href="#ODataProtocol">OData-Protocol</a>. 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.</p>
+<p>These convenience operations are modeled as bound actions and defined in the vocabulary for temporal data <a href="#ODataVocTemporal">OData-VocTemporal</a>. Implementations SHOULD consider the preferences <code>return=representation</code> and <code>return=minimal</code> as specified in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Preferencereturnrepresentationandreturnminimal">OData-Protocol, section 8.2.8.7</a>. 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.</p>
<p>All actions define a collection of entities as their binding parameter. This collection can be</p>
<ul>
<li>A snapshot entity set</li>
@@ -1949,7 +1949,7 @@ <h4 id="4321-update-during-a-period"><a id="UpdateduringaPeriod" href="#Updatedu
<li>The “delta time slices” in <code>deltaTimeslices</code> are processed in the order of the collection.</li>
<li>For each delta time slice all time slices from the bound collection are selected whose temporal object key values are identical to the values of corresponding properties present in the delta time slice, and whose application-time period overlaps with the period of the delta time slice.</li>
<li>Selected time slices whose period is not fully included in the period of the delta time slice are split into two or three consecutive time slices, one with fully included period, and one or two with a non-overlapping period immediately before or after the delta time slice’s period.</li>
-<li>Then all fully included time slices (including ones created in the previous step) are updated following the rules for updating entities specified in <a href="#ODataProtocol">OData-Protocol</a>.</li>
+<li>Then all fully included time slices (including ones created in the previous step) are updated following the rules for updating entities specified in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity">OData-Protocol, section 11.4.3</a>.</li>
<li>Gaps between selected time slices in the period to update are not affected.</li>
</ol>
<p>On success it returns the created or updated time slices.</p>
@@ -2215,9 +2215,9 @@ <h4 id="4322-upsert-during-a-period"><a id="UpsertduringaPeriod" href="#Upsertdu
<ol type="1">
<li>copying the property values of the preceding time slice (except for computed properties),</li>
<li>setting the period boundaries to close the gap, and then</li>
-<li>updating the new time slice following the rules for updating entities specified in <a href="#ODataProtocol">OData-Protocol</a>.</li>
+<li>updating the new time slice following the rules for updating entities specified in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpdateanEntity">OData-Protocol, section 11.4.3</a>.</li>
</ol>
-<p>If no preceding time slice exists, the time slice is created following the rules for creating entities specified in <a href="#ODataProtocol">OData-Protocol</a>.</p></li>
+<p>If no preceding time slice exists, the time slice is created following the rules for creating entities specified in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#CreateanEntity">OData-Protocol, section 11.4.2</a>.</p></li>
</ol>
<p>On success it returns the created or updated time slices.</p>
<div class="example">
@@ -2396,7 +2396,7 @@ <h4 id="4323-delete-during-a-period"><a id="DeleteduringaPeriod" href="#Deletedu
<li>The “delta time slices” in <code>deltaTimeslices</code> are processed in the order of the collection.</li>
<li>For each delta time slice all time slices from the bound collection are selected whose temporal object key values are identical to the values of corresponding properties present in the delta time slice, and whose application-time period overlaps with the period of the delta time slice.</li>
<li>Selected time slices whose period is not fully included in the period of the delta time slice are split into two consecutive time slices, one with non-overlapping, and one with fully included period.</li>
-<li>Then all fully included time slices (including ones created in the previous step) are deleted following the rules for deleting entities specified in <a href="#ODataProtocol">OData-Protocol</a>.</li>
+<li>Then all fully included time slices (including ones created in the previous step) are deleted following the rules for deleting entities specified in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DeleteanEntity">OData-Protocol, section 11.4.5</a>.</li>
</ol>
<p>On success it returns the deleted time slices.</p>
</details>
@@ -2488,7 +2488,7 @@ <h1 id="appendix-b-acknowledgments"><a id="Acknowledgments" href="#Acknowledgmen
<details open><summary>
<h2 id="b1-special-thanks"><a id="SpecialThanks" href="#SpecialThanks">B.1 Special Thanks</a></h2>
</summary>
-<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="#ODataProtocol">OData-Protocol</a> are gratefully acknowledged.</p>
+<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants">OData-Protocol, section C.2</a>, are gratefully acknowledged.</p>
<p>Special thanks to Andrew Eisenberg, whose contributions in the early stages of the OData TC were invaluable to getting this extension specification on track.</p>
</details>
<details open><summary>
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:
## <a id="SpecialThanks" href="#SpecialThanks">B.1 Special Thanks</a>
-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 @@ <h2 id="22-url-syntax"><a id="URLSyntax" href="#URLSyntax">2.2 URL Syntax</a></h
<details open><summary>
<h1 id="3-service-root-url"><a id="ServiceRootURL" href="#ServiceRootURL">3 Service Root URL</a></h1>
</summary>
-<p>The service root URL identifies the root of an OData service. A <code>GET</code> request to this URL returns the format-specific service document, see <a href="#ODataJSON">OData-JSON</a>.</p>
+<p>The service root URL identifies the root of an OData service. A <code>GET</code> request to this URL returns the format-specific service document, see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ServiceDocument">OData-JSON, section 5</a>.</p>
<p>The service root URL MUST terminate in a forward slash.</p>
<p>The service document enables simple hypermedia-driven clients to enumerate and explore the resources published by the OData service.</p>
</details>
@@ -575,7 +575,7 @@ <h1 id="4-resource-path"><a id="ResourcePath" href="#ResourcePath">4 Resource Pa
<details open><summary>
<h2 id="41-addressing-the-model-for-a-service"><a id="AddressingtheModelforaService" href="#AddressingtheModelforaService">4.1 Addressing the Model for a Service</a></h2>
</summary>
-<p>OData services expose their entity model according to <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a> at the metadata URL, formed by appending <code>$metadata</code> to the <a href="#ServiceRootURL">service root URL</a>.</p>
+<p>OData services expose their entity model according to <a href="#ODataCSDL">OData-CSDL</a> at the metadata URL, formed by appending <code>$metadata</code> to the <a href="#ServiceRootURL">service root URL</a>.</p>
<div class="example">
<p>Example 5: Metadata document URL</p>
<pre><code>http://host/service/$metadata</code></pre>
@@ -721,7 +721,7 @@ <h3 id="431-canonical-url"><a id="CanonicalURL" href="#CanonicalURL">4.3.1 Canon
<details open><summary>
<h3 id="432-canonical-url-for-contained-entities"><a id="CanonicalURLforContainedEntities" href="#CanonicalURLforContainedEntities">4.3.2 Canonical URL for Contained Entities</a></h3>
</summary>
-<p>For contained entities (i.e. related via a containment navigation property, see <a href="#ODataCSDL">OData-CSDLJSON</a> or <a href="#ODataCSDL">OData-CSDLXML</a>) the canonical URL is the canonical URL of the containing entity followed by:</p>
+<p>For contained entities (i.e. related via a containment navigation property, see <a href="#ODataCSDL">OData-CSDLJSON</a>) the canonical URL is the canonical URL of the containing entity followed by:</p>
<ul>
<li>A <a href="#AddressingDerivedTypes">type-cast segment</a> if the navigation property is defined on a type derived from the entity type declared for the entity set,</li>
<li>A path segment for the containment navigation property, and</li>
@@ -752,7 +752,7 @@ <h3 id="434-resolving-an-entity-id"><a id="ResolvinganEntityId" href="#Resolving
<p>Example 23: request the entity representation for an entity-id</p>
<pre><code>http://host/service/$entity?$id=Products(0)</code></pre>
</div>
-<p>The semantics of <code>$entity</code> are covered in the <a href="#ODataProtocol">OData-Protocol</a> document.</p>
+<p>The semantics of <code>$entity</code> are covered in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ContextURL">OData-Protocol, section 10</a>.</p>
</details>
<details open><summary>
<h3 id="435-alternate-keys"><a id="AlternateKeys" href="#AlternateKeys">4.3.5 Alternate Keys</a></h3>
@@ -797,7 +797,7 @@ <h3 id="436-key-as-segment-convention"><a id="KeyasSegmentConvention" href="#Key
<ol type="1">
<li>matches a defined OData segment (starting with “<code>$</code>”), treat it as such</li>
<li>matches a qualified bound function, bound action, or type name, treat it as such</li>
-<li>matches an unqualified bound function, bound action, or type name defined in a default namespace (see <a href="#ODataProtocol">OData-Protocol</a>) treat it as such</li>
+<li>matches an unqualified bound function, bound action, or type name defined in a default namespace (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces">OData-Protocol, section 4.4</a>) treat it as such</li>
<li>treat as a key value</li>
</ol>
<p>For maximum interoperability, services that support the key-as-segment convention SHOULD also support the canonical <a href="#CanonicalURL">parentheses-style convention</a> 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.</p>
@@ -813,7 +813,7 @@ <h2 id="44-addressing-references-between-entities"><a id="AddressingReferencesbe
<p>Example 28: URL addressing the references between <code>Categories(1)</code> and <code>Products</code></p>
<pre><code>http://host/service/Categories(1)/Products/$ref</code></pre>
</div>
-<p>Resource paths addressing a single related entity reference can be used in <code>DELETE</code> 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 <code>$id</code> in order to identify a single entity reference within the collection to be removed. The entity-id specified by <code>$id</code> may be expressed absolute or relative to the request URL. For details see <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>Resource paths addressing a single related entity reference can be used in <code>DELETE</code> 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 <code>$id</code> in order to identify a single entity reference within the collection to be removed. The entity-id specified by <code>$id</code> may be expressed absolute or relative to the request URL. For details see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences">OData-Protocol, section 4.1</a>.</p>
<div class="example">
<p>Example 29: three ways of unrelating <code>Categories(1)</code> and <code>Products(0)</code>; the second option is supported only in OData 4.01</p>
<pre><code>DELETE http://host/service/Categories(1)/Products/$ref?$id=../../Products(0)</code></pre>
@@ -824,8 +824,8 @@ <h2 id="44-addressing-references-between-entities"><a id="AddressingReferencesbe
<details open><summary>
<h2 id="45-addressing-operations"><a id="AddressingOperations" href="#AddressingOperations">4.5 Addressing Operations</a></h2>
</summary>
-<p>The semantic rules for addressing and invoking actions and functions are defined in the <a href="#ODataProtocol">OData-Protocol</a> document.</p>
-<p>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 <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace"><code>Core.DefaultNamespace</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a>. For more information on default namespaces, see Default Namespaces in <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>The semantic rules for addressing and invoking actions and functions are defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Operations">OData-Protocol, section 11.5</a>.</p>
+<p>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 <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace"><code>Core.DefaultNamespace</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a>. For more information on default namespaces, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces">OData-Protocol, section 4.4</a>.</p>
<details open><summary>
<h3 id="451-addressing-actions"><a id="AddressingActions" href="#AddressingActions">4.5.1 Addressing Actions</a></h3>
</summary>
@@ -845,7 +845,7 @@ <h3 id="452-addressing-functions"><a id="AddressingFunctions" href="#AddressingF
<li>The bound function call syntax rules <code>boundComplexFunctionCall</code>, <code>boundComplexColFunctionCall</code>, <code>boundEntityFunctionCall</code>, <code>boundEntityColFunctionCall</code>, <code>boundPrimitiveFunctionCall</code> and <code>boundPrimitiveColFunctionCall</code> define the grammar in the <code>resourcePath</code> for addressing and providing parameters for a function that is appended to a <code>resourcePath</code> that identifies some resources that can be used as the binding parameter value when invoking the function.</li>
<li>The <code>boundOperation</code> syntax rule (which encompasses the bound function call syntax rules), when used by the <code>resourcePath</code> syntax rule, illustrates how a bound function call can be appended to a <code>resourcePath</code>.</li>
<li>The <code>functionExpr</code> and <code>boundFunctionExpr</code> syntax rules as used by the <code>commonExpr</code> syntax rule define the grammar for invoking functions, for example to help filter and order resources identified by the <code>resourcePath</code> of the URL.</li>
-<li>The <code>aliasAndValue</code> syntax rule defines the grammar for providing function parameter values using Parameter Alias Syntax, see <a href="#ODataProtocol">OData-Protocol</a>.</li>
+<li>The <code>aliasAndValue</code> syntax rule defines the grammar for providing function parameter values using Parameter Alias Syntax, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ParameterAliases">OData-Protocol, section 11.2.6.1.3</a>.</li>
</ul>
<p>Note: there is no literal representation for <code>Edm.Stream</code> values in URLs, so it is not possible to pass <code>Edm.Stream</code> 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 <a href="#PathExpressions">path expressions</a> of type <code>Edm.Stream</code> as values of non-binding function parameters. The aliases can contain <a href="#CommonExpressionSyntax">common expressions</a>. In the case of a bound function these MAY contain <a href="#PathExpressions">path expressions</a>, which the service evaluates on the binding parameter value.</p>
<div class="example">
@@ -927,7 +927,7 @@ <h2 id="411-addressing-derived-types"><a id="AddressingDerivedTypes" href="#Addr
</summary>
<p>Any resource path or path expression identifying a collection of entities or complex type instances can be appended with a <em>type-cast segment</em>, that is a path segment containing the qualified name of a type derived from the declared item type of the collection. The result will be restricted to instances of the derived type and may be empty.</p>
<p>Any resource path or path expression identifying a single entity or complex type instance can be appended with a type-cast segment containing the qualified name of a type derived from the declared type of the identified resource. If used in a resource path and the identified resource is not an instance of the derived type, the request will result in a <code>404 Not Found</code> response. If used in a path expression, the type cast will evaluate to <code>null</code>.</p>
-<p>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 <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace"><code>Core.DefaultNamespace</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a>. For more information on default namespaces, see Default Namespaces in <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>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 <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace"><code>Core.DefaultNamespace</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a>. For more information on default namespaces, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces">OData-Protocol, section 4.4</a>.</p>
<p>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 <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#MayImplement"><code>Core.MayImplement</code></a> annotation term, defined in <a href="#ODataVocCore">OData-VocCore</a>.</p>
<div class="example">
<p>Example 37: entity set restricted to <code>VipCustomer</code> instances</p>
@@ -1128,7 +1128,7 @@ <h2 id="51-system-query-options"><a id="SystemQueryOptions" href="#SystemQueryOp
<p>System query options SHOULD NOT be applied to a <code>DELETE</code> request.</p>
<p>An OData service may support some or all of the system query options defined. If a data service does not support a system query option, it MUST reject any request that contains the unsupported option.</p>
<p>The same system query option, irrespective of casing or whether or not it is prefixed with a <code>$</code>, MUST NOT be specified more than once for any resource.</p>
-<p>The semantics of all system query options are defined in the <a href="#ODataProtocol">OData-Protocol</a> document.</p>
+<p>The semantics of all system query options are defined in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptions">OData-Protocol, section 11.2.1</a>.</p>
<p>The grammar and syntax rules for system query options are defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>Dynamic properties can be used in the same way as declared properties. If they are not defined on an instance, they evaluate to <code>null</code>.</p>
<details open><summary>
@@ -2060,7 +2060,7 @@ <h4 id="51116-annotation-values-in-expressions"><a id="AnnotationValuesinExpress
<p>Example 121: Return Employees that have any error messages in the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Messages"><code>Core.Messages</code></a> annotation</p>
<pre><code>http://host/service/Employees?$filter=@Core.Messages/any(m:m/severity eq 'error')</code></pre>
</div>
-<p>Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace"><code>Core.DefaultNamespace</code></a> annotation term defined in <a href="#ODataVocCore">OData-VocCore</a>. For more information on default namespaces, see Default Namespaces in <a href="#ODataProtocol">OData-Protocol</a>. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a <a href="#ParameterAliases">parameter alias</a>, 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.</p>
+<p>Services MAY additionally support the use of the unqualified term name by defining one or more default namespaces through the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DefaultNamespace"><code>Core.DefaultNamespace</code></a> annotation term defined in <a href="#ODataVocCore">OData-VocCore</a>. For more information on default namespaces, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DefaultNamespaces">OData-Protocol, section 4.4</a>. This short notation however uses the same name pattern as parameter aliases. If a query option is specified as a <a href="#ParameterAliases">parameter alias</a>, 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.</p>
</details>
<details open><summary>
<h4 id="51117-operator-precedence"><a id="OperatorPrecedence" href="#OperatorPrecedence">5.1.1.17 Operator Precedence</a></h4>
@@ -2374,7 +2374,7 @@ <h3 id="514-system-query-option-select"><a id="SystemQueryOptionselect" href="#S
&$expand=Addresses/Country</code></pre>
</div>
<p>Any structural property, non-expanded navigation property, or operation not requested as a select item (explicitly or via a star) SHOULD be omitted from the response.</p>
-<p>Annotations requested in <code>$select</code> MUST be included in the response; <code>$select</code> overrules the <code>include-annotations</code> preference (see <a href="#ODataProtocol">OData-Protocol</a>) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via <code>$select</code>. The <code>Preference-Applied</code> response header only reflects the set of annotations included due to the <code>include-annotations</code> preference and not those only included due to <code>$select</code>.</p>
+<p>Annotations requested in <code>$select</code> MUST be included in the response; <code>$select</code> overrules the <code>include-annotations</code> preference (see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Preferenceincludeannotationsodataincludeannotations">OData-Protocol, section 8.2.8.4</a>) for the explicitly requested annotations. Additional annotations matching the preference can be included even if not requested via <code>$select</code>. The <code>Preference-Applied</code> response header only reflects the set of annotations included due to the <code>include-annotations</code> preference and not those only included due to <code>$select</code>.</p>
<p>If any select item (including a star) is specified, actions and functions SHOULD be omitted unless explicitly requested.</p>
<p>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.</p>
<p>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.</p>
@@ -2388,20 +2388,20 @@ <h3 id="514-system-query-option-select"><a id="SystemQueryOptionselect" href="#S
<h3 id="515-system-query-option-orderby"><a id="SystemQueryOptionorderby" href="#SystemQueryOptionorderby">5.1.5 System Query Option <code>$orderby</code></a></h3>
</summary>
<p>The <code>$orderby</code> system query option allows clients to request resources in a particular order.</p>
-<p>The semantics of <code>$orderby</code> are covered in the <a href="#ODataProtocol">OData-Protocol</a> document.</p>
+<p>The semantics of <code>$orderby</code> are covered in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionorderby">OData-Protocol, section 11.2.6.2</a>.</p>
<p>The <a href="#ODataABNF">OData-ABNF</a> <code>orderby</code> syntax rule defines the formal grammar of the <code>$orderby</code> query option.</p>
</details>
<details open><summary>
<h3 id="516-system-query-options-top-and-skip"><a id="SystemQueryOptionstopandskip" href="#SystemQueryOptionstopandskip">5.1.6 System Query Options <code>$top</code> and <code>$skip</code></a></h3>
</summary>
<p>The <code>$top</code> system query option requests the number of items in the queried collection to be included in the result. The <code>$skip</code> 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 <code>$top</code> and <code>$skip</code>.</p>
-<p>The semantics of <code>$top</code> and <code>$skip</code> are covered in the <a href="#ODataProtocol">OData-Protocol</a> document. The <a href="#ODataABNF">OData-ABNF</a> <code>top</code> and <code>skip</code> syntax rules define the formal grammar of the <code>$top</code> and <code>$skip</code> query options respectively.</p>
+<p>The semantics of <code>$top</code> and <code>$skip</code> are covered in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptiontop">OData-Protocol, section 11.2.6.3</a> and <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionskip">OData-Protocol, section 11.2.6.4</a>. The <a href="#ODataABNF">OData-ABNF</a> <code>top</code> and <code>skip</code> syntax rules define the formal grammar of the <code>$top</code> and <code>$skip</code> query options respectively.</p>
</details>
<details open><summary>
<h3 id="517-system-query-option-count"><a id="SystemQueryOptioncount" href="#SystemQueryOptioncount">5.1.7 System Query Option <code>$count</code></a></h3>
</summary>
<p>The <code>$count</code> system query option allows clients to request a count of the matching resources included with the resources in the response. The <code>$count</code> query option has a Boolean value of <code>true</code> or <code>false</code>.</p>
-<p>The semantics of <code>$count</code> is covered in the <a href="#ODataProtocol">OData-Protocol</a> document.</p>
+<p>The semantics of <code>$count</code> is covered in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptioncount">OData-Protocol, section 11.2.6.5</a>.</p>
</details>
<details open><summary>
<h3 id="518-system-query-option-search"><a id="SystemQueryOptionsearch" href="#SystemQueryOptionsearch">5.1.8 System Query Option <code>$search</code></a></h3>
@@ -2435,7 +2435,7 @@ <h4 id="5181-search-expressions"><a id="SearchExpressions" href="#SearchExpressi
<h3 id="519-system-query-option-format"><a id="SystemQueryOptionformat" href="#SystemQueryOptionformat">5.1.9 System Query Option <code>$format</code></a></h3>
</summary>
<p>The <code>$format</code> 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 <code>$format</code> takes precedence over standard content-type negotiation.</p>
-<p>The semantics of <code>$format</code> is covered in the <a href="#ODataProtocol">OData-Protocol</a> document.</p>
+<p>The semantics of <code>$format</code> is covered in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionformat">OData-Protocol, section 11.2.11</a>.</p>
<p>The <a href="#ODataABNF">OData-ABNF</a> <code>format</code> syntax rule defines the formal grammar of the <code>$format</code> query option.</p>
</details>
<details open><summary>
@@ -2464,7 +2464,7 @@ <h3 id="5111-system-query-option-index"><a id="SystemQueryOptionindex" href="#Sy
<details open><summary>
<h3 id="5112-system-query-option-schemaversion"><a id="SystemQueryOptionschemaversion" href="#SystemQueryOptionschemaversion">5.1.12 System Query Option <code>$schemaversion</code></a></h3>
</summary>
-<p>The <code>$schemaversion</code> system query option allows clients to specify the version of the schema against which the request is made. The semantics of <code>$schemaversion</code> is covered in the <a href="#ODataProtocol">OData-Protocol</a> document.</p>
+<p>The <code>$schemaversion</code> system query option allows clients to specify the version of the schema against which the request is made. The semantics of <code>$schemaversion</code> is covered in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion">OData-Protocol, section 11.2.12</a>.</p>
<p>The <a href="#ODataABNF">OData-ABNF</a> <code>schemaversion</code> syntax rule defines the formal grammar of the <code>$schemaversion</code> query option</p>
</details>
</details>
@@ -2483,7 +2483,7 @@ <h2 id="53-parameter-aliases"><a id="ParameterAliases" href="#ParameterAliases">
</summary>
<p>Parameter aliases can be used in place of literal values in entity keys, <a href="#AddressingFunctions">function</a> parameters, or within a <a href="#SystemQueryOptionfilter"><code>$filter</code></a> or <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> expression.</p>
<p>Parameter aliases MUST start with an <code>@</code> character, see rule <code>parameterAlias</code> in <a href="#ODataABNF">OData-ABNF</a>.</p>
-<p>The semantics of parameter aliases are covered in <a href="#ODataProtocol">OData-Protocol</a>. The <a href="#ODataABNF">OData-ABNF</a> rule <code>aliasAndValue</code> defines the formal grammar for passing parameter alias values as query options.</p>
+<p>The semantics of parameter aliases are covered in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ParameterAliases">OData-Protocol, section 11.2.6.1.3</a>. The <a href="#ODataABNF">OData-ABNF</a> rule <code>aliasAndValue</code> defines the formal grammar for passing parameter alias values as query options.</p>
<div class="example">
<p>Example 144:</p>
<pre><code>http://host/service/Movies?$filter=contains(@word,Title)&@word='Black'</code></pre>
@@ -2503,7 +2503,7 @@ <h2 id="53-parameter-aliases"><a id="ParameterAliases" href="#ParameterAliases">
<details open><summary>
<h1 id="6-conformance"><a id="Conformance" href="#Conformance">6 Conformance</a></h1>
</summary>
-<p>The conformance requirements for OData clients and services are described in <a href="#ODataProtocol">OData-Protocol</a>.</p>
+<p>The conformance requirements for OData clients and services are described in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Conformance">OData-Protocol, section 12</a>.</p>
</details>
<hr />
<details open><summary>
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
## <a id="AddressingtheModelforaService" href="#AddressingtheModelforaService">4.1 Addressing the Model for a Service</a>
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)
### <a id="CanonicalURLforContainedEntities" href="#CanonicalURLforContainedEntities">4.3.2 Canonical URL for Contained Entities</a>
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).
### <a id="AlternateKeys" href="#AlternateKeys">4.3.5 Alternate Keys</a>
@@ -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
## <a id="AddressingOperations" href="#AddressingOperations">4.5 Addressing Operations</a>
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).
### <a id="AddressingActions" href="#AddressingActions">4.5.1 Addressing Actions</a>
@@ -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).
### <a id="SystemQueryOptionsearch" href="#SystemQueryOptionsearch">5.1.8 System Query Option `$search`</a>
@@ -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)
# <a id="Conformance" href="#Conformance">6 Conformance</a>
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
- `$<content-id>/$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 <ralf.handl@sap.com>
Date: Wed, 6 Nov 2024 19:01:24 +0100
Subject: [PATCH 11/19] 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 @@ <h2 id="116-asynchronous-requests"><a id="AsynchronousRequests" href="#Asynchron
<p>If the client has specified<code> respond-async</code> in the request, the service MAY process the request asynchronously and return a <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> response. A service MUST NOT reply to a <a href="#DataServiceRequests">Data Service Request</a> with <code>202 Accepted</code> if the request has not included the <code>respond-async</code> preference.</p>
<p>Responses that return <code>202 Accepted</code> MUST include a <a href="#HeaderLocation"><code>Location</code></a> header pointing to a <em>status monitor resource</em> that represents the current state of the asynchronous processing in addition to an optional <a href="#HeaderRetryAfter"><code>Retry-After</code></a> 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.</p>
<p>A <code>GET</code> request to the status monitor resource again returns <code>202 Accepted</code> response if the asynchronous processing has not finished. This response MUST again include a <a href="#HeaderLocation"><code>Location</code></a> header and MAY include a <a href="#HeaderRetryAfter"><code>Retry-After</code></a> header to be used for a subsequent request. The <code>Location</code> header and optional <code>Retry-After</code> header may or may not contain the same values as returned by the previous request.</p>
-<p>A <code>GET</code> request to the status monitor resource returns <a href="#ResponseCode200OK"><code>200 OK</code></a> once the asynchronous processing has completed. For OData 4.01 or greater responses, or OData 4.0 requests that include an <code>Accept</code> header that does not specify <code>application/http</code>, the response MUST include the <a href="#HeaderAsyncResult"><code>AsyncResult</code></a> response header. Any other headers, along with the response body, represent the result of the completed asynchronous operation. If the <code>GET</code> request to the status monitor includes an <code>OData-MaxVersion</code> header with a value of <code>4.0</code> and no <code>Accept</code> header, or an <code>Accept</code> header that includes <code>application/http</code>, then the body of the final <code>200 OK</code> response MUST be represented as an HTTP message, as described in <a href="#rfc9110">RFC9110</a>, which is the full HTTP response to the completed asynchronous operation.</p>
-<p>A <code>DELETE</code> request sent to the status monitor resource requests that the asynchronous processing be canceled. A <code>200 OK</code> or a <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> response indicates that the asynchronous processing has been successfully canceled. A client can request that the <code>DELETE</code> should be executed asynchronously. A <code>202 Accepted</code> response indicates that the cancellation is being processed asynchronously; the client can use the returned <a href="#HeaderLocation"><code>Location</code></a> 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 <a href="#ResponseCode405MethodNotAllowed"><code>405 Method Not Allowed</code></a>.</p>
+<p>Once the asynchronous processing has completed, a <code>GET</code> request to the status monitor resource returns <a href="#ResponseCode200OK"><code>200 OK</code></a>, or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> if the request included a <code>Prefer</code> header with a value of <code>return=minimal</code> that was applied by the service. For OData 4.01 or greater responses, or OData 4.0 requests that include an <code>Accept</code> header that does not specify <code>application/http</code>, the response MUST include the <a href="#HeaderAsyncResult"><code>AsyncResult</code></a> response header. A <code>204 No Content</code> response MUST include a <code>Location</code> 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 <code>200 OK</code> response any other headers, along with the response body, represent the result of the completed asynchronous operation. If the <code>GET</code> request to the status monitor includes an <code>OData-MaxVersion</code> header with a value of <code>4.0</code> and no <code>Accept</code> header, or an <code>Accept</code> header that includes <code>application/http</code>, then the body of the final <code>200 OK</code> response MUST be represented as an HTTP message, as described in <a href="#rfc9110">RFC9110</a>, which is the full HTTP response to the completed asynchronous operation.</p>
+<p>A <code>DELETE</code> request sent to the status monitor resource requests that the asynchronous processing be canceled. A <code>200 OK</code> or a <code>204 No Content</code> response indicates that the asynchronous processing has been successfully canceled. A client can request that the <code>DELETE</code> should be executed asynchronously. A <code>202 Accepted</code> response indicates that the cancellation is being processed asynchronously; the client can use the returned <code>Location</code> 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 <a href="#ResponseCode405MethodNotAllowed"><code>405 Method Not Allowed</code></a>.</p>
<p>After a successful <code>DELETE</code> request against the status monitor resource, any subsequent <code>GET</code> requests for the same status monitor resource returns <a href="#ResponseCode404NotFound"><code>404 Not Found</code></a>.</p>
<p>If an asynchronous request is cancelled for reasons other than the consumers issuing a <code>DELETE</code> request against the status monitor resource, a <code>GET</code> request to the status monitor resource returns <code>200 OK</code> with a response body containing a single HTTP response with a status code in the <a href="#ServerErrorResponses"><code>5xx Server Error</code></a> range indicating that the operation was cancelled.</p>
<p>The service MUST ensure that no observable change has occurred as a result of a canceled request.</p>
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 <ralf.handl@sap.com>
Date: Wed, 13 Nov 2024 18:31:39 +0100
Subject: [PATCH 12/19] 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 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/326">326</a></td>
</tr>
<tr class="even">
+<td><a href="#SimpleIdentifier">Section 15.2</a></td>
+<td>Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/375">375</a></td>
+</tr>
+<tr class="odd">
<td><a href="#Conformance">Section 17</a></td>
<td>Additional conformance clauses for version 4.02</td>
<td></td>
@@ -3888,6 +3893,7 @@ <h2 id="152-simple-identifier"><a id="SimpleIdentifier" href="#SimpleIdentifier"
<li>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)”.</li>
</ul>
<p>Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits.</p>
+<p>For maximum interoperability services SHOULD use simple identifiers that additionally only consist of characters from the Basic Latin code block and match the pattern <code>^[_A-Za-z][_A-Za-z0-9]*$</code>.</p>
</details>
<details open><summary>
<h2 id="153-qualified-name"><a id="QualifiedName" href="#QualifiedName">15.3 Qualified Name</a></h2>
@@ -4225,9 +4231,10 @@ <h1 id="17-conformance"><a id="Conformance" href="#Conformance">17 Conformance</
<ol start="14" type="1">
<li>SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case</li>
</ol>
-<p>In addition, OData 4.01 services:</p>
+<p>In addition, OData 4.02 or greater services:</p>
<ol start="15" type="1">
<li>SHOULD NOT include constant <a href="#GeoValues">Geo</a> or <a href="#StreamValues">Stream values</a> in annotations</li>
+<li>SHOULD use <a href="#SimpleIdentifier">simple identifiers</a> matching the pattern <code>^[_A-Za-z][_A-Za-z0-9]*$</code></li>
</ol>
<p>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.</p>
</details>
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 |
## <a id="Glossary" href="#Glossary">1.2 Glossary</a>
@@ -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]*$`.
+
## <a id="QualifiedName" href="#QualifiedName">15.3 Qualified Name</a>
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 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/326">326</a></td>
</tr>
<tr class="odd">
+<td><a href="#SimpleIdentifier">Section 15.2</a></td>
+<td>Prefer identifiers consisting only of latin letters, the underscore, and decimal numbers</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/375">375</a></td>
+</tr>
+<tr class="even">
<td><a href="#Conformance">Section 17</a></td>
<td>Additional conformance clauses for version 4.02</td>
<td></td>
@@ -3642,6 +3647,7 @@ <h2 id="152-simple-identifier"><a id="SimpleIdentifier" href="#SimpleIdentifier"
<li>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)”.</li>
</ul>
<p>Non-normatively speaking it starts with a letter or underscore, followed by at most 127 letters, underscores or digits.</p>
+<p>For maximum interoperability services SHOULD use simple identifiers that additionally only consist of characters from the Basic Latin code block and match the pattern <code>^[_A-Za-z][_A-Za-z0-9]*$</code>.</p>
</details>
<details open><summary>
<h2 id="153-qualified-name"><a id="QualifiedName" href="#QualifiedName">15.3 Qualified Name</a></h2>
@@ -3861,9 +3867,10 @@ <h1 id="17-conformance"><a id="Conformance" href="#Conformance">17 Conformance</
<ol start="14" type="1">
<li>SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case</li>
</ol>
-<p>In addition, OData 4.01 services:</p>
+<p>In addition, OData 4.02 or greater services:</p>
<ol start="15" type="1">
<li>SHOULD NOT include constant <a href="#GeoValues">Geo</a> or <a href="#StreamValues">Stream values</a> in annotations</li>
+<li>SHOULD use <a href="#SimpleIdentifier">simple identifiers</a> matching the pattern <code>^[_A-Za-z][_A-Za-z0-9]*$</code></li>
</ol>
<p>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.</p>
</details>
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 |
## <a id="Glossary" href="#Glossary">1.2 Glossary</a>
@@ -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]*$`.
+
## <a id="QualifiedName" href="#QualifiedName">15.3 Qualified Name</a>
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?= <heiko.theissen@sap.com>
Date: Wed, 20 Nov 2024 17:18:27 +0100
Subject: [PATCH 13/19] 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 @@ <h2 id="72-standard-aggregation-methods"><a id="StandardAggregationMethods" href
<span id="cb144-6"><a href="#cb144-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"ID"</span><span class="fu">:</span> <span class="st">"P3"</span><span class="fu">,</span> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Paper"</span><span class="fu">,</span> <span class="dt">"Color"</span><span class="fu">:</span> <span class="st">"White"</span><span class="fu">,</span> <span class="dt">"TaxRate"</span><span class="fu">:</span> <span class="dv">0</span><span class="er">.</span><span class="dv">14</span><span class="fu">,</span></span>
<span id="cb144-7"><a href="#cb144-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Total@type"</span><span class="fu">:</span> <span class="st">"Decimal"</span><span class="fu">,</span> <span class="dt">"Total"</span><span class="fu">:</span> <span class="dv">8</span> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb144-8"><a href="#cb144-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"ID"</span><span class="fu">:</span> <span class="st">"P4"</span><span class="fu">,</span> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Pencil"</span><span class="fu">,</span> <span class="dt">"Color"</span><span class="fu">:</span> <span class="st">"Black"</span><span class="fu">,</span> <span class="dt">"TaxRate"</span><span class="fu">:</span> <span class="dv">0</span><span class="er">.</span><span class="dv">14</span><span class="fu">,</span></span>
-<span id="cb144-9"><a href="#cb144-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Total"</span><span class="fu">:</span> <span class="kw">null</span> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb144-9"><a href="#cb144-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Total"</span><span class="fu">:</span> <span class="kw">null</span> <span class="fu">}</span><span class="ot">,</span></span>
<span id="cb144-10"><a href="#cb144-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"ID"</span><span class="fu">:</span> <span class="st">"P1"</span><span class="fu">,</span> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Sugar"</span><span class="fu">,</span> <span class="dt">"Color"</span><span class="fu">:</span> <span class="st">"White"</span><span class="fu">,</span> <span class="dt">"TaxRate"</span><span class="fu">:</span> <span class="dv">0</span><span class="er">.06</span><span class="fu">,</span></span>
<span id="cb144-11"><a href="#cb144-11" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Total@type"</span><span class="fu">:</span> <span class="st">"Decimal"</span><span class="fu">,</span> <span class="dt">"Total"</span><span class="fu">:</span> <span class="dv">4</span> <span class="fu">}</span></span>
<span id="cb144-12"><a href="#cb144-12" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
<span id="cb144-13"><a href="#cb144-13" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
-<p>The expression <code>$it/Sales</code> refers to the sales of the current product. Without <code>$it</code>, all sales of all products would be aggregated, because the input collection for the <code>aggregate</code> function consists of all products.</p>
</div>
<div class="example">
<p>Example 79: Alternatively, <code>join</code> could be applied to yield a flat structure:</p>
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?= <heiko.theissen@sap.com>
Date: Wed, 20 Nov 2024 17:43:07 +0100
Subject: [PATCH 14/19] 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 @@ <h1 id="10-context-url"><a id="ContextURL" href="#ContextURL">10 Context URL</a>
<p>For details on how the context URL is used to describe a payload, see the relevant sections in the particular format.</p>
<p>The following subsections describe how the context URL is constructed for each category of payload by providing a <em>context URL template</em>. The context URL template uses the following terms:</p>
<ul>
-<li><code>{context-url}</code> is the canonical resource path to the <code>$metadata</code> document,</li>
-<li><code>{entity-set}</code> is the name of an entity set or path to a containment navigation property,</li>
-<li><code>{entity}</code> is the canonical URL for an entity,</li>
-<li><code>{singleton}</code> is the canonical URL for a singleton entity,</li>
-<li><code>{select-list}</code> is an optional parenthesized comma-separated list of selected properties, instance annotations, functions, and actions,</li>
-<li><code>{property-path}</code> is the path to a structural property of the entity,</li>
-<li><code>{type-name}</code> is a qualified type name,</li>
+<li><code>{context-url}</code> is the canonical resource path to the <code>$metadata</code> document.</li>
+<li>A <em>canonical collection</em> is an entity set <a href="https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#EntitySet">OData-CSDL, section 13.2</a> or a collection addressed by a containment navigation property <a href="https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#ContainmentNavigationProperty">OData-CSDL, section 8.4</a>. We denote by <code>{canonical-collection}</code> the canonical URL <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL">OData-URL, section 4.3.1</a> that addresses a canonical collection relative to the service root.</li>
+<li>A <em>canonical singleton</em> is a singleton <a href="https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html#Singleton">OData-CSDL, section 13.3</a> or an entity addressed by a single-valued containment navigation property. We denote by <code>{canonical-singleton}</code> the canonical URL that addresses a canonical singleton relative to the service root.</li>
+<li>A <em>canonical member</em> is an entity within a canonical collection. We denote by <code>{canonical-member}</code> the canonical URL that addresses a canonical member relative to the service root.</li>
+<li><code>{select-list}</code> is an optional parenthesized comma-separated list of selected properties, instance annotations, functions, and actions.</li>
+<li><code>{property-path}</code> is the path to a structural property of the entity.</li>
+<li><code>{type-name}</code> is a qualified type name.</li>
<li><code>{/type-name}</code> is an optional type-cast segment containing the qualified name of a derived or implemented type prefixed with a forward slash.</li>
</ul>
+<p>Key values in <code>{canonical-collection}</code>, <code>{canonical-singleton}</code>, and <code>{canonical-member}</code> are represented in canonical form (parentheses-style) without percent-encoding.</p>
<p>The full grammar for the context URL is defined in <a href="#ODataABNF">OData-ABNF</a>. Note that the syntax of the context URL is independent of whatever URL conventions the service uses for addressing individual entities.</p>
<details open><summary>
<h2 id="101-service-document"><a id="ServiceDocument" href="#ServiceDocument">10.1 Service Document</a></h2>
@@ -1327,62 +1328,65 @@ <h2 id="101-service-document"><a id="ServiceDocument" href="#ServiceDocument">10
<h2 id="102-collection-of-entities"><a id="CollectionofEntities" href="#CollectionofEntities">10.2 Collection of Entities</a></h2>
</summary>
<p>Context URL template:</p>
-<pre><code>{context-url}#{entity-set}
+<pre><code>{context-url}#{canonical-collection}
{context-url}#Collection({type-name})</code></pre>
-<p>If all entities in the collection are members of one entity set, its name is the context URL fragment.</p>
+<p>If all entities in the response or a response part are members of a single canonical collection, the context URL fragment is the <code>{canonical-collection}</code>.</p>
<div class="example">
<p>Example 11: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Customers
http://host/service/$metadata#Customers</code></pre>
</div>
-<p>If the entities are contained, then <code>entity-set</code> 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.</p>
<div class="example">
<p>Example 12: resource URL and corresponding context URL for contained entities</p>
<pre><code>http://host/service/Orders(4711)/Items
http://host/service/$metadata#Orders(4711)/Items</code></pre>
</div>
-<p>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.</p>
+<p>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.</p>
</details>
<details open><summary>
<h2 id="103-entity"><a id="Entity" href="#Entity">10.3 Entity</a></h2>
</summary>
<p>Context URL template:</p>
-<pre><code>{context-url}#{entity-set}/$entity
+<pre><code>{context-url}#{canonical-collection}/$entity
{context-url}#{type-name}</code></pre>
-<p>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 <code>/$entity</code> appended.</p>
+<p>If a response or response part is an entity within in a canonical collection, the context URL fragment is the <code>{canonical-collection}</code> with <code>/$entity</code> appended.</p>
<div class="example">
-<p>Example 13: resource URL and corresponding context URL</p>
+<p>Example 13: resource URL and corresponding context URL for named entity set. Note the absence of the key predicate <code>(1)</code> in the context URL.</p>
<pre><code>http://host/service/Customers(1)
http://host/service/$metadata#Customers/$entity</code></pre>
</div>
-<p>If the entity is contained, then <code>entity-set</code> is the top-level entity set or singleton followed by the path to the containment navigation property of the containing entity.</p>
<div class="example">
<p>Example 14: resource URL and corresponding context URL for contained entity</p>
<pre><code>http://host/service/Orders(4711)/Items(1)
http://host/service/$metadata#Orders(4711)/Items/$entity</code></pre>
</div>
-<p>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.</p>
+<p>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 <code>{type-name}</code> of the returned entity.</p>
</details>
<details open><summary>
<h2 id="104-singleton"><a id="Singleton" href="#Singleton">10.4 Singleton</a></h2>
</summary>
<p>Context URL template:</p>
-<pre><code>{context-url}#{singleton}</code></pre>
-<p>If a response or response part is a singleton, its name is the context URL fragment.</p>
+<pre><code>{context-url}#{canonical-singleton}</code></pre>
+<p>If a response or response part is a canonical singleton, the context URL fragment is the <code>{canonical-singleton}</code> without <code>/$entity</code> appended.</p>
<div class="example">
<p>Example 15: resource URL and corresponding context URL</p>
<pre><code>http://host/service/MainSupplier
http://host/service/$metadata#MainSupplier</code></pre>
</div>
+<div class="example">
+<p>Example 16: resource URL and corresponding context URL for entity targeted by a single-valued containment navigation property</p>
+<pre><code>http://host/service/Orders(4711)/DeliveryAddress
+http://host/service/$metadata#Orders(4711)/DeliveryAddress</code></pre>
+</div>
</details>
<details open><summary>
<h2 id="105-collection-of-derived-entities"><a id="CollectionofDerivedEntities" href="#CollectionofDerivedEntities">10.5 Collection of Derived Entities</a></h2>
</summary>
<p>Context URL template:</p>
-<pre><code>{context-url}#{entity-set}{/type-name}</code></pre>
-<p>If an entity set consists exclusively of derived entities, a type-cast segment is added to the context URL.</p>
+<pre><code>{context-url}#{canonical-collection}{/type-name}</code></pre>
+<p>If a response or response part is a collection filtered by a type cast segment in the resource URL <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes">OData-URL, section 4.11</a>, the type-cast segment is added to the context URL.</p>
<div class="example">
-<p>Example 16: resource URL and corresponding context URL</p>
+<p>Example 17: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Customers/Model.VipCustomer
http://host/service/$metadata#Customers/Model.VipCustomer</code></pre>
</div>
@@ -1391,28 +1395,34 @@ <h2 id="105-collection-of-derived-entities"><a id="CollectionofDerivedEntities"
<h2 id="106-derived-entity"><a id="DerivedEntity" href="#DerivedEntity">10.6 Derived Entity</a></h2>
</summary>
<p>Context URL template:</p>
-<pre><code>{context-url}#{entity-set}{/type-name}/$entity</code></pre>
-<p>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.</p>
+<pre><code>{context-url}#{canonical-collection}{/type-name}/$entity
+{context-url}#{canonical-singleton}{/type-name}</code></pre>
+<p>If a response or response part is an entity filtered by a type cast segment in the resource URL <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingDerivedTypes">OData-URL, section 4.11</a>, the type-cast segment is appended to the <code>{canonical-collection}</code> or <code>{canonical-singleton}</code> and prior to appending <code>/$entity</code>, if any.</p>
<div class="example">
-<p>Example 17: resource URL and corresponding context URL</p>
+<p>Example 18: resource URL with key predicate and corresponding context URL</p>
<pre><code>http://host/service/Customers(2)/Model.VipCustomer
http://host/service/$metadata#Customers/Model.VipCustomer/$entity</code></pre>
</div>
+<div class="example">
+<p>Example 19: resource URL for singleton and corresponding context URL</p>
+<pre><code>http://host/service/MainSupplier/Model.PreferredVendor
+http://host/service/$metadata#MainSupplier/Model.PreferredVendor</code></pre>
+</div>
</details>
<details open><summary>
<h2 id="107-collection-of-projected-entities"><a id="CollectionofProjectedEntities" href="#CollectionofProjectedEntities">10.7 Collection of Projected Entities</a></h2>
</summary>
<p>Context URL templates:</p>
-<pre><code>{context-url}#{entity-set}{/type-name}{select-list}
+<pre><code>{context-url}#{canonical-collection}{/type-name}{select-list}
{context-url}#Collection({type-name}){select-list}</code></pre>
-<p>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 <a href="#CollectionofEntities">collection of entities</a>.</p>
+<p>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 <a href="#CollectionofEntities">collection of entities</a>.</p>
<p>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.</p>
<p>The shortcut <code>*</code> 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 <a href="#ODataABNF">OData-ABNF</a>.</p>
<p>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 <a href="#Preferenceincludeannotationsodataincludeannotations"><code>include-annotations</code></a> preference do not appear in the context URL and do not affect the selected/expanded properties.</p>
<p>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.</p>
<p>OData 4.01 responses MAY use the shortcut pattern <code>{namespace}.*</code> to represent the list of all bound actions or functions available for entities in the collection, see system query option <a href="#SystemQueryOptionselect"><code>$select</code></a>.</p>
<div class="example">
-<p>Example 18: resource URL and corresponding context URL</p>
+<p>Example 20: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Customers?$select=Address,Orders,Model.VipCustomer/PreferredContact
http://host/service/$metadata#Customers(Address,Orders,Model.VipCustomer/PreferredContact)</code></pre>
</div>
@@ -1421,17 +1431,17 @@ <h2 id="107-collection-of-projected-entities"><a id="CollectionofProjectedEntiti
<h2 id="108-projected-entity"><a id="ProjectedEntity" href="#ProjectedEntity">10.8 Projected Entity</a></h2>
</summary>
<p>Context URL templates:</p>
-<pre><code>{context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{singleton}{select-list}
+<pre><code>{context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+{context-url}#{canonical-singleton}{/type-name}{select-list}
{context-url}#{type-name}{select-list}</code></pre>
-<p>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 <code>{entity-set}</code> after an optional type-cast segment and prior to appending <code>/$entity</code>. If the response is not a subset of a single entity set, the <code>{select-list}</code> is instead appended to the <code>{type-name}</code> of the returned entity.</p>
+<p>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 <code>{canonical-collection}</code> or <code>{canonical-singleton}</code> after an optional type-cast segment and prior to appending <code>/$entity</code>, if any.</p>
<p>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.</p>
<p>The shortcut <code>*</code> 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 <a href="#ODataABNF">OData-ABNF</a>. Note that expanded properties are automatically included in the response.</p>
<p>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 <a href="#Preferenceincludeannotationsodataincludeannotations"><code>include-annotations</code></a> preference do not appear in the context URL and do not affect the selected/expanded properties.</p>
<p>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.</p>
<p>OData 4.01 responses MAY use the shortcut pattern <code>{namespace}.*</code> to represent the list of all bound actions or functions available for the returned entity, see system query option <a href="#SystemQueryOptionselect"><code>$select</code></a>.</p>
<div class="example">
-<p>Example 19: resource URL and corresponding context URL</p>
+<p>Example 21: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Customers(1)?$select=Name,Rating
http://host/service/$metadata#Customers(Name,Rating)/$entity</code></pre>
</div>
@@ -1440,7 +1450,7 @@ <h2 id="108-projected-entity"><a id="ProjectedEntity" href="#ProjectedEntity">10
<h2 id="109-collection-of-expanded-entities"><a id="CollectionofExpandedEntities" href="#CollectionofExpandedEntities">10.9 Collection of Expanded Entities</a></h2>
</summary>
<p>Context URL template:</p>
-<pre><code>{context-url}#{entity-set}{/type-name}{select-list}
+<pre><code>{context-url}#{canonical-collection}{/type-name}{select-list}
{context-url}#Collection({type-name}){select-list}</code></pre>
<p>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 <code>$select</code> or <code>$expand</code>, then the expanded property is suffixed with empty parentheses. If the expansion is recursive for nested children, a plus sign (<code>+</code>) is infixed between the navigation property name and the opening parenthesis.</p>
<p>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 <code>$select</code> or <code>$expand</code>, but MUST still be present, without a suffix, if it is explicitly selected.</p>
@@ -1448,17 +1458,17 @@ <h2 id="109-collection-of-expanded-entities"><a id="CollectionofExpandedEntities
<p>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).</p>
<p>Navigation properties with expanded references are not represented in the context URL.</p>
<div class="example">
-<p>Example 20: resource URL and corresponding context URL — select and expand</p>
+<p>Example 22: resource URL and corresponding context URL — select and expand</p>
<pre><code>http://host/service/Customers?$select=Name&$expand=Address/Country
http://host/service/$metadata#Customers(Name,Address/Country())</code></pre>
</div>
<div class="example">
-<p>Example 21: resource URL and corresponding context URL — expand <code>$ref</code></p>
+<p>Example 23: resource URL and corresponding context URL — expand <code>$ref</code></p>
<pre><code>http://host/service/Customers?$expand=Orders/$ref
http://host/service/$metadata#Customers</code></pre>
</div>
<div class="example">
-<p>Example 22: resource URL and corresponding context URL — expand with <code>$levels</code></p>
+<p>Example 24: resource URL and corresponding context URL — expand with <code>$levels</code></p>
<pre><code>http://host/service/Employees/Sales.Manager?$select=DirectReports
&$expand=DirectReports($select=FirstName,LastName;$levels=4)
http://host/service/$metadata
@@ -1469,15 +1479,15 @@ <h2 id="109-collection-of-expanded-entities"><a id="CollectionofExpandedEntities
<h2 id="1010-expanded-entity"><a id="ExpandedEntity" href="#ExpandedEntity">10.10 Expanded Entity</a></h2>
</summary>
<p>Context URL template:</p>
-<pre><code>{context-url}#{entity-set}{/type-name}{select-list}/$entity
-{context-url}#{singleton}{select-list}
+<pre><code>{context-url}#{canonical-collection}{/type-name}{select-list}/$entity
+{context-url}#{canonical-singleton}{/type-name}{select-list}
{context-url}#{type-name}{select-list}</code></pre>
<p>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 <code>$select</code> or <code>$expand</code>, then the expanded property is suffixed with empty parentheses. If the expansion is recursive for nested children, a plus sign (<code>+</code>) is infixed between the navigation property name and the opening parenthesis.</p>
<p>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 <code>$select</code> or <code>$expand</code>, but MUST still be present, without a suffix, if it is explicitly selected.</p>
<p>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).</p>
<p>Navigation properties with expanded references are not represented in the context URL.</p>
<div class="example">
-<p>Example 23: resource URL and corresponding context URL</p>
+<p>Example 25: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Employees(1)/Sales.Manager?
$expand=DirectReports($select=FirstName,LastName;$levels=4)
http://host/service/$metadata
@@ -1491,7 +1501,7 @@ <h2 id="1011-collection-of-entity-references"><a id="CollectionofEntityReference
<pre><code>{context-url}#Collection($ref)</code></pre>
<p>If a response is a collection of entity references, the context URL does not contain the type of the referenced entities.</p>
<div class="example">
-<p>Example 24: resource URL and corresponding context URL for a collection of entity references</p>
+<p>Example 26: resource URL and corresponding context URL for a collection of entity references</p>
<pre><code>http://host/service/Customers('ALFKI')/Orders/$ref
http://host/service/$metadata#Collection($ref)</code></pre>
</div>
@@ -1503,7 +1513,7 @@ <h2 id="1012-entity-reference"><a id="EntityReference" href="#EntityReference">1
<pre><code>{context-url}#$ref</code></pre>
<p>If a response is a single entity reference, <code>$ref</code> is the context URL fragment.</p>
<div class="example">
-<p>Example 25: resource URL and corresponding context URL for a single entity reference</p>
+<p>Example 27: resource URL and corresponding context URL for a single entity reference</p>
<pre><code>http://host/service/Orders(10643)/Customer/$ref
http://host/service/$metadata#$ref</code></pre>
</div>
@@ -1512,12 +1522,12 @@ <h2 id="1012-entity-reference"><a id="EntityReference" href="#EntityReference">1
<h2 id="1013-property-value"><a id="PropertyValue" href="#PropertyValue">10.13 Property Value</a></h2>
</summary>
<p>Context URL templates:</p>
-<pre><code>{context-url}#{entity}/{property-path}{select-list}
+<pre><code>{context-url}#{canonical-member}/{property-path}{select-list}
{context-url}#{type-name}{select-list}</code></pre>
-<p>If a response represents an <a href="#RequestingIndividualProperties">individual property</a> 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.</p>
+<p>If a response represents an <a href="#RequestingIndividualProperties">individual property</a> of a canonical member, the context URL specifies the <code>{canonical-member}</code> 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.</p>
<p>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.</p>
<div class="example">
-<p>Example 26: resource URL and corresponding context URL</p>
+<p>Example 28: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Customers(1)/Addresses
http://host/service/$metadata#Customers(1)/Addresses</code></pre>
</div>
@@ -1527,9 +1537,9 @@ <h2 id="1014-collection-of-complex-or-primitive-types"><a id="CollectionofComple
</summary>
<p>Context URL template:</p>
<pre><code>{context-url}#Collection({type-name}){select-list}</code></pre>
-<p>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 collection.</p>
+<p>If a response is a collection of complex types or primitive types that do not represent an individual property of a canonical member, the context URL specifies the fully qualified type of the collection.</p>
<div class="example">
-<p>Example 27: resource URL and corresponding context URL</p>
+<p>Example 29: resource URL and corresponding context URL</p>
<pre><code>http://host/service/TopFiveHobbies()
http://host/service/$metadata#Collection(Edm.String)</code></pre>
</div>
@@ -1539,9 +1549,9 @@ <h2 id="1015-complex-or-primitive-type"><a id="ComplexorPrimitiveType" href="#Co
</summary>
<p>Context URL template:</p>
<pre><code>{context-url}#{type-name}{select-list}</code></pre>
-<p>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 context URL specifies the fully qualified type of the result.</p>
+<p>If a response is a complex type or primitive type that does not represent an individual property of a canonical member, the context URL specifies the fully qualified type of the result.</p>
<div class="example">
-<p>Example 28: resource URL and corresponding context URL</p>
+<p>Example 30: resource URL and corresponding context URL</p>
<pre><code>http://host/service/MostPopularName()
http://host/service/$metadata#Edm.String</code></pre>
</div>
@@ -1549,15 +1559,9 @@ <h2 id="1015-complex-or-primitive-type"><a id="ComplexorPrimitiveType" href="#Co
<details open><summary>
<h2 id="1016-operation-result"><a id="OperationResult" href="#OperationResult">10.16 Operation Result</a></h2>
</summary>
-<p>Context URL templates:</p>
-<pre><code>{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}</code></pre>
-<p>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.</p>
+<p>The context URL in a response from an action or function has one of the formats described so far (except the <a href="#ServiceDocument">service document</a> format). It does not mention the name of the invoked action or function.</p>
<div class="example">
-<p>Example 29: resource URL and corresponding context URL</p>
+<p>Example 31: resource URL and corresponding context URL</p>
<pre><code>http://host/service/TopFiveCustomers()
http://host/service/$metadata#Customers</code></pre>
</div>
@@ -1566,14 +1570,14 @@ <h2 id="1016-operation-result"><a id="OperationResult" href="#OperationResult">1
<h2 id="1017-delta-payload"><a id="DeltaPayload" href="#DeltaPayload">10.17 Delta Payload</a></h2>
</summary>
<p>Context URL template:</p>
-<pre><code>{context-url}#{entity-set}{/type-name}{select-list}/$delta
-{context-url}#{entity}{select-list}/$delta
-{context-url}#{entity}/{property-path}{select-list}/$delta
+<pre><code>{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</code></pre>
<p>The context URL of a <a href="#RequestingChanges">delta response</a> is the context URL of the response to the defining query, followed by <code>/$delta</code>. This includes singletons, single-valued navigation properties, and collection-valued navigation properties.</p>
-<p>If the entities are contained, then <code>{entity-set}</code> is the top-level entity set followed by the path to the containment navigation property of the containing entity.</p>
+<p>If the entities are contained, then <code>{canonical-collection}</code> is the top-level entity set followed by the path to the containment navigation property of the containing entity.</p>
<div class="example">
-<p>Example 30: resource URL and corresponding context URL</p>
+<p>Example 32: resource URL and corresponding context URL</p>
<pre><code>http://host/service/Customers?$deltatoken=1234
http://host/service/$metadata#Customers/$delta</code></pre>
</div>
@@ -1583,10 +1587,10 @@ <h2 id="1017-delta-payload"><a id="DeltaPayload" href="#DeltaPayload">10.17 Delt
<h2 id="1018-item-in-a-delta-payload"><a id="IteminaDeltaPayload" href="#IteminaDeltaPayload">10.18 Item in a Delta Payload</a></h2>
</summary>
<p>Context URL templates:</p>
-<pre><code>{context-url}#{entity-set}/$deletedEntity
-{context-url}#{entity-set}/$link
-{context-url}#{entity-set}/$deletedLink</code></pre>
-<p>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. <code>{entity-set}</code> corresponds to the set of the deleted entity, or source entity for an added or deleted link.</p>
+<pre><code>{context-url}#{canonical-collection}/$deletedEntity
+{context-url}#{canonical-collection}/$link
+{context-url}#{canonical-collection}/$deletedLink</code></pre>
+<p>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. <code>{canonical-collection}</code> corresponds to the set of the deleted entity, or source entity for an added or deleted link.</p>
</details>
<details open><summary>
<h2 id="1019-all-response"><a id="allResponse" href="#allResponse">10.19 <code>$all</code> Response</a></h2>
@@ -1728,7 +1732,7 @@ <h3 id="1124-requesting-individual-properties"><a id="RequestingIndividualProper
<p>If the property is single-valued and has the <code>null</code> value, the service responds with <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>.</p>
<p>If the property is not available, for example due to permissions, the service responds with <a href="#ResponseCode404NotFound"><code>404 Not Found</code></a>.</p>
<div class="example">
-<p>Example 31:</p>
+<p>Example 33:</p>
<pre><code>GET http://host/service/Products(1)/Name</code></pre>
</div>
<details open><summary>
@@ -1749,7 +1753,7 @@ <h4 id="11242-requesting-a-raw-value-using-value"><a id="RequestingaRawValueusin
<p>A raw value request for a property or operation result that is <code>null</code> results in a <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> response.</p>
<p>If the property or operation result is not available, for example due to permissions, the service responds with <a href="#ResponseCode404NotFound"><code>404 Not Found</code></a>.</p>
<div class="example">
-<p>Example 32:</p>
+<p>Example 34:</p>
<pre><code>GET http://host/service/Products(1)/Name/$value</code></pre>
</div>
</details>
@@ -1764,27 +1768,27 @@ <h4 id="11251-system-query-option-select"><a id="SystemQueryOptionselect" href="
<p>The <code>$select</code> system query option requests that the service return only the properties, dynamic properties, <a href="#Actions">actions</a> and <a href="#Functions">functions</a> explicitly requested by the client. The service returns the specified content, if available, along with any available <a href="#SystemQueryOptionexpand">expanded</a> navigation or stream properties, and MAY return additional information.</p>
<p>The value of the <code>$select</code> 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 (<code>*</code>), 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.</p>
<div class="example">
-<p>Example 33: request only the <code>Rating</code> and <code>ReleaseDate</code> for the matching Products</p>
+<p>Example 35: request only the <code>Rating</code> and <code>ReleaseDate</code> for the matching Products</p>
<pre><code>GET http://host/service/Products?$select=Rating,ReleaseDate</code></pre>
</div>
<p>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.</p>
<div class="example">
-<p>Example 34:</p>
+<p>Example 36:</p>
<pre><code>GET http://host/service/Products?$select=*</code></pre>
</div>
<p>Properties of related entities can be specified by including the <code>$select</code> query option within the <code>$expand</code>.</p>
<div class="example">
-<p>Example 35:</p>
+<p>Example 37:</p>
<pre><code>GET http://host/service/Products?$expand=Category($select=Name)</code></pre>
</div>
<p>The properties specified in <code>$select</code> are represented in addition to any expanded navigation or stream properties. If a navigation property is specified in <code>$select</code>, then the corresponding navigation link is represented in the response. If the navigation property also appears in an <a href="#SystemQueryOptionexpand"><code>$expand</code></a> query option, then it is additionally represented as inline content.</p>
<div class="example">
-<p>Example 36: for each category, return the <code>CategoryName</code> and the <code>Products</code> navigation link</p>
+<p>Example 38: for each category, return the <code>CategoryName</code> and the <code>Products</code> navigation link</p>
<pre><code>GET http://host/service/Categories?$select=CategoryName,Products</code></pre>
</div>
<p>It is also possible to request all actions or functions available for each returned entity.</p>
<div class="example">
-<p>Example 37:</p>
+<p>Example 39:</p>
<pre><code>GET http://host/service/Products?$select=DemoService.*</code></pre>
</div>
<p>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 <a href="#SystemQueryOptionselect"><code>$select</code></a> and <a href="#SystemQueryOptioncompute"><code>$compute</code></a> for complex properties, plus <a href="#SystemQueryOptionfilter"><code>$filter</code></a>, <a href="#SystemQueryOptionsearch"><code>$search</code></a>, <a href="#SystemQueryOptioncount"><code>$count</code></a>, <a href="#SystemQueryOptionorderby"><code>$orderby</code></a>, <a href="#SystemQueryOptionskip"><code>$skip</code></a>, and <a href="#SystemQueryOptiontop"><code>$top</code></a> 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.</p>
@@ -1798,15 +1802,15 @@ <h4 id="11252-system-query-option-expand"><a id="SystemQueryOptionexpand" href="
<p>The value of <code>$expand</code> is a comma-separated list of expand items. Each expand item is evaluated relative to the retrieved resource being expanded.</p>
<p>For a full description of the syntax used when building requests, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionexpand">OData-URL, section 5.1.3</a>.</p>
<div class="example">
-<p>Example 38: for each customer entity within the Customers entity set the value of all related Orders will be represented inline</p>
+<p>Example 40: for each customer entity within the Customers entity set the value of all related Orders will be represented inline</p>
<pre><code>GET http://host/service.svc/Customers?$expand=Orders</code></pre>
</div>
<div class="example">
-<p>Example 39: for each customer entity within the Customers entity set the references to the related Orders will be represented inline</p>
+<p>Example 41: for each customer entity within the Customers entity set the references to the related Orders will be represented inline</p>
<pre><code>GET http://host/service.svc/Customers?$expand=Orders/$ref</code></pre>
</div>
<div class="example">
-<p>Example 40: for each customer entity within the Customers entity set the media stream representing the customer photo will be represented inline</p>
+<p>Example 42: for each customer entity within the Customers entity set the media stream representing the customer photo will be represented inline</p>
<pre><code>GET http://host/service.svc/Customers?$expand=Photo</code></pre>
</div>
<details open><summary>
@@ -1815,11 +1819,11 @@ <h5 id="112521-expand-options"><a id="ExpandOptions" href="#ExpandOptions">11.2.
<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#SystemQueryOptionexpand">OData-URL, section 5.1.3</a>.</p>
<p>Allowed system query options are <a href="#SystemQueryOptioncompute"><code>$compute</code></a>, <a href="#SystemQueryOptionselect"><code>$select</code></a>, <code>$expand</code>, and <a href="#ExpandOptionlevels"><code>$levels</code></a> for all navigation properties, plus <a href="#SystemQueryOptionfilter"><code>$filter</code></a>, <a href="#SystemQueryOptionorderby"><code>$orderby</code></a>, <a href="#SystemQueryOptionskip"><code>$skip</code></a>, <a href="#SystemQueryOptiontop"><code>$top</code></a>, <a href="#SystemQueryOptioncount"><code>$count</code></a>, and <a href="#SystemQueryOptionsearch"><code>$search</code></a> for collection-valued navigation properties.</p>
<div class="example">
-<p>Example 41: for each customer entity within the <code>Customers</code> entity set, the value of those related <code>Orders</code> whose <code>Amount</code> is greater than 100 will be represented inline</p>
+<p>Example 43: for each customer entity within the <code>Customers</code> entity set, the value of those related <code>Orders</code> whose <code>Amount</code> is greater than 100 will be represented inline</p>
<pre><code>GET http://host/service.svc/Customers?$expand=Orders($filter=Amount gt 100)</code></pre>
</div>
<div class="example">
-<p>Example 42: for each order within the <code>Orders</code> entity set, the following will be represented inline:</p>
+<p>Example 44: for each order within the <code>Orders</code> entity set, the following will be represented inline:</p>
<ul>
<li>The <code>Items</code> related to the <code>Orders</code> identified by the resource path section of the URL and the products related to each order item.</li>
<li>The <code>Customer</code> related to each order returned.</li>
@@ -1827,7 +1831,7 @@ <h5 id="112521-expand-options"><a id="ExpandOptions" href="#ExpandOptions">11.2.
<pre><code>GET http://host/service.svc/Orders?$expand=Items($expand=Product),Customer</code></pre>
</div>
<div class="example">
-<p>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 <code>VipCustomer</code>, or any of its subtypes, that entity may be returned with no inline representation for the expanded navigation property <code>InHouseStaff</code> (the service can always send more than requested)</p>
+<p>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 <code>VipCustomer</code>, or any of its subtypes, that entity may be returned with no inline representation for the expanded navigation property <code>InHouseStaff</code> (the service can always send more than requested)</p>
<pre><code>GET http://host/service.svc/Customers?$expand=SampleModel.VipCustomer/InHouseStaff</code></pre>
</div>
<details open><summary>
@@ -1838,7 +1842,7 @@ <h6 id="1125211-expand-option-levels"><a id="ExpandOptionlevels" href="#ExpandOp
<p>Clients using <code>$levels=max</code> MUST be prepared to handle entity references in cases were a circular reference would occur otherwise.</p>
<p>4.01 services that support <code>max</code> SHOULD do so in a case-insensitive manner. Clients that want to work with 4.0 services MUST use lower case.</p>
<div class="example">
-<p>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</p>
+<p>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</p>
<pre><code>GET http://host/service/Employees?$expand=Model.Manager/DirectReports($levels=4)</code></pre>
</div>
</details>
@@ -1850,7 +1854,7 @@ <h4 id="11253-system-query-option-compute"><a id="SystemQueryOptioncompute" href
<p>The <code>$compute</code> system query option allows clients to define computed properties that can be used in a <a href="#SystemQueryOptionselect"><code>$select</code></a> or within a <a href="#SystemQueryOptionfilter"><code>$filter</code></a> or <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> expression.</p>
<p>Computed properties SHOULD be included as dynamic properties in the result and MUST be included if <code>$select</code> is specified with the computed property name, or star (<code>*</code>).</p>
<div class="example">
-<p>Example 45: compute total price for order items (line breaks only for readability)</p>
+<p>Example 47: compute total price for order items (line breaks only for readability)</p>
<pre><code>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 @@ <h4 id="11261-system-query-option-filter"><a id="SystemQueryOptionfilter" href="
</summary>
<p>The <code>$filter</code> system query option restricts the set of items returned.</p>
<div class="example">
-<p>Example 46: return all Products whose <code>Price</code> is less than $10.00</p>
+<p>Example 48: return all Products whose <code>Price</code> is less than $10.00</p>
<pre><code>GET http://host/service/Products?$filter=Price lt 10.00</code></pre>
</div>
<p>The <a href="#SystemQueryOptioncount"><code>$count</code></a> segment may be used within a <code>$filter</code> expression to limit the items returned based on the exact count of related entities or items within a collection-valued property.</p>
<div class="example">
-<p>Example 47: return all Categories with less than 10 products</p>
+<p>Example 49: return all Categories with less than 10 products</p>
<pre><code>GET http://host/service/Categories?$filter=Products/$count lt 10</code></pre>
</div>
<p>The value of the <code>$filter</code> option is a Boolean expression as defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
@@ -1975,7 +1979,7 @@ <h5 id="112613-parameter-aliases"><a id="ParameterAliases" href="#ParameterAlias
<p>Parameter aliases can be used in place of literal values in entity keys, <a href="#InvokingaFunction">function parameters</a>, or within a <a href="#SystemQueryOptioncompute"><code>$compute</code></a>, <a href="#SystemQueryOptionfilter"><code>$filter</code></a> or <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> expression. Parameters aliases are names beginning with an at sign (<code>@</code>).</p>
<p>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.</p>
<div class="example">
-<p>Example 48: returns all employees whose Region property matches the string parameter value <code>WA</code></p>
+<p>Example 50: returns all employees whose Region property matches the string parameter value <code>WA</code></p>
<pre><code>GET http://host/service.svc/Employees?$filter=Region eq @p1&@p1='WA'</code></pre>
</div>
<p>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.</p>
@@ -1983,7 +1987,7 @@ <h5 id="112613-parameter-aliases"><a id="ParameterAliases" href="#ParameterAlias
<p>Parameter alias values used in <code>/$filter</code> path segments are always passed as expressions (because that is the expected type of the parameter).</p>
<p>All other parameter alias values are evaluated in the context of the resource identified by the path segment in which they are assigned and passed as values into the expression. Parameter alias value assignments MAY be nested within <code>$expand</code> and <code>$select</code>, in which case they are evaluated relative to the resource context of the <code>$expand</code> or <code>$select</code>.</p>
<div class="example">
-<p>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 <code>$this</code> to pass the manager into the filter on the expanded direct reports</p>
+<p>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 <code>$this</code> to pass the manager into the filter on the expanded direct reports</p>
<pre><code>GET http://host/service.svc/Employees?$expand=Manager(@m=$this;$expand=DirectReports($filter=@m/FirstName eq FirstName))</code></pre>
</div>
</details>
@@ -2000,17 +2004,17 @@ <h4 id="11262-system-query-option-orderby"><a id="SystemQueryOptionorderby" href
<p>Services SHOULD order language-dependent strings according to the <a href="#HeaderContentLanguage"><code>Content-Language</code></a> of the response, and SHOULD annotate string properties with language-dependent order with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#IsLanguageDependent"><code>Core.IsLanguageDependent</code></a>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
<p>Values of type <code>Edm.Stream</code> or any of the <code>Geo</code> types cannot be sorted.</p>
<div class="example">
-<p>Example 50: return all Products ordered by release date in ascending order, then by rating in descending order</p>
+<p>Example 52: return all Products ordered by release date in ascending order, then by rating in descending order</p>
<pre><code>GET http://host/service/Products?$orderby=ReleaseDate asc, Rating desc</code></pre>
</div>
<p>Related entities may be ordered by specifying <code>$orderby</code> within the <code>$expand</code> clause.</p>
<div class="example">
-<p>Example 51: return all Categories, and their Products ordered according to release date and in descending order of rating</p>
+<p>Example 53: return all Categories, and their Products ordered according to release date and in descending order of rating</p>
<pre><code>GET http://host/service/Categories?$expand=Products($orderby=ReleaseDate asc, Rating desc)</code></pre>
</div>
<p><code>$count</code> may be used within a <code>$orderby</code> expression to order the returned items according to the exact count of related entities or items within a collection-valued property.</p>
<div class="example">
-<p>Example 52: return all Categories ordered by the number of Products within each category</p>
+<p>Example 54: return all Categories ordered by the number of Products within each category</p>
<pre><code>GET http://host/service/Categories?$orderby=Products/$count</code></pre>
</div>
</details>
@@ -2021,7 +2025,7 @@ <h4 id="11263-system-query-option-top"><a id="SystemQueryOptiontop" href="#Syste
<p>Let <span class="math inline">\(A\)</span> 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 <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> query option, the service MUST choose a stable ordering across requests that include <code>$top</code> or <a href="#SystemQueryOptionskip"><code>$skip</code></a>.</p>
<p>If <span class="math inline">\(A\)</span> contains more than <span class="math inline">\(n\)</span> instances, the result of <span class="math inline">\({\tt \$top}=n\)</span> consists of the first <span class="math inline">\(n\)</span> instances in <span class="math inline">\(A\)</span>. Otherwise, the result equals <span class="math inline">\(A\)</span>. The instances in the result are in the same order as they occur in <span class="math inline">\(A\)</span>.</p>
<div class="example">
-<p>Example 53: return only the first five products of the Products entity set</p>
+<p>Example 55: return only the first five products of the Products entity set</p>
<pre><code>GET http://host/service/Products?$top=5</code></pre>
</div>
</details>
@@ -2032,12 +2036,12 @@ <h4 id="11264-system-query-option-skip"><a id="SystemQueryOptionskip" href="#Sys
<p>Let <span class="math inline">\(A\)</span> 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 <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> query option, the service MUST choose a stable ordering across requests that include <a href="#SystemQueryOptiontop"><code>$top</code></a> or <code>$skip</code>.</p>
<p>If <span class="math inline">\(A\)</span> contains <span class="math inline">\(n\)</span> or fewer instances, the result of <span class="math inline">\({\tt \$skip}=n\)</span> is empty. Otherwise, the first <span class="math inline">\(n\)</span> instances in <span class="math inline">\(A\)</span> are omitted from the result and all remaining instances are kept in the same order as they occur in <span class="math inline">\(A\)</span>.</p>
<div class="example">
-<p>Example 54: return products starting with the 6th product of the <code>Products</code> entity set</p>
+<p>Example 56: return products starting with the 6th product of the <code>Products</code> entity set</p>
<pre><code>GET http://host/service/Products?$skip=5</code></pre>
</div>
<p>Where <a href="#SystemQueryOptiontop"><code>$top</code></a> and <code>$skip</code> are used together, <code>$skip</code> MUST be applied before <code>$top</code>, regardless of the order in which they appear in the request.</p>
<div class="example">
-<p>Example 55: return the third through seventh products of the <code>Products</code> entity set</p>
+<p>Example 57: return the third through seventh products of the <code>Products</code> entity set</p>
<pre><code>GET http://host/service/Products?$top=5&$skip=2</code></pre>
</div>
<p>If no unique ordering is imposed through an <a href="#SystemQueryOptionorderby"><code>$orderby</code></a> query option, the service MUST impose a stable ordering across requests that include <code>$skip</code>.</p>
@@ -2047,12 +2051,12 @@ <h4 id="11265-system-query-option-count"><a id="SystemQueryOptioncount" href="#S
</summary>
<p>The <code>$count</code> system query option with a value of <code>true</code> specifies that the total count of items within a collection matching the request be returned along with the result.</p>
<div class="example">
-<p>Example 56: return, along with the results, the total number of products in the collection</p>
+<p>Example 58: return, along with the results, the total number of products in the collection</p>
<pre><code>GET http://host/service/Products?$count=true</code></pre>
</div>
<p>The count of related entities can be requested by specifying the <code>$count</code> query option within the <code>$expand</code> clause.</p>
<div class="example">
-<p>Example 57:</p>
+<p>Example 59:</p>
<pre><code>GET http://host/service/Categories?$expand=Products($count=true)</code></pre>
</div>
<p>A <code>$count</code> query option with a value of <code>false</code> (or not specified) hints that the service SHOULD NOT return a count.</p>
@@ -2065,32 +2069,32 @@ <h4 id="11266-system-query-option-search"><a id="SystemQueryOptionsearch" href="
</summary>
<p>The <code>$search</code> system query option restricts the result to include only those items <em>matching</em> the specified search expression. The definition of what it means to match is dependent upon the implementation.</p>
<div class="example">
-<p>Example 58: return all Products that match the search term <code>bike</code></p>
+<p>Example 60: return all Products that match the search term <code>bike</code></p>
<pre><code>GET http://host/service/Products?$search=bike</code></pre>
</div>
<p>The search expression can contain phrases, enclosed in double-quotes.</p>
<div class="example">
-<p>Example 59: return all Products that match the phrase <code>mountain bike</code></p>
+<p>Example 61: return all Products that match the phrase <code>mountain bike</code></p>
<pre><code>GET http://host/service/Products?$search="mountain bike"</code></pre>
</div>
<p>The upper-case keyword <code>NOT</code> restricts the set of entities to those that do not match the specified term.</p>
<div class="example">
-<p>Example 60: return all Products that do not match <code>clothing</code></p>
+<p>Example 62: return all Products that do not match <code>clothing</code></p>
<pre><code>GET http://host/service/Products?$search=NOT clothing</code></pre>
</div>
<p>Multiple terms within a search expression are separated by a space (implicit <code>AND</code>) or the upper-case keyword <code>AND</code>, indicating that all such terms must be matched.</p>
<div class="example">
-<p>Example 61: return all Products that match both <code>mountain</code> and <code>bike</code></p>
+<p>Example 63: return all Products that match both <code>mountain</code> and <code>bike</code></p>
<pre><code>GET http://host/service/Products?$search=mountain AND bike</code></pre>
</div>
<p>The upper-case keyword <code>OR</code> is used to return entities that satisfy either the immediately preceding or subsequent expression.</p>
<div class="example">
-<p>Example 62: return all Products that match <code>mountain</code> or <code>bike</code></p>
+<p>Example 64: return all Products that match <code>mountain</code> or <code>bike</code></p>
<pre><code>GET http://host/service/Products?$search=mountain OR bike</code></pre>
</div>
<p>Parentheses within the search expression group together multiple expressions.</p>
<div class="example">
-<p>Example 63: return all Products that match <code>mountain</code> or <code>bike</code> and do not match clothing</p>
+<p>Example 65: return all Products that match <code>mountain</code> or <code>bike</code> and do not match clothing</p>
<pre><code>GET http://host/service/Products?$search=(mountain OR bike) AND NOT clothing</code></pre>
</div>
<p>The operations within a search expression MUST be evaluated in the following order: grouping operator, <code>NOT</code> operator, <code>AND</code> operator, <code>OR</code> operator</p>
@@ -2111,7 +2115,7 @@ <h4 id="11268-requesting-an-individual-member-of-an-ordered-collection"><a id="R
<p>Individual members of collections of primitive and complex types annotated with the <code>Ordered</code> term (see <a href="#ODataVocCore">OData-VocCore</a>) are addressable by appending a segment containing the zero-based ordinal to the URL of the collection. A negative ordinal indexes from the end of the collection, with -1 representing the last item in the collection.</p>
<p>Entities are stably addressable using their canonical URL and are not accessible using an ordinal index.</p>
<div class="example">
-<p>Example 64: the first address in a list of addresses for <code>MainSupplier</code></p>
+<p>Example 66: the first address in a list of addresses for <code>MainSupplier</code></p>
<pre><code>GET http://host/service/MainSupplier/Addresses/0</code></pre>
</div>
</details>
@@ -2124,7 +2128,7 @@ <h3 id="1127-requesting-related-entities"><a id="RequestingRelatedEntities" href
<p>If the relationship terminates on a collection, the response MUST be the format-specific representation of the collection of related entities. If no entities are related, the response is the format-specific representation of an empty collection.</p>
<p>If the relationship terminates on a single entity, the response MUST be the format-specific representation of the related single entity. If no entity is related, the service returns <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>.</p>
<div class="example">
-<p>Example 65: return the supplier of the product with <code>ID=1</code> in the Products entity set</p>
+<p>Example 67: return the supplier of the product with <code>ID=1</code> in the Products entity set</p>
<pre><code>GET http://host/service/Products(1)/Supplier</code></pre>
</div>
</details>
@@ -2137,7 +2141,7 @@ <h3 id="1128-requesting-entity-references"><a id="RequestingEntityReferences" hr
<p>If the resource path identifies a single existing entity, the response MUST be the format-specific representation of an entity reference. The response MAY contain an <a href="#HeaderETag"><code>ETag</code></a> header which represents the identity of the referenced entity. If the resource path terminates in a single-valued navigation path, the ETag value changes if the relationship is changed and points to a different OData entity. If the resource path is the canonical path for a single entity, the returned ETag can never change.</p>
<p>If the resource path terminates on a single entity and no such entity exists, the service returns either <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> or <a href="#ResponseCode404NotFound"><code>404 Not Found</code></a>.</p>
<div class="example">
-<p>Example 66: collection with an entity reference for each Order related to the Product with <code>ID=0</code></p>
+<p>Example 68: collection with an entity reference for each Order related to the Product with <code>ID=0</code></p>
<pre><code>GET http://host/service/Products(0)/Orders/$ref</code></pre>
</div>
</details>
@@ -2146,13 +2150,13 @@ <h3 id="1129-resolving-an-entity-id"><a id="ResolvinganEntityId" href="#Resolvin
</summary>
<p>To resolve an <a href="#EntityIdsandEntityReferences">entity-id</a>, e.g. obtained in an entity reference, into a representation of the identified entity, the client issues a <code>GET</code> request to the <code>$entity</code> resource located at the URL <code>$entity</code> relative to the service root. The entity-id MUST be specified using the system query option <code>$id</code>.</p>
<div class="example">
-<p>Example 67: return the entity representation for a given entity-id</p>
+<p>Example 69: return the entity representation for a given entity-id</p>
<pre><code>GET http://host/service/$entity?$id=http://host/service/Products(0)</code></pre>
</div>
<p>A type segment following the <code>$entity</code> resource casts the resource to the specified type. If the identified entity is not of the specified type, or a type derived from the specified type, the service returns <a href="#ResponseCode404NotFound"><code>404 Not Found</code></a>.</p>
<p>After applying a type-cast segment to cast to a specific type, the system query options <a href="#SystemQueryOptionselect"><code>$select</code></a> and <a href="#SystemQueryOptionexpand"><code>$expand</code></a> can be specified in <code>GET</code> requests to the <code>$entity</code> resource.</p>
<div class="example">
-<p>Example 68: return the entity representation for a given entity-id and specify properties to return</p>
+<p>Example 70: return the entity representation for a given entity-id and specify properties to return</p>
<pre><code>GET http://host/service/$entity/Model.Customer
?$id=http://host/service/Customers('ALFKI')
&$select=CompanyName,ContactName
@@ -2165,27 +2169,27 @@ <h3 id="11210-requesting-the-number-of-items-in-a-collection"><a id="Requestingt
<p>To request only the number of items of a collection of entities or items of a collection-valued property, the client issues a <code>GET</code> request with <code>/$count</code> appended to the resource path of the collection.</p>
<p>On success, the response body MUST contain the exact count of items matching the request after applying any <a href="#SystemQueryOptionfilter"><code>$filter</code></a> or <a href="#SystemQueryOptionsearch"><code>$search</code></a> system query options, formatted as a simple primitive integer value with media type <code>text/plain</code>. Clients SHOULD NOT combine the system query options <a href="#SystemQueryOptiontop"><code>$top</code></a>, <a href="#SystemQueryOptionskip"><code>$skip</code></a>, <a href="#SystemQueryOptionorderby"><code>$orderby</code></a>, <a href="#SystemQueryOptionexpand"><code>$expand</code></a>, and <a href="#SystemQueryOptionformat"><code>$format</code></a> with the path suffix <code>/$count</code>. The result of such a request is undefined.</p>
<div class="example">
-<p>Example 69: return the number of products in the Products entity set</p>
+<p>Example 71: return the number of products in the Products entity set</p>
<pre><code>GET http://host/service/Products/$count</code></pre>
</div>
<p>With 4.01 services the <code>/$count</code> segment MAY be used in combination with the <code>/$filter</code> path segment to count the items in the filtered collection.</p>
<div class="example">
-<p>Example 70: return the number of products whose <code>Price</code> is less than $10.00</p>
+<p>Example 72: return the number of products whose <code>Price</code> is less than $10.00</p>
<pre><code>GET http://host/service/Products/$filter(@foo)/$count?@foo=Price lt 10.00</code></pre>
</div>
<p>For backwards compatibility, the <code>/$count</code> suffix MAY be used in combination with the <a href="#SystemQueryOptionfilter"><code>$filter</code></a> system query option.</p>
<div class="example">
-<p>Example 71: return the number of products whose <code>Price</code> is less than $10.00</p>
+<p>Example 73: return the number of products whose <code>Price</code> is less than $10.00</p>
<pre><code>GET http://host/service/Products/$count?$filter=Price lt 10.00</code></pre>
</div>
<p>The <a href="#SystemQueryOptionfilter"><code>$filter</code></a> system query option MUST NOT be used in conjunction with a both a <code>/$count</code> path segment and a <code>/$filter</code> path segment.</p>
<p>The <code>/$count</code> suffix can also be used in path expressions within system query options, e.g. <a href="#SystemQueryOptionfilter"><code>$filter</code></a>.</p>
<div class="example">
-<p>Example 72: return all customers with more than five interests</p>
+<p>Example 74: return all customers with more than five interests</p>
<pre><code>GET http://host/service/Customers?$filter=Interests/$count gt 5</code></pre>
</div>
<div class="example">
-<p>Example 73: return all categories with more than one product over $5.00</p>
+<p>Example 75: return all categories with more than one product over $5.00</p>
<pre><code>GET http://host/service/Categories?$filter=Products/$filter(Price gt 5.0)/$count gt 1</code></pre>
</div>
</details>
@@ -2197,12 +2201,12 @@ <h3 id="11211-system-query-option-format"><a id="SystemQueryOptionformat" href="
<p>The value of the <code>$format</code> system query option is a valid internet media type, optionally including parameters.</p>
<p>In addition, format-specific abbreviations may be used, e.g. <code>json</code> for <code>application/json</code>, see <a href="#ODataJSON">OData-JSON</a>, but format parameters MUST NOT be appended to the format abbreviations.</p>
<div class="example">
-<p>Example 74: the request</p>
+<p>Example 76: the request</p>
<pre><code>GET http://host/service/Orders?$format=application/json;metadata=full</code></pre>
</div>
<p>is equivalent to a request with an <code>Accept</code> 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 <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadatafullodatametadatafull">OData-JSON, section 3.1.2</a>.</p>
<div class="example">
-<p>Example 75: the request</p>
+<p>Example 77: the request</p>
<pre><code>GET http://host/service/Orders?$format=json</code></pre>
</div>
<p>is equivalent to a request with the <code>Accept</code> header set to <code>application/json</code>; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#metadataminimalodatametadataminimal">OData-JSON, section 3.1.1</a>.</p>
@@ -2336,29 +2340,29 @@ <h4 id="11421-link-to-related-entities-when-creating-an-entity"><a id="LinktoRel
<p>To create a new entity with links to existing entities in a single request, the client includes references to the related entities in the request body.</p>
<p>The representation for referencing related entities is format-specific.</p>
<div class="example">
-<p>Example 76: 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 <code>odata.bind</code> annotation to the <code>Manager</code> and <code>DirectReports</code> navigation properties</p>
-<div class="sourceCode" id="cb95"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb95-1"><a href="#cb95-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb95-2"><a href="#cb95-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Northwind.Manager"</span><span class="fu">,</span></span>
-<span id="cb95-3"><a href="#cb95-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">1</span><span class="fu">,</span></span>
-<span id="cb95-4"><a href="#cb95-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Pat"</span><span class="fu">,</span></span>
-<span id="cb95-5"><a href="#cb95-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Griswold"</span><span class="fu">,</span></span>
-<span id="cb95-6"><a href="#cb95-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Manager@odata.bind"</span><span class="fu">:</span> <span class="st">"http://host/service/Employees(0)"</span><span class="fu">,</span></span>
-<span id="cb95-7"><a href="#cb95-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DirectReports@odata.bind"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb95-8"><a href="#cb95-8" aria-hidden="true" tabindex="-1"></a> <span class="st">"http://host/service/Employees(5)"</span><span class="ot">,</span></span>
-<span id="cb95-9"><a href="#cb95-9" aria-hidden="true" tabindex="-1"></a> <span class="st">"http://host/service/Employees(6)"</span></span>
-<span id="cb95-10"><a href="#cb95-10" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
-<span id="cb95-11"><a href="#cb95-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
-</div>
-<div class="example">
-<p>Example 77: 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 <code>Manager</code> and <code>DirectReports</code> navigation properties</p>
+<p>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 <code>odata.bind</code> annotation to the <code>Manager</code> and <code>DirectReports</code> navigation properties</p>
<div class="sourceCode" id="cb96"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb96-1"><a href="#cb96-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb96-2"><a href="#cb96-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Northwind.Manager"</span><span class="fu">,</span></span>
<span id="cb96-3"><a href="#cb96-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">1</span><span class="fu">,</span></span>
<span id="cb96-4"><a href="#cb96-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Pat"</span><span class="fu">,</span></span>
<span id="cb96-5"><a href="#cb96-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Griswold"</span><span class="fu">,</span></span>
-<span id="cb96-6"><a href="#cb96-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Manager"</span><span class="fu">:</span> <span class="fu">{</span> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(0)"</span> <span class="fu">},</span></span>
-<span id="cb96-7"><a href="#cb96-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DirectReports"</span><span class="fu">:</span> <span class="ot">[</span><span class="fu">{</span> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(5)"</span> <span class="fu">}</span><span class="ot">,</span> <span class="fu">{</span> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(6)"</span> <span class="fu">}</span><span class="ot">]</span></span>
-<span id="cb96-8"><a href="#cb96-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<span id="cb96-6"><a href="#cb96-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Manager@odata.bind"</span><span class="fu">:</span> <span class="st">"http://host/service/Employees(0)"</span><span class="fu">,</span></span>
+<span id="cb96-7"><a href="#cb96-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DirectReports@odata.bind"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb96-8"><a href="#cb96-8" aria-hidden="true" tabindex="-1"></a> <span class="st">"http://host/service/Employees(5)"</span><span class="ot">,</span></span>
+<span id="cb96-9"><a href="#cb96-9" aria-hidden="true" tabindex="-1"></a> <span class="st">"http://host/service/Employees(6)"</span></span>
+<span id="cb96-10"><a href="#cb96-10" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb96-11"><a href="#cb96-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+</div>
+<div class="example">
+<p>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 <code>Manager</code> and <code>DirectReports</code> navigation properties</p>
+<div class="sourceCode" id="cb97"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb97-1"><a href="#cb97-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb97-2"><a href="#cb97-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Northwind.Manager"</span><span class="fu">,</span></span>
+<span id="cb97-3"><a href="#cb97-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ID"</span><span class="fu">:</span> <span class="dv">1</span><span class="fu">,</span></span>
+<span id="cb97-4"><a href="#cb97-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Pat"</span><span class="fu">,</span></span>
+<span id="cb97-5"><a href="#cb97-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Griswold"</span><span class="fu">,</span></span>
+<span id="cb97-6"><a href="#cb97-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Manager"</span><span class="fu">:</span> <span class="fu">{</span> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(0)"</span> <span class="fu">},</span></span>
+<span id="cb97-7"><a href="#cb97-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DirectReports"</span><span class="fu">:</span> <span class="ot">[</span><span class="fu">{</span> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(5)"</span> <span class="fu">}</span><span class="ot">,</span> <span class="fu">{</span> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(6)"</span> <span class="fu">}</span><span class="ot">]</span></span>
+<span id="cb97-8"><a href="#cb97-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>Upon successful completion of the operation, the service creates the requested entity and relates it to the requested existing entities.</p>
<p>If the target URL for the collection the entity is created in and binding information provided in the <code>POST</code> body contradicts the implicit binding information provided by the request URL, the request MUST fail, and the service responds with <code>400 Bad Request</code>.</p>
@@ -2412,29 +2416,29 @@ <h4 id="11431-update-related-entities-when-updating-an-entity"><a id="UpdateRela
<p>Payloads with an <code>OData-Version</code> header with a value of <code>4.01</code> or greater MAY include nested entities and entity references that specify the full set of to be related entities, or a nested <a href="#DeltaPayloads">delta payload</a> representing the related entities that have been added, removed, or changed. Such a request is referred to as a “deep update”. If the nested collection is represented identical to an expanded navigation property, then the set of nested entities and entity references specified in a successful update request represents the full set of entities to be related according to that relationship and MUST NOT include added links, deleted links, or deleted entities.</p>
<p>If a navigation property is absent from a <code>PUT</code> or <code>PATCH</code> request payload, the referenced or contained entity, or the collection thereof, remains unchanged by a successful update.</p>
<div class="example">
-<p>Example 78: using the JSON format, a 4.01 <code>PATCH</code> request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named <code>Suzanne Brown</code>. The <code>LastName</code> of employee 6 is updated to <code>Smith</code>.</p>
-<div class="sourceCode" id="cb97"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb97-1"><a href="#cb97-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb97-2"><a href="#cb97-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Northwind.Manager"</span><span class="fu">,</span></span>
-<span id="cb97-3"><a href="#cb97-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Patricia"</span><span class="fu">,</span></span>
-<span id="cb97-4"><a href="#cb97-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DirectReports"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb97-5"><a href="#cb97-5" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb97-6"><a href="#cb97-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(5)"</span></span>
-<span id="cb97-7"><a href="#cb97-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb97-8"><a href="#cb97-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb97-9"><a href="#cb97-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(6)"</span><span class="fu">,</span></span>
-<span id="cb97-10"><a href="#cb97-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Smith"</span></span>
-<span id="cb97-11"><a href="#cb97-11" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb97-12"><a href="#cb97-12" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb97-13"><a href="#cb97-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Suzanne"</span><span class="fu">,</span></span>
-<span id="cb97-14"><a href="#cb97-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Brown"</span></span>
-<span id="cb97-15"><a href="#cb97-15" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
-<span id="cb97-16"><a href="#cb97-16" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
-<span id="cb97-17"><a href="#cb97-17" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 80: using the JSON format, a 4.01 <code>PATCH</code> request can update a manager entity. Following the update, the manager has three direct reports; two existing employees and one new employee named <code>Suzanne Brown</code>. The <code>LastName</code> of employee 6 is updated to <code>Smith</code>.</p>
+<div class="sourceCode" id="cb98"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb98-1"><a href="#cb98-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb98-2"><a href="#cb98-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Northwind.Manager"</span><span class="fu">,</span></span>
+<span id="cb98-3"><a href="#cb98-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Patricia"</span><span class="fu">,</span></span>
+<span id="cb98-4"><a href="#cb98-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DirectReports"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb98-5"><a href="#cb98-5" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb98-6"><a href="#cb98-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(5)"</span></span>
+<span id="cb98-7"><a href="#cb98-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb98-8"><a href="#cb98-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb98-9"><a href="#cb98-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(6)"</span><span class="fu">,</span></span>
+<span id="cb98-10"><a href="#cb98-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Smith"</span></span>
+<span id="cb98-11"><a href="#cb98-11" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb98-12"><a href="#cb98-12" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb98-13"><a href="#cb98-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Suzanne"</span><span class="fu">,</span></span>
+<span id="cb98-14"><a href="#cb98-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Brown"</span></span>
+<span id="cb98-15"><a href="#cb98-15" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb98-16"><a href="#cb98-16" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb98-17"><a href="#cb98-17" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>If the nested collection is represented as a delta annotation on the navigation property, then the collection contains members to be added or changed and MAY include deleted entities for entities that are no longer part of the collection, using the <a href="#DeltaPayloads">delta payload</a> format. If the deleted entity specifies a <code>reason</code> as <code>deleted</code>, then the entity is both removed from the collection and deleted, otherwise it is removed from the collection and only deleted if the relationship is contained. Non-key properties of the deleted entity are ignored. Nested collections MUST NOT contain added or deleted links. If the request contains nested delta collections, then the <code>PATCH</code> verb must be specified.</p>
<p>If a nested entity has the same id or key fields as an existing entity, the existing entity is updated according to the semantics of the <code>PUT</code> or <code>PATCH</code> request. Nested entities that have no id or key fields, or for which the id or key fields do not match existing entities, are treated as inserts. If the nested collection does not represent a containment relationship and has no navigation property binding, then such entities MUST include a context URL specifying the entity set in which the new entity is to be created. If any nested entities contain both id and key fields, they MUST identify the same entity, or the request is invalid.</p>
<div class="example">
-<p>Example 79: using the JSON format, a 4.01 <code>PATCH</code> request can specify a nested delta representation to:</p>
+<p>Example 81: using the JSON format, a 4.01 <code>PATCH</code> request can specify a nested delta representation to:</p>
<ul>
<li>delete employee 3 and remove link to it</li>
<li>remove the link to employee 4 and do not delete it</li>
@@ -2442,96 +2446,96 @@ <h4 id="11431-update-related-entities-when-updating-an-entity"><a id="UpdateRela
<li>change the last name of employee 6 and link to it if necessary</li>
<li>add a new employee named “Suzanne Brown” and link to it</li>
</ul>
-<div class="sourceCode" id="cb98"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb98-1"><a href="#cb98-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb98-2"><a href="#cb98-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Northwind.Manager"</span><span class="fu">,</span></span>
-<span id="cb98-3"><a href="#cb98-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Patricia"</span><span class="fu">,</span></span>
-<span id="cb98-4"><a href="#cb98-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DirectReports@delta"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb98-5"><a href="#cb98-5" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb98-6"><a href="#cb98-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@removed"</span><span class="fu">:</span> <span class="fu">{</span></span>
-<span id="cb98-7"><a href="#cb98-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"reason"</span><span class="fu">:</span> <span class="st">"deleted"</span></span>
-<span id="cb98-8"><a href="#cb98-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
-<span id="cb98-9"><a href="#cb98-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(3)"</span></span>
-<span id="cb98-10"><a href="#cb98-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb98-11"><a href="#cb98-11" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb98-12"><a href="#cb98-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@removed"</span><span class="fu">:</span> <span class="fu">{</span></span>
-<span id="cb98-13"><a href="#cb98-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">"reason"</span><span class="fu">:</span> <span class="st">"changed"</span></span>
-<span id="cb98-14"><a href="#cb98-14" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
-<span id="cb98-15"><a href="#cb98-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(4)"</span></span>
-<span id="cb98-16"><a href="#cb98-16" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb98-17"><a href="#cb98-17" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb98-18"><a href="#cb98-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(5)"</span></span>
-<span id="cb98-19"><a href="#cb98-19" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb98-20"><a href="#cb98-20" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb98-21"><a href="#cb98-21" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(6)"</span><span class="fu">,</span></span>
-<span id="cb98-22"><a href="#cb98-22" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Smith"</span></span>
-<span id="cb98-23"><a href="#cb98-23" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb98-24"><a href="#cb98-24" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb98-25"><a href="#cb98-25" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Suzanne"</span><span class="fu">,</span></span>
-<span id="cb98-26"><a href="#cb98-26" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Brown"</span></span>
-<span id="cb98-27"><a href="#cb98-27" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
-<span id="cb98-28"><a href="#cb98-28" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
-<span id="cb98-29"><a href="#cb98-29" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
-</div>
-<div class="example">
-<p>Example 80: When updating an entity with a 4.01 <code>PUT</code> request, the target of a non-containment navigation property can be replaced if the targeted entity is specified by an entity reference (see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#EntityReference">OData-JSON, section 14</a>), without specifying all its structural properties in <code>PUT</code> semantics.</p>
+<div class="sourceCode" id="cb99"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb99-1"><a href="#cb99-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb99-2"><a href="#cb99-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@type"</span><span class="fu">:</span> <span class="st">"#Northwind.Manager"</span><span class="fu">,</span></span>
+<span id="cb99-3"><a href="#cb99-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Patricia"</span><span class="fu">,</span></span>
+<span id="cb99-4"><a href="#cb99-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"DirectReports@delta"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb99-5"><a href="#cb99-5" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb99-6"><a href="#cb99-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@removed"</span><span class="fu">:</span> <span class="fu">{</span></span>
+<span id="cb99-7"><a href="#cb99-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"reason"</span><span class="fu">:</span> <span class="st">"deleted"</span></span>
+<span id="cb99-8"><a href="#cb99-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
+<span id="cb99-9"><a href="#cb99-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(3)"</span></span>
+<span id="cb99-10"><a href="#cb99-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb99-11"><a href="#cb99-11" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb99-12"><a href="#cb99-12" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@removed"</span><span class="fu">:</span> <span class="fu">{</span></span>
+<span id="cb99-13"><a href="#cb99-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">"reason"</span><span class="fu">:</span> <span class="st">"changed"</span></span>
+<span id="cb99-14"><a href="#cb99-14" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
+<span id="cb99-15"><a href="#cb99-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(4)"</span></span>
+<span id="cb99-16"><a href="#cb99-16" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb99-17"><a href="#cb99-17" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb99-18"><a href="#cb99-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(5)"</span></span>
+<span id="cb99-19"><a href="#cb99-19" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb99-20"><a href="#cb99-20" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb99-21"><a href="#cb99-21" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Employees(6)"</span><span class="fu">,</span></span>
+<span id="cb99-22"><a href="#cb99-22" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Smith"</span></span>
+<span id="cb99-23"><a href="#cb99-23" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb99-24"><a href="#cb99-24" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb99-25"><a href="#cb99-25" aria-hidden="true" tabindex="-1"></a> <span class="dt">"FirstName"</span><span class="fu">:</span> <span class="st">"Suzanne"</span><span class="fu">,</span></span>
+<span id="cb99-26"><a href="#cb99-26" aria-hidden="true" tabindex="-1"></a> <span class="dt">"LastName"</span><span class="fu">:</span> <span class="st">"Brown"</span></span>
+<span id="cb99-27"><a href="#cb99-27" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb99-28"><a href="#cb99-28" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb99-29"><a href="#cb99-29" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+</div>
+<div class="example">
+<p>Example 82: When updating an entity with a 4.01 <code>PUT</code> request, the target of a non-containment navigation property can be replaced if the targeted entity is specified by an entity reference (see <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#EntityReference">OData-JSON, section 14</a>), without specifying all its structural properties in <code>PUT</code> semantics.</p>
<p>The following JSON payload changes the name of a category and the products belonging to it. (Compare this to <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#deepupdate">OData-JSON, example 22</a>.) The effect would be the same if the <code>@context</code> was omitted from the request.</p>
<div class="side-by-side">
<div class="caption">
<p>Request</p>
-<div class="sourceCode" id="cb99"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb99-1"><a href="#cb99-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">http://host/service/Categories(6)?$expand=Products</span></span>
-<span id="cb99-2"><a href="#cb99-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb99-3"><a href="#cb99-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb99-4"><a href="#cb99-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb99-5"><a href="#cb99-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
-<span id="cb99-6"><a href="#cb99-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb99-7"><a href="#cb99-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb99-8"><a href="#cb99-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#$ref"</span><span class="fu">,</span></span>
-<span id="cb99-9"><a href="#cb99-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(57)"</span></span>
-<span id="cb99-10"><a href="#cb99-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
-<span id="cb99-11"><a href="#cb99-11" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
-<span id="cb99-12"><a href="#cb99-12" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<div class="sourceCode" id="cb100"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb100-1"><a href="#cb100-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">http://host/service/Categories(6)?$expand=Products</span></span>
+<span id="cb100-2"><a href="#cb100-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb100-3"><a href="#cb100-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb100-4"><a href="#cb100-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb100-5"><a href="#cb100-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
+<span id="cb100-6"><a href="#cb100-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb100-7"><a href="#cb100-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb100-8"><a href="#cb100-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#$ref"</span><span class="fu">,</span></span>
+<span id="cb100-9"><a href="#cb100-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(57)"</span></span>
+<span id="cb100-10"><a href="#cb100-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb100-11"><a href="#cb100-11" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb100-12"><a href="#cb100-12" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<div class="caption">
<p>Response</p>
-<div class="sourceCode" id="cb100"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb100-1"><a href="#cb100-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb100-2"><a href="#cb100-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#Categories/$entity"</span><span class="fu">,</span></span>
-<span id="cb100-3"><a href="#cb100-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CategoryID"</span><span class="fu">:</span> <span class="dv">6</span><span class="fu">,</span></span>
-<span id="cb100-4"><a href="#cb100-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
-<span id="cb100-5"><a href="#cb100-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb100-6"><a href="#cb100-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb100-7"><a href="#cb100-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span><span class="fu">,</span></span>
-<span id="cb100-8"><a href="#cb100-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Widgets"</span></span>
-<span id="cb100-9"><a href="#cb100-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
-<span id="cb100-10"><a href="#cb100-10" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
-<span id="cb100-11"><a href="#cb100-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<div class="sourceCode" id="cb101"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb101-1"><a href="#cb101-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb101-2"><a href="#cb101-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#Categories/$entity"</span><span class="fu">,</span></span>
+<span id="cb101-3"><a href="#cb101-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CategoryID"</span><span class="fu">:</span> <span class="dv">6</span><span class="fu">,</span></span>
+<span id="cb101-4"><a href="#cb101-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
+<span id="cb101-5"><a href="#cb101-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb101-6"><a href="#cb101-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb101-7"><a href="#cb101-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span><span class="fu">,</span></span>
+<span id="cb101-8"><a href="#cb101-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Widgets"</span></span>
+<span id="cb101-9"><a href="#cb101-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb101-10"><a href="#cb101-10" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb101-11"><a href="#cb101-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
</div>
<p>If <code>Products</code> was a containment navigation property, the request and response would be the same, except that the <code>@id</code> would likely be relative to the category, for example, <code>Categories(6)/Products(57)</code>.</p>
<p>If the targeted entity in the payload contains some structural properties, <code>PUT</code> resets all its other structural properties. The following alternative payload resets the product name. The effect would be the same if the <code>@id</code> was omitted from the request.</p>
<div class="side-by-side">
-<div class="sourceCode" id="cb101"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb101-1"><a href="#cb101-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">http://host/service/Categories(6)?$expand=Products</span></span>
-<span id="cb101-2"><a href="#cb101-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb101-3"><a href="#cb101-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb101-4"><a href="#cb101-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb101-5"><a href="#cb101-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
-<span id="cb101-6"><a href="#cb101-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb101-7"><a href="#cb101-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb101-8"><a href="#cb101-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(57)"</span><span class="fu">,</span></span>
-<span id="cb101-9"><a href="#cb101-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span></span>
-<span id="cb101-10"><a href="#cb101-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
-<span id="cb101-11"><a href="#cb101-11" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
-<span id="cb101-12"><a href="#cb101-12" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
-<div class="sourceCode" id="cb102"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb102-1"><a href="#cb102-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb102-2"><a href="#cb102-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#Categories/$entity"</span><span class="fu">,</span></span>
-<span id="cb102-3"><a href="#cb102-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CategoryID"</span><span class="fu">:</span> <span class="dv">6</span><span class="fu">,</span></span>
-<span id="cb102-4"><a href="#cb102-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
-<span id="cb102-5"><a href="#cb102-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb102-6"><a href="#cb102-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
-<span id="cb102-7"><a href="#cb102-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span><span class="fu">,</span></span>
-<span id="cb102-8"><a href="#cb102-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="kw">null</span></span>
-<span id="cb102-9"><a href="#cb102-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
-<span id="cb102-10"><a href="#cb102-10" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
-<span id="cb102-11"><a href="#cb102-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<div class="sourceCode" id="cb102"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb102-1"><a href="#cb102-1" aria-hidden="true" tabindex="-1"></a><span class="er">PUT</span> <span class="er">http://host/service/Categories(6)?$expand=Products</span></span>
+<span id="cb102-2"><a href="#cb102-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb102-3"><a href="#cb102-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb102-4"><a href="#cb102-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb102-5"><a href="#cb102-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
+<span id="cb102-6"><a href="#cb102-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb102-7"><a href="#cb102-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb102-8"><a href="#cb102-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@id"</span><span class="fu">:</span> <span class="st">"Products(57)"</span><span class="fu">,</span></span>
+<span id="cb102-9"><a href="#cb102-9" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span></span>
+<span id="cb102-10"><a href="#cb102-10" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb102-11"><a href="#cb102-11" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb102-12"><a href="#cb102-12" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<div class="sourceCode" id="cb103"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb103-1"><a href="#cb103-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb103-2"><a href="#cb103-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"$metadata#Categories/$entity"</span><span class="fu">,</span></span>
+<span id="cb103-3"><a href="#cb103-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CategoryID"</span><span class="fu">:</span> <span class="dv">6</span><span class="fu">,</span></span>
+<span id="cb103-4"><a href="#cb103-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"UpdatedCategory"</span><span class="fu">,</span></span>
+<span id="cb103-5"><a href="#cb103-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Products"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb103-6"><a href="#cb103-6" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span></span>
+<span id="cb103-7"><a href="#cb103-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"ProductID"</span><span class="fu">:</span> <span class="dv">57</span><span class="fu">,</span></span>
+<span id="cb103-8"><a href="#cb103-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Name"</span><span class="fu">:</span> <span class="kw">null</span></span>
+<span id="cb103-9"><a href="#cb103-9" aria-hidden="true" tabindex="-1"></a> <span class="fu">}</span></span>
+<span id="cb103-10"><a href="#cb103-10" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span></span>
+<span id="cb103-11"><a href="#cb103-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
</div>
<p>Clients MAY associate an id with individual nested entities in the request by using the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a>. Services that respond with <a href="#ResponseCode200OK"><code>200 OK</code></a> SHOULD annotate the entities in the response using the same <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> value as specified in the request. Services SHOULD advertise support for deep updates, including support for returning the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a>, through the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepUpdateSupport"><code>Capabilities.DeepUpdateSupport</code></a> term, defined in <a href="#ODataVocCap">OData-VocCap</a>.</p>
@@ -2636,22 +2640,22 @@ <h3 id="1148-managing-stream-properties"><a id="ManagingStreamProperties" href="
<p>An entity may have one or more <em>stream properties</em>. Stream properties are properties of type <code>Edm.Stream</code>.</p>
<p>The values for stream properties do not usually appear in the entity payload unless explicitly requested with <a href="#SystemQueryOptionexpand"><code>$expand</code></a>. Instead, the values are generally read or written through URLs.</p>
<div class="example">
-<p>Example <a id="entityWithStreamProperty" href="#entityWithStreamProperty">81</a>: read an entity and select a stream property</p>
+<p>Example <a id="entityWithStreamProperty" href="#entityWithStreamProperty">83</a>: read an entity and select a stream property</p>
<pre><code>GET http://host/service/Products(1)?$select=Thumbnail</code></pre>
<p>would only include control information for the stream property, not the stream data itself</p>
-<div class="sourceCode" id="cb104"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb104-1"><a href="#cb104-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb104-2"><a href="#cb104-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Products/$entity"</span><span class="fu">,</span></span>
-<span id="cb104-3"><a href="#cb104-3" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
-<span id="cb104-4"><a href="#cb104-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaReadLink"</span><span class="fu">:</span> <span class="st">"http://server/Thumbnail546.jpg"</span><span class="fu">,</span></span>
-<span id="cb104-5"><a href="#cb104-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaEditLink"</span><span class="fu">:</span> <span class="st">"http://server/uploads/Thumbnail546.jpg"</span><span class="fu">,</span></span>
-<span id="cb104-6"><a href="#cb104-6" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
-<span id="cb104-7"><a href="#cb104-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<div class="sourceCode" id="cb105"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb105-1"><a href="#cb105-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb105-2"><a href="#cb105-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="st">"http://host/service/$metadata#Products/$entity"</span><span class="fu">,</span></span>
+<span id="cb105-3"><a href="#cb105-3" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
+<span id="cb105-4"><a href="#cb105-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaReadLink"</span><span class="fu">:</span> <span class="st">"http://server/Thumbnail546.jpg"</span><span class="fu">,</span></span>
+<span id="cb105-5"><a href="#cb105-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Thumbnail@mediaEditLink"</span><span class="fu">:</span> <span class="st">"http://server/uploads/Thumbnail546.jpg"</span><span class="fu">,</span></span>
+<span id="cb105-6"><a href="#cb105-6" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
+<span id="cb105-7"><a href="#cb105-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
<p>The stream data can then be requested using the media read link:</p>
<pre><code>GET http://server/Thumbnail546.jpg</code></pre>
</div>
<p>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.</p>
<div class="example">
-<p>Example 82: directly read a stream property of an entity</p>
+<p>Example 84: directly read a stream property of an entity</p>
<pre><code>GET http://host/service/Products(1)/Thumbnail</code></pre>
<p>can return <a href="#ResponseCode200OK"><code>200 OK</code></a> and the stream data (see <a href="#RequestingStreamProperties">section 11.2.4.1</a>), or a <a href="#ResponseCode3xxRedirection"><code>3xx Redirect</code></a> to the media read link of the stream property.</p>
</div>
@@ -2671,7 +2675,7 @@ <h4 id="11482-delete-stream-values"><a id="DeleteStreamValues" href="#DeleteStre
</summary>
<p>A successful <code>DELETE</code> request to the edit URL of a stream property attempts to set the property to null and results in an error if the property is non-nullable.</p>
<div class="example">
-<p>Example 83: delete the stream value using the media edit link retrieved in <a href="#entityWithStreamProperty">example 81</a></p>
+<p>Example 85: delete the stream value using the media edit link retrieved in <a href="#entityWithStreamProperty">example 83</a></p>
<pre><code>DELETE http://server/uploads/Thumbnail546.jpg</code></pre>
</div>
<p>Attempting to request a stream property whose value is null results in <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>.</p>
@@ -2733,13 +2737,13 @@ <h3 id="11411-positional-inserts"><a id="PositionalInserts" href="#PositionalIns
</summary>
<p>Collections of entity, complex, or primitive types annotated with the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#PositionalInsert"><code>Core.PositionalInsert</code></a> term (see <a href="#ODataVocCore">OData-VocCore</a>) support inserting items at a specific location via <code>POST</code> requests to the collection URL using the <code>$index</code> system query option. The value of the <code>$index</code> 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.</p>
<div class="example">
-<p>Example 84: Insert a new email address at the second position</p>
-<div class="sourceCode" id="cb108"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb108-1"><a href="#cb108-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/service/Customers('ALFKI')/EmailAddresses?$index=1</span></span>
-<span id="cb108-2"><a href="#cb108-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb108-3"><a href="#cb108-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb108-4"><a href="#cb108-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb108-5"><a href="#cb108-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"value"</span><span class="fu">:</span> <span class="st">"alfred@futterkiste.de"</span></span>
-<span id="cb108-6"><a href="#cb108-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 86: Insert a new email address at the second position</p>
+<div class="sourceCode" id="cb109"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb109-1"><a href="#cb109-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/service/Customers('ALFKI')/EmailAddresses?$index=1</span></span>
+<span id="cb109-2"><a href="#cb109-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb109-3"><a href="#cb109-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb109-4"><a href="#cb109-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb109-5"><a href="#cb109-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"value"</span><span class="fu">:</span> <span class="st">"alfred@futterkiste.de"</span></span>
+<span id="cb109-6"><a href="#cb109-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
</details>
<details open><summary>
@@ -2794,13 +2798,13 @@ <h3 id="11414-update-members-of-a-collection"><a id="UpdateMembersofaCollection"
<p>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.</p>
<p>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 <a href="#UpdateanEntity">updated</a> using <code>PATCH</code> semantics. Structured types MAY include nested collections or delta collections, in which case the semantics described in <a href="#UpdateaCollectionofEntities">Update a Collection of Entities</a> applies.</p>
<div class="example">
-<p>Example 85: change the color of all beige-brown products</p>
-<div class="sourceCode" id="cb109"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb109-1"><a href="#cb109-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/service/Products/$filter(@bar)/$each?@bar=Color</span> <span class="er">eq</span> <span class="er">'beige-brown'</span></span>
-<span id="cb109-2"><a href="#cb109-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb109-3"><a href="#cb109-3" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb109-4"><a href="#cb109-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb109-5"><a href="#cb109-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Color"</span><span class="fu">:</span> <span class="st">"taupe"</span></span>
-<span id="cb109-6"><a href="#cb109-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 87: change the color of all beige-brown products</p>
+<div class="sourceCode" id="cb110"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb110-1"><a href="#cb110-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/service/Products/$filter(@bar)/$each?@bar=Color</span> <span class="er">eq</span> <span class="er">'beige-brown'</span></span>
+<span id="cb110-2"><a href="#cb110-2" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb110-3"><a href="#cb110-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb110-4"><a href="#cb110-4" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb110-5"><a href="#cb110-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Color"</span><span class="fu">:</span> <span class="st">"taupe"</span></span>
+<span id="cb110-6"><a href="#cb110-6" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
<p>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 <a href="#UpdateaCollectionofEntities">Update a Collection of Entities</a>.</p>
<p>Clients should note that requesting a response may be expensive for services that could otherwise efficiently apply updates to a (possibly filtered) collection.</p>
@@ -2813,7 +2817,7 @@ <h3 id="11415-delete-members-of-a-collection"><a id="DeleteMembersofaCollection"
<p>Members of a collection can be deleted by submitting a <code>DELETE</code> request to the URL constructed by appending <code>/$each</code> to the resource path of the collection. The additional path segment expresses that the collection itself is not deleted.</p>
<p>The request resource path of the collection MAY contain type-cast or filter segments to subset the collection.</p>
<div class="example">
-<p>Example 86: delete all products older than 3</p>
+<p>Example 88: delete all products older than 3</p>
<pre><code>DELETE /service/Products/$filter(Age gt 3)/$each</code></pre>
</div>
<p>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.</p>
@@ -2832,25 +2836,25 @@ <h3 id="1151-binding-an-operation-to-a-resource"><a id="BindinganOperationtoaRes
<p><a href="#Actions">Actions</a> and <a href="#Functions">Functions</a> 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 <em>binding parameter</em>.</p>
<p>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 <em>binding parameter value</em>. Only aliases defined in the metadata document of the service can be used in URLs.</p>
<div class="example">
-<p>Example 87: the function <code>MostRecentOrder</code> can be bound to any URL that identifies a <code>SampleModel.Customer</code></p>
-<div class="sourceCode" id="cb111"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb111-1"><a href="#cb111-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"MostRecentOrder"</span><span class="ot"> IsBound=</span><span class="st">"true"</span>></span>
-<span id="cb111-2"><a href="#cb111-2" aria-hidden="true" tabindex="-1"></a> <<span class="kw">Parameter</span><span class="ot"> Name=</span><span class="st">"customer"</span><span class="ot"> Type=</span><span class="st">"SampleModel.Customer"</span> /></span>
-<span id="cb111-3"><a href="#cb111-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"SampleModel.Order"</span> /></span>
-<span id="cb111-4"><a href="#cb111-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
+<p>Example 89: the function <code>MostRecentOrder</code> can be bound to any URL that identifies a <code>SampleModel.Customer</code></p>
+<div class="sourceCode" id="cb112"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb112-1"><a href="#cb112-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"MostRecentOrder"</span><span class="ot"> IsBound=</span><span class="st">"true"</span>></span>
+<span id="cb112-2"><a href="#cb112-2" aria-hidden="true" tabindex="-1"></a> <<span class="kw">Parameter</span><span class="ot"> Name=</span><span class="st">"customer"</span><span class="ot"> Type=</span><span class="st">"SampleModel.Customer"</span> /></span>
+<span id="cb112-3"><a href="#cb112-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"SampleModel.Order"</span> /></span>
+<span id="cb112-4"><a href="#cb112-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
</div>
<div class="example">
-<p>Example 88: invoke the <code>MostRecentOrder</code> function with the value of the binding parameter <code>customer</code> being the entity identified by <code>http://host/service/Customers(6)</code></p>
+<p>Example 90: invoke the <code>MostRecentOrder</code> function with the value of the binding parameter <code>customer</code> being the entity identified by <code>http://host/service/Customers(6)</code></p>
<pre><code>GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()</code></pre>
</div>
<div class="example">
-<p>Example 89: the function <code>Comparison</code> can be bound to any URL that identifies a collection of entities</p>
-<div class="sourceCode" id="cb113"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb113-1"><a href="#cb113-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"Comparison"</span><span class="ot"> IsBound=</span><span class="st">"true"</span>></span>
-<span id="cb113-2"><a href="#cb113-2" aria-hidden="true" tabindex="-1"></a> <<span class="kw">Parameter</span><span class="ot"> Name=</span><span class="st">"in"</span><span class="ot"> Type=</span><span class="st">"Collection(Edm.EntityType)"</span> /></span>
-<span id="cb113-3"><a href="#cb113-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"Diff.Overview"</span> /></span>
-<span id="cb113-4"><a href="#cb113-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
+<p>Example 91: the function <code>Comparison</code> can be bound to any URL that identifies a collection of entities</p>
+<div class="sourceCode" id="cb114"><pre class="sourceCode xml"><code class="sourceCode xml"><span id="cb114-1"><a href="#cb114-1" aria-hidden="true" tabindex="-1"></a><<span class="kw">Function</span><span class="ot"> Name=</span><span class="st">"Comparison"</span><span class="ot"> IsBound=</span><span class="st">"true"</span>></span>
+<span id="cb114-2"><a href="#cb114-2" aria-hidden="true" tabindex="-1"></a> <<span class="kw">Parameter</span><span class="ot"> Name=</span><span class="st">"in"</span><span class="ot"> Type=</span><span class="st">"Collection(Edm.EntityType)"</span> /></span>
+<span id="cb114-3"><a href="#cb114-3" aria-hidden="true" tabindex="-1"></a> <<span class="kw">ReturnType</span><span class="ot"> Type=</span><span class="st">"Diff.Overview"</span> /></span>
+<span id="cb114-4"><a href="#cb114-4" aria-hidden="true" tabindex="-1"></a></<span class="kw">Function</span>></span></code></pre></div>
</div>
<div class="example">
-<p>Example 90: invoke the <code>Comparison</code> function on the set of red products</p>
+<p>Example 92: invoke the <code>Comparison</code> function on the set of red products</p>
<pre><code>GET http://host/service/Products/$filter(Color eq 'Red')/Diff.Comparison()</code></pre>
</div>
</details>
@@ -2861,7 +2865,7 @@ <h3 id="1152-applying-an-operation-to-members-of-a-collection"><a id="Applyingan
<p>The resource path of the collection MAY contain type-cast or filter segments to subset the collection.</p>
<p>The response is a collection with members that are instances of the result type of the bound operation. If the bound operation returns a collection, the response is a collection of collections.</p>
<div class="example">
-<p>Example 91: invoke the <code>MostRecentOrder</code> function on each entity in the entity set <code>Customers</code></p>
+<p>Example 93: invoke the <code>MostRecentOrder</code> function on each entity in the entity set <code>Customers</code></p>
<pre><code>GET http://host/service/Customers/$each/SampleModel.MostRecentOrder()</code></pre>
</div>
<p>The client MAY specify the <code>continue-on-error</code> preference, in which case the service MAY continue processing actions after a failure. In this case, the service MUST, regardless of the <code>return</code> 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 <code>Core.DataModificationException</code> with a <code>failedOperation</code> value of <code>invoke</code>.</p>
@@ -2872,29 +2876,29 @@ <h3 id="1153-advertising-available-operations-within-a-payload"><a id="Advertisi
</summary>
<p>Services MAY return actions and/or functions bound to a particular entity or entity collection as part of the representation of the entity or entity collection within the payload. The representation of an action or function depends on the <a href="#Formats">format</a>.</p>
<div class="example">
-<p>Example 92: given a <code>GET</code> request to <code>http://host/service/Customers('ALFKI')</code>, the service might respond with a Customer that includes the <code>SampleEntities.MostRecentOrder</code> function bound to the entity</p>
-<div class="sourceCode" id="cb116"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb116-1"><a href="#cb116-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb116-2"><a href="#cb116-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="er">…</span><span class="fu">,</span></span>
-<span id="cb116-3"><a href="#cb116-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CustomerID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
-<span id="cb116-4"><a href="#cb116-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
-<span id="cb116-5"><a href="#cb116-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"#SampleEntities.MostRecentOrder"</span><span class="fu">:</span> <span class="fu">{</span></span>
-<span id="cb116-6"><a href="#cb116-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"title"</span><span class="fu">:</span> <span class="st">"Most Recent Order"</span><span class="fu">,</span></span>
-<span id="cb116-7"><a href="#cb116-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"target"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/SampleEntities.MostRecentOrder()"</span></span>
-<span id="cb116-8"><a href="#cb116-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
-<span id="cb116-9"><a href="#cb116-9" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
-<span id="cb116-10"><a href="#cb116-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
-</div>
-<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingOperations">OData-URL, section 4.5</a>.</p>
-<p>Services can advertise that a function or action is not available for a particular instance by setting its value to null.</p>
-<div class="example">
-<p>Example 93: the <code>SampleEntities.MostRecentOrder</code> function is not available for customer <code>ALFKI</code></p>
+<p>Example 94: given a <code>GET</code> request to <code>http://host/service/Customers('ALFKI')</code>, the service might respond with a Customer that includes the <code>SampleEntities.MostRecentOrder</code> function bound to the entity</p>
<div class="sourceCode" id="cb117"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb117-1"><a href="#cb117-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb117-2"><a href="#cb117-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="er">…</span><span class="fu">,</span></span>
<span id="cb117-3"><a href="#cb117-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CustomerID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
<span id="cb117-4"><a href="#cb117-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
-<span id="cb117-5"><a href="#cb117-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"#SampleEntities.MostRecentOrder"</span><span class="fu">:</span> <span class="kw">null</span><span class="fu">,</span></span>
-<span id="cb117-6"><a href="#cb117-6" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
-<span id="cb117-7"><a href="#cb117-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<span id="cb117-5"><a href="#cb117-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"#SampleEntities.MostRecentOrder"</span><span class="fu">:</span> <span class="fu">{</span></span>
+<span id="cb117-6"><a href="#cb117-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"title"</span><span class="fu">:</span> <span class="st">"Most Recent Order"</span><span class="fu">,</span></span>
+<span id="cb117-7"><a href="#cb117-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">"target"</span><span class="fu">:</span> <span class="st">"Customers('ALFKI')/SampleEntities.MostRecentOrder()"</span></span>
+<span id="cb117-8"><a href="#cb117-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">},</span></span>
+<span id="cb117-9"><a href="#cb117-9" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
+<span id="cb117-10"><a href="#cb117-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+</div>
+<p>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 <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#AddressingOperations">OData-URL, section 4.5</a>.</p>
+<p>Services can advertise that a function or action is not available for a particular instance by setting its value to null.</p>
+<div class="example">
+<p>Example 95: the <code>SampleEntities.MostRecentOrder</code> function is not available for customer <code>ALFKI</code></p>
+<div class="sourceCode" id="cb118"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb118-1"><a href="#cb118-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb118-2"><a href="#cb118-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">"@context"</span><span class="fu">:</span> <span class="er">…</span><span class="fu">,</span></span>
+<span id="cb118-3"><a href="#cb118-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CustomerID"</span><span class="fu">:</span> <span class="st">"ALFKI"</span><span class="fu">,</span></span>
+<span id="cb118-4"><a href="#cb118-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">"CompanyName"</span><span class="fu">:</span> <span class="st">"Alfreds Futterkiste"</span><span class="fu">,</span></span>
+<span id="cb118-5"><a href="#cb118-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">"#SampleEntities.MostRecentOrder"</span><span class="fu">:</span> <span class="kw">null</span><span class="fu">,</span></span>
+<span id="cb118-6"><a href="#cb118-6" aria-hidden="true" tabindex="-1"></a> <span class="er">…</span></span>
+<span id="cb118-7"><a href="#cb118-7" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
</details>
<details open><summary>
@@ -2912,7 +2916,7 @@ <h4 id="11541-invoking-a-function"><a id="InvokingaFunction" href="#InvokingaFun
<p>To invoke a function through a function import the client issues a <code>GET</code> request to a URL identifying the function import and passing parameter values using <a href="#InlineParameterSyntax">inline parameter syntax</a>. 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.</p>
<p>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 <code>POST</code> request may be used to create a new entity in the identified collection.</p>
<div class="example">
-<p>Example 94: add a new item to the list of items of the shopping cart returned by the composable <code>MyShoppingCart</code> function import</p>
+<p>Example 96: add a new item to the list of items of the shopping cart returned by the composable <code>MyShoppingCart</code> function import</p>
<pre><code>POST http://host/service/MyShoppingCart()/Items
…</code></pre>
@@ -2929,22 +2933,22 @@ <h5 id="115411-inline-parameter-syntax"><a id="InlineParameterSyntax" href="#Inl
<p>Parameter values are specified inline by appending a comma-separated list of parameter values, enclosed by parenthesis to the function name.</p>
<p>Each parameter value is represented as a name/value pair in the format <code>Name=Value</code>, where <code>Name</code> is the name of the parameter to the function and <code>Value</code> is the parameter value.</p>
<div class="example">
-<p>Example 95: invoke a <code>Sales.EmployeesByManager</code> function which takes a single <code>ManagerID</code> parameter via the function import <code>EmployeesByManager</code></p>
+<p>Example 97: invoke a <code>Sales.EmployeesByManager</code> function which takes a single <code>ManagerID</code> parameter via the function import <code>EmployeesByManager</code></p>
<pre><code>GET http://host/service/EmployeesByManager(ManagerID=3)</code></pre>
</div>
<div class="example">
-<p>Example 96: return all Customers whose <code>City</code> property returns <code>Western</code> when passed to the <code>Sales.SalesRegion</code> function</p>
+<p>Example 98: return all Customers whose <code>City</code> property returns <code>Western</code> when passed to the <code>Sales.SalesRegion</code> function</p>
<pre><code>GET http://host/service/Customers?
$filter=Sales.SalesRegion(City=$it/City) eq 'Western'</code></pre>
</div>
<p>A <a href="#ParameterAliases">parameter alias</a> 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.</p>
<div class="example">
-<p>Example 97: invoke a <code>Sales.EmployeesByManager</code> function via the function import <code>EmployeesByManager</code>, passing 3 for the <code>ManagerID</code> parameter</p>
+<p>Example 99: invoke a <code>Sales.EmployeesByManager</code> function via the function import <code>EmployeesByManager</code>, passing 3 for the <code>ManagerID</code> parameter</p>
<pre><code>GET http://host/service/EmployeesByManager(ManagerID=@p1)?@p1=3</code></pre>
</div>
<p>Services MAY in addition allow implicit <a href="#ParameterAliases">parameter aliases</a> 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 (<code>@</code>) 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 <code>$</code> prefix), the parameter name MUST be prefixed with an at (<code>@</code>) sign.</p>
<div class="example">
-<p>Example 98: invoke a <code>Sales.EmployeesByManager</code> function via the function import <code>EmployeesByManager</code>, passing 3 for the <code>ManagerID</code> parameter using the implicit parameter alias</p>
+<p>Example 100: invoke a <code>Sales.EmployeesByManager</code> function via the function import <code>EmployeesByManager</code>, passing 3 for the <code>ManagerID</code> parameter using the implicit parameter alias</p>
<pre><code>GET http://host/service/EmployeesByManager?ManagerID=3</code></pre>
</div>
<p>Non-binding parameters annotated with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter"><code>Core.OptionalParameter</code></a> defined in <a href="#ODataVocCore">OData-VocCore</a> MAY be omitted. If it is annotated and the annotation specifies a <code>DefaultValue</code>, 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.</p>
@@ -2984,18 +2988,18 @@ <h4 id="11551-invoking-an-action"><a id="InvokinganAction" href="#InvokinganActi
<p>Actions without a return type respond with <a href="#ResponseCode204NoContent"><code>204 No Content</code></a> on success.</p>
<p>To request processing of the action only if the binding parameter value, an entity or collection of entities, is unmodified, the client includes the <a href="#HeaderIfMatch"><code>If-Match</code></a> 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 <a href="#HeaderETag"><code>ETag</code></a> header of a collection response.</p>
<div class="example">
-<p>Example 99: invoke the <code>SampleEntities.CreateOrder</code> action using <code>Customers('ALFKI')</code> as the customer (or binding parameter). The values <code>2</code> for the <code>quantity</code> parameter and <code>BLACKFRIDAY</code> for the <code>discountCode</code> parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.</p>
-<div class="sourceCode" id="cb123"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb123-1"><a href="#cb123-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder</span></span>
-<span id="cb123-2"><a href="#cb123-2" aria-hidden="true" tabindex="-1"></a><span class="er">If-Match:</span> <span class="er">W/"MjAxOS0wMy0yMVQxMzowNVo="</span></span>
-<span id="cb123-3"><a href="#cb123-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb123-4"><a href="#cb123-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb123-5"><a href="#cb123-5" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb123-6"><a href="#cb123-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"items"</span><span class="fu">:</span> <span class="ot">[</span></span>
-<span id="cb123-7"><a href="#cb123-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"product"</span><span class="fu">:</span> <span class="dv">4001</span><span class="fu">,</span> <span class="dt">"quantity"</span><span class="fu">:</span> <span class="dv">2</span> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb123-8"><a href="#cb123-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"product"</span><span class="fu">:</span> <span class="dv">7062</span><span class="fu">,</span> <span class="dt">"quantity"</span><span class="fu">:</span> <span class="dv">1</span> <span class="fu">}</span><span class="ot">,</span></span>
-<span id="cb123-9"><a href="#cb123-9" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span><span class="fu">,</span></span>
-<span id="cb123-10"><a href="#cb123-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"discountCode"</span><span class="fu">:</span> <span class="st">"BLACKFRIDAY"</span></span>
-<span id="cb123-11"><a href="#cb123-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+<p>Example 101: invoke the <code>SampleEntities.CreateOrder</code> action using <code>Customers('ALFKI')</code> as the customer (or binding parameter). The values <code>2</code> for the <code>quantity</code> parameter and <code>BLACKFRIDAY</code> for the <code>discountCode</code> parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.</p>
+<div class="sourceCode" id="cb124"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb124-1"><a href="#cb124-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder</span></span>
+<span id="cb124-2"><a href="#cb124-2" aria-hidden="true" tabindex="-1"></a><span class="er">If-Match:</span> <span class="er">W/"MjAxOS0wMy0yMVQxMzowNVo="</span></span>
+<span id="cb124-3"><a href="#cb124-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb124-4"><a href="#cb124-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb124-5"><a href="#cb124-5" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb124-6"><a href="#cb124-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">"items"</span><span class="fu">:</span> <span class="ot">[</span></span>
+<span id="cb124-7"><a href="#cb124-7" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"product"</span><span class="fu">:</span> <span class="dv">4001</span><span class="fu">,</span> <span class="dt">"quantity"</span><span class="fu">:</span> <span class="dv">2</span> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb124-8"><a href="#cb124-8" aria-hidden="true" tabindex="-1"></a> <span class="fu">{</span> <span class="dt">"product"</span><span class="fu">:</span> <span class="dv">7062</span><span class="fu">,</span> <span class="dt">"quantity"</span><span class="fu">:</span> <span class="dv">1</span> <span class="fu">}</span><span class="ot">,</span></span>
+<span id="cb124-9"><a href="#cb124-9" aria-hidden="true" tabindex="-1"></a> <span class="ot">]</span><span class="fu">,</span></span>
+<span id="cb124-10"><a href="#cb124-10" aria-hidden="true" tabindex="-1"></a> <span class="dt">"discountCode"</span><span class="fu">:</span> <span class="st">"BLACKFRIDAY"</span></span>
+<span id="cb124-11"><a href="#cb124-11" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
</div>
</details>
<details open><summary>
@@ -3035,7 +3039,7 @@ <h3 id="1171-batch-request-headers"><a id="BatchRequestHeaders" href="#BatchRequ
</summary>
<p>A batch request using the <a href="#MultipartBatchFormat">multipart batch format</a> MUST contain a <a href="#HeaderContentType"><code>Content-Type</code></a> header specifying a content type of <code>multipart/mixed</code> and a <code>boundary</code> parameter as defined in <a href="#rfc2046">RFC2046</a>.</p>
<div class="example">
-<p>Example 100: multipart batch request</p>
+<p>Example 102: multipart batch request</p>
<pre><code>POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.0
@@ -3045,7 +3049,7 @@ <h3 id="1171-batch-request-headers"><a id="BatchRequestHeaders" href="#BatchRequ
</div>
<p>A batch request using the JSON batch format MUST contain a <code>Content-Type</code> header specifying a content type of <code>application/json</code>.</p>
<div class="example">
-<p>Example 101: JSON batch request</p>
+<p>Example 103: JSON batch request</p>
<pre><code>POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.01
@@ -3072,7 +3076,7 @@ <h3 id="1173-identifying-individual-requests"><a id="IdentifyingIndividualReques
<details open><summary>
<h3 id="1174-referencing-returned-entities"><a id="ReferencingReturnedEntities" href="#ReferencingReturnedEntities">11.7.4 Referencing Returned Entities</a></h3>
</summary>
-<p>Entities created by an <a href="#CreateanEntity">insert</a> request or an <a href="#InvokinganAction">action</a> can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a <code>$</code> character as the first segment of the request URL. Services MUST treat this segment like the URL in the <a href="#HeaderLocation"><code>Location</code></a> header of the response to the request identified by the segment. If the <code>Location</code> 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 <a href="#batchcontentid">example 106</a>.</p>
+<p>Entities created by an <a href="#CreateanEntity">insert</a> request or an <a href="#InvokinganAction">action</a> can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a <code>$</code> character as the first segment of the request URL. Services MUST treat this segment like the URL in the <a href="#HeaderLocation"><code>Location</code></a> header of the response to the request identified by the segment. If the <code>Location</code> 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 <a href="#batchcontentid">example 108</a>.</p>
<p>If the <code>$</code>-prefixed request identifier is identical to the name of a top-level system resource (<code>$batch</code>, <code>$crossjoin</code>, <code>$all</code>, <code>$entity</code>, <code>$root</code>, <code>$id</code>, <code>$metadata</code>, or other system resources defined according to the <a href="#HeaderODataVersion"><code>OData-Version</code></a> 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.</p>
<p>Services MAY also support referencing within request bodies, in which case they SHOULD advertise this support by specifying the <code>ReferencesInRequestBodiesSupported</code> property in the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#BatchSupport"><code>Capabilities.BatchSupport</code></a> term applied to the entity container, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
</details>
@@ -3106,25 +3110,25 @@ <h4 id="11771-multipart-batch-request-body"><a id="MultipartBatchRequestBody" hr
<li>Absolute URI with schema, host, port, and absolute resource path.</li>
</ul>
<div class="example">
-<p>Example 102:</p>
+<p>Example 104:</p>
<pre><code>GET https://host:1234/path/service/People(1) HTTP/1.1</code></pre>
</div>
<ul>
<li>Absolute resource path and separate <code>Host</code> header</li>
</ul>
<div class="example">
-<p>Example <a id="batchhost" href="#batchhost">103</a>:</p>
-<div class="sourceCode" id="cb127"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb127-1"><a href="#cb127-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/path/service/People(1) HTTP/1.1</span></span>
-<span id="cb127-2"><a href="#cb127-2" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">myserver.mydomain.org:1234</span></span>
-<span id="cb127-3"><a href="#cb127-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb127-4"><a href="#cb127-4" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb127-5"><a href="#cb127-5" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Peter"</span> <span class="fu">}</span></span></code></pre></div>
+<p>Example <a id="batchhost" href="#batchhost">105</a>:</p>
+<div class="sourceCode" id="cb128"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb128-1"><a href="#cb128-1" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/path/service/People(1) HTTP/1.1</span></span>
+<span id="cb128-2"><a href="#cb128-2" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">myserver.mydomain.org:1234</span></span>
+<span id="cb128-3"><a href="#cb128-3" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb128-4"><a href="#cb128-4" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb128-5"><a href="#cb128-5" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span> <span class="dt">"Name"</span><span class="fu">:</span> <span class="st">"Peter"</span> <span class="fu">}</span></span></code></pre></div>
</div>
<ul>
<li>Resource path relative to the batch request URI.</li>
</ul>
<div class="example">
-<p>Example 104:</p>
+<p>Example 106:</p>
<pre><code>DELETE People(1) HTTP/1.1</code></pre>
</div>
<p>Services MUST support all three formats for URLs of individual requests.</p>
@@ -3136,7 +3140,7 @@ <h4 id="11771-multipart-batch-request-body"><a id="MultipartBatchRequestBody" hr
</ul>
<p>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.</p>
<div class="example">
-<p>Example <a id="batchRequest" href="#batchRequest">105</a>: a batch request that contains the following individual requests in the order listed</p>
+<p>Example <a id="batchRequest" href="#batchRequest">107</a>: a batch request that contains the following individual requests in the order listed</p>
<ol type="1">
<li>A query request</li>
<li>A change set that contains the following requests:
@@ -3202,7 +3206,7 @@ <h4 id="11772-referencing-new-entities"><a id="ReferencingNewEntities" href="#Re
</summary>
<p>Entities created by an <a href="#CreateanEntity">insert</a> request or an <a href="#InvokinganAction">action</a> 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 <code>ReferencesAcrossChangeSetsSupported</code> property in the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#BatchSupport"><code>Capabilities.BatchSupport</code></a> term applied to the entity container, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
<div class="example">
-<p>Example <a id="batchcontentid" href="#batchcontentid">106</a>: a batch request that contains the following operations in the order listed:</p>
+<p>Example <a id="batchcontentid" href="#batchcontentid">108</a>: a batch request that contains the following operations in the order listed:</p>
<p>A change set that contains the following requests:</p>
<ul>
<li>Insert a new entity (with <code>Content-ID = 1</code>)</li>
@@ -3262,54 +3266,54 @@ <h4 id="11772-referencing-new-entities"><a id="ReferencingNewEntities" href="#Re
…
--changeset_77162fcd-b8da-41ac-a9f8-9357efbbe--
--batch_36522ad7-fc75-4b56-8c71-56071383e77a--</code></pre>
-<p>The second <code>Location</code> URL <code>Orders(1)</code> is relative with its base URI being the second request URL <code>$1/Orders</code>. To get an absolute base URI, the client must replace the <code>$1</code> with the first <code>Location</code> URL <code>Customers('ALFKI')</code> and resolve the resulting URL <code>Customers('ALFKI')/Orders(1)</code> relative to its base URI, which is <code>http://host/service/Customers</code> (determined from the first request URL <code>/service/Customers</code> and the <code>Host: host</code> header as in <a href="#batchhost">example 103</a>). This gives the effective second request URL <code>http://host/service/Customers('ALFKI')/Orders</code> as base URI for the second <code>Location</code> URL, which therefore resolves to <code>http://host/service/Customers('ALFKI')/Orders(1)</code>.</p>
+<p>The second <code>Location</code> URL <code>Orders(1)</code> is relative with its base URI being the second request URL <code>$1/Orders</code>. To get an absolute base URI, the client must replace the <code>$1</code> with the first <code>Location</code> URL <code>Customers('ALFKI')</code> and resolve the resulting URL <code>Customers('ALFKI')/Orders(1)</code> relative to its base URI, which is <code>http://host/service/Customers</code> (determined from the first request URL <code>/service/Customers</code> and the <code>Host: host</code> header as in <a href="#batchhost">example 105</a>). This gives the effective second request URL <code>http://host/service/Customers('ALFKI')/Orders</code> as base URI for the second <code>Location</code> URL, which therefore resolves to <code>http://host/service/Customers('ALFKI')/Orders(1)</code>.</p>
</div>
</details>
<details open><summary>
<h4 id="11773-referencing-an-etag"><a id="ReferencinganETag" href="#ReferencinganETag">11.7.7.3 Referencing an ETag</a></h4>
</summary>
<div class="example">
-<p>Example 107: a batch request that contains the following operations in the order listed:</p>
+<p>Example 109: a batch request that contains the following operations in the order listed:</p>
<ul>
<li>Get an employee (with <code>Content-ID = 1</code>)</li>
<li>Update the salary only if the employee has not changed</li>
</ul>
-<div class="sourceCode" id="cb132"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb132-1"><a href="#cb132-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/service/$batch</span> <span class="er">HTTP/1.1</span></span>
-<span id="cb132-2"><a href="#cb132-2" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
-<span id="cb132-3"><a href="#cb132-3" aria-hidden="true" tabindex="-1"></a><span class="er">OData-Version:</span> <span class="er">4.0</span></span>
-<span id="cb132-4"><a href="#cb132-4" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">multipart/mixed;</span> <span class="er">boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
-<span id="cb132-5"><a href="#cb132-5" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">###</span></span>
-<span id="cb132-6"><a href="#cb132-6" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb132-7"><a href="#cb132-7" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
-<span id="cb132-8"><a href="#cb132-8" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/http</span></span>
-<span id="cb132-9"><a href="#cb132-9" aria-hidden="true" tabindex="-1"></a><span class="er">Content-ID:</span> <span class="er">1</span></span>
-<span id="cb132-10"><a href="#cb132-10" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb132-11"><a href="#cb132-11" aria-hidden="true" tabindex="-1"></a><span class="er">GET</span> <span class="er">/service/Employees(0)</span> <span class="er">HTTP/1.1</span></span>
-<span id="cb132-12"><a href="#cb132-12" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
-<span id="cb132-13"><a href="#cb132-13" aria-hidden="true" tabindex="-1"></a><span class="er">Accept:</span> <span class="er">application/json</span></span>
-<span id="cb132-14"><a href="#cb132-14" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb132-15"><a href="#cb132-15" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb132-16"><a href="#cb132-16" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
-<span id="cb132-17"><a href="#cb132-17" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/http</span></span>
-<span id="cb132-18"><a href="#cb132-18" aria-hidden="true" tabindex="-1"></a><span class="er">Content-ID:</span> <span class="er">2</span></span>
-<span id="cb132-19"><a href="#cb132-19" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb132-20"><a href="#cb132-20" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/service/Employees(0)</span> <span class="er">HTTP/1.1</span></span>
-<span id="cb132-21"><a href="#cb132-21" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
-<span id="cb132-22"><a href="#cb132-22" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
-<span id="cb132-23"><a href="#cb132-23" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">###</span></span>
-<span id="cb132-24"><a href="#cb132-24" aria-hidden="true" tabindex="-1"></a><span class="er">If-Match:</span> <span class="er">$1</span></span>
-<span id="cb132-25"><a href="#cb132-25" aria-hidden="true" tabindex="-1"></a></span>
-<span id="cb132-26"><a href="#cb132-26" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
-<span id="cb132-27"><a href="#cb132-27" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Salary"</span><span class="fu">:</span> <span class="dv">75000</span></span>
-<span id="cb132-28"><a href="#cb132-28" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>
-<span id="cb132-29"><a href="#cb132-29" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b--</span></span></code></pre></div>
+<div class="sourceCode" id="cb133"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb133-1"><a href="#cb133-1" aria-hidden="true" tabindex="-1"></a><span class="er">POST</span> <span class="er">/service/$batch</span> <span class="er">HTTP/1.1</span></span>
+<span id="cb133-2"><a href="#cb133-2" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
+<span id="cb133-3"><a href="#cb133-3" aria-hidden="true" tabindex="-1"></a><span class="er">OData-Version:</span> <span class="er">4.0</span></span>
+<span id="cb133-4"><a href="#cb133-4" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">multipart/mixed;</span> <span class="er">boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
+<span id="cb133-5"><a href="#cb133-5" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">###</span></span>
+<span id="cb133-6"><a href="#cb133-6" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb133-7"><a href="#cb133-7" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
+<span id="cb133-8"><a href="#cb133-8" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/http</span></span>
+<span id="cb133-9"><a href="#cb133-9" aria-hidden="true" tabindex="-1"></a><span class="er">Content-ID:</span> <span class="er">1</span></span>
+<span id="cb133-10"><a href="#cb133-10" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb133-11"><a href="#cb133-11" aria-hidden="true" tabindex="-1"></a><span class="er">GET</span> <span class="er">/service/Employees(0)</span> <span class="er">HTTP/1.1</span></span>
+<span id="cb133-12"><a href="#cb133-12" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
+<span id="cb133-13"><a href="#cb133-13" aria-hidden="true" tabindex="-1"></a><span class="er">Accept:</span> <span class="er">application/json</span></span>
+<span id="cb133-14"><a href="#cb133-14" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb133-15"><a href="#cb133-15" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb133-16"><a href="#cb133-16" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b</span></span>
+<span id="cb133-17"><a href="#cb133-17" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/http</span></span>
+<span id="cb133-18"><a href="#cb133-18" aria-hidden="true" tabindex="-1"></a><span class="er">Content-ID:</span> <span class="er">2</span></span>
+<span id="cb133-19"><a href="#cb133-19" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb133-20"><a href="#cb133-20" aria-hidden="true" tabindex="-1"></a><span class="er">PATCH</span> <span class="er">/service/Employees(0)</span> <span class="er">HTTP/1.1</span></span>
+<span id="cb133-21"><a href="#cb133-21" aria-hidden="true" tabindex="-1"></a><span class="er">Host:</span> <span class="er">host</span></span>
+<span id="cb133-22"><a href="#cb133-22" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Type:</span> <span class="er">application/json</span></span>
+<span id="cb133-23"><a href="#cb133-23" aria-hidden="true" tabindex="-1"></a><span class="er">Content-Length:</span> <span class="er">###</span></span>
+<span id="cb133-24"><a href="#cb133-24" aria-hidden="true" tabindex="-1"></a><span class="er">If-Match:</span> <span class="er">$1</span></span>
+<span id="cb133-25"><a href="#cb133-25" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb133-26"><a href="#cb133-26" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb133-27"><a href="#cb133-27" aria-hidden="true" tabindex="-1"></a> <span class="dt">"Salary"</span><span class="fu">:</span> <span class="dv">75000</span></span>
+<span id="cb133-28"><a href="#cb133-28" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span>
+<span id="cb133-29"><a href="#cb133-29" aria-hidden="true" tabindex="-1"></a><span class="er">--batch_36522ad7-fc75-4b56-8c71-56071383e77b--</span></span></code></pre></div>
</div>
</details>
<details open><summary>
<h4 id="11774-referencing-response-body-values"><a id="ReferencingResponseBodyValues" href="#ReferencingResponseBodyValues">11.7.7.4 Referencing Response Body Values</a></h4>
</summary>
<div class="example">
-<p>Example 108: a batch request that contains the following operations in the order listed:</p>
+<p>Example 110: a batch request that contains the following operations in the order listed:</p>
<ul>
<li>Get an employee (with <code>Content-ID = 1</code>)</li>
<li>Get all employees residing in the same building</li>
@@ -3358,9 +3362,9 @@ <h4 id="11776-multipart-batch-response"><a id="MultipartBatchResponse" href="#Mu
<li><a href="#AsynchronousBatchRequests">Asynchronously processed batch requests</a> can return interim results and end with a <code>202 Accepted</code> as the last part of the multipart response. Therefore, the <a href="#Preferencerespondasync"><code>respond-async</code></a> preference MUST NOT be applied to individual requests within a batch if the batch response is a multipart response.</li>
</ul>
<p>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 <code>Content-ID</code> header with the value of the <code>id</code> name/value pair of the corresponding request object.</p>
-<p>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 <a href="#DataServiceRequests">Data Service Requests</a>. Relative URLs in each individual response are relative to the request URL of the corresponding individual request (see <a href="#batchcontentid">example 106</a>). URLs in responses MUST NOT contain <code>$</code>-prefixed request identifiers.</p>
+<p>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 <a href="#DataServiceRequests">Data Service Requests</a>. Relative URLs in each individual response are relative to the request URL of the corresponding individual request (see <a href="#batchcontentid">example 108</a>). URLs in responses MUST NOT contain <code>$</code>-prefixed request identifiers.</p>
<div class="example">
-<p>Example 109: referencing the batch request <a href="#batchRequest">example 105</a> above, assume all the requests except the final query request succeed. In this case the response would be</p>
+<p>Example 111: referencing the batch request <a href="#batchRequest">example 107</a> above, assume all the requests except the final query request succeed. In this case the response would be</p>
<pre><code>HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
@@ -3414,7 +3418,7 @@ <h4 id="11777-asynchronous-batch-requests"><a id="AsynchronousBatchRequests" hre
<p>A service MAY return interim results to an asynchronously executing batch. It does this by responding with <a href="#ResponseCode200OK"><code>200 OK</code></a> to a <code>GET</code> request to the monitor resource and including a <a href="#ResponseCode202Accepted"><code>202 Accepted</code></a> response as the last part of the multipart response. The client can use the monitor URL returned in this <code>202 Accepted</code> response to continue processing the batch response.</p>
<p>Since a change set is executed atomically, <code>202 Accepted</code> MUST NOT be returned within a change set.</p>
<div class="example">
-<p>Example 110: referencing the <a href="#batchRequest">example 105</a> above again, assume that</p>
+<p>Example 112: referencing the <a href="#batchRequest">example 107</a> above again, assume that</p>
<pre><code>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.
## <a id="Singleton" href="#Singleton">10.4 Singleton</a>
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
+```
+:::
+
## <a id="CollectionofDerivedEntities" href="#CollectionofDerivedEntities">10.5 Collection of Derived Entities</a>
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
+```
+:::
+
## <a id="CollectionofProjectedEntities" href="#CollectionofProjectedEntities">10.7 Collection of Projected Entities</a>
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
## <a id="OperationResult" href="#OperationResult">10.16 Operation Result</a>
-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.
## <a id="allResponse" href="#allResponse">10.19 `$all` Response</a>
@@ -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 <a id="entityWithStreamProperty" href="#entityWithStreamProperty">81</a>: read an entity and select a stream property
+Example <a id="entityWithStreamProperty" href="#entityWithStreamProperty">83</a>: 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
<Function Name="MostRecentOrder" IsBound="true">
@@ -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
<Function Name="Comparison" IsBound="true">
@@ -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 <a id="batchhost" href="#batchhost">103</a>:
+Example <a id="batchhost" href="#batchhost">105</a>:
```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 <a id="batchRequest" href="#batchRequest">105</a>: a batch request that contains the following individual
+Example <a id="batchRequest" href="#batchRequest">107</a>: 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 <a id="batchcontentid" href="#batchcontentid">106</a>: a batch request that contains the following operations in
+Example <a id="batchcontentid" href="#batchcontentid">108</a>: 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(
#### <a id="ReferencinganETag" href="#ReferencinganETag">11.7.7.3 Referencing an ETag</a>
::: 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
#### <a id="ReferencingResponseBodyValues" href="#ReferencingResponseBodyValues">11.7.7.4 Referencing Response Body Values</a>
::: 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 <ralf.handl@sap.com>
Date: Wed, 20 Nov 2024 18:05:34 +0100
Subject: [PATCH 15/19] 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 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/356">356</a></td>
</tr>
<tr class="odd">
+<td>Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) Deep-insert response includes at least the properties present in the request</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/363">363</a></td>
+<td></td>
+</tr>
+<tr class="even">
<td><a href="#UpdateanEntity">Section 11.4.3</a></td>
<td>Services can validate non-updatable property values in update payloads</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/356">356</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#UpsertanEntity">Section 11.4.4</a></td>
<td>Upserts to single-valued non-containment navigation properties</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/455">455</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#UpdateaComplexProperty">Section 11.4.9.3</a></td>
<td>Setting a complex property to a different type</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/534">534</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#ReplaceaCollectionofEntities">Section 11.4.13</a></td>
<td>Semantics of <code>continue-on-error</code> when replacing a collection of entities</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/358">358</a></td>
</tr>
-<tr class="odd">
+<tr class="even">
<td><a href="#Conformance">Section 12</a></td>
<td>Allow <code>400 Bad Request</code> in addition to <code>501 Not Implemented</code> for unsupported functionality</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/391">391</a></td>
</tr>
-<tr class="even">
+<tr class="odd">
<td><a href="#InteroperableODataClients">Section 12.3</a></td>
<td>Encoding of plus character in URLs</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/485">485</a></td>
@@ -2374,7 +2379,7 @@ <h4 id="11422-create-related-entities-when-creating-an-entity"><a id="CreateRela
<p>A request to create an entity that includes related entities, represented using the appropriate inline representation, is referred to as a “deep insert”.</p>
<p>Media entities MUST contain the format-specific representation of their media stream as a virtual property <code>$value</code> when nested within a deep insert.</p>
<p>Each included related entity is processed observing the rules for <a href="#CreateanEntity">creating an entity</a> as if it was posted against the original target URL extended with the navigation path to this related entity.</p>
-<p>On success, the service MUST create all entities and relate them. If the service responds with <a href="#ResponseCode201Created"><code>201 Created</code></a>, the response MUST be expanded to at least the level that was present in the deep-insert request.</p>
+<p>On success, the service MUST create all entities and relate them. If the service responds with <a href="#ResponseCode201Created"><code>201 Created</code></a>, the response MUST be expanded to include at least the entities and properties that were specified in the deep-insert request.</p>
<p>Clients MAY associate an id with individual nested entities in the request by applying the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> term using the namespace or alias defined for the <a href="#ODataVocCore">OData-VocCore</a> vocabulary in the service’s <code>$metadata</code> document. Services that respond with <a href="#ResponseCode201Created"><code>201 Created</code></a> SHOULD annotate the entities in the response using the same <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> value as specified in the request. Services SHOULD advertise support for deep inserts, including support for returning the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a>, through the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepInsertSupport"><code>Capabilities.DeepInsertSupport</code></a> term, defined in <a href="#ODataVocCap">OData-VocCap</a>; services that advertise support through <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepInsertSupport"><code>Capabilities.DeepInsertSupport</code></a> MUST return the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> for the inserted or updated entities.</p>
<p>The <code>continue-on-error</code> preference is not supported for deep insert operations.</p>
<p>On failure, the service MUST NOT create any of the entities.</p>
diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index de6c788d..42bd081a 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -358,6 +358,7 @@ Section | Feature / Change | Issue
[Section 10.2](#CollectionofEntities)| Context URLs use parentheses-style keys without percent-encoding| [368](https://github.com/oasis-tcs/odata-specs/issues/368)
[Section 11.4](#DataModification)| Response code `204 No Content` after successful data modification if requested response could not be constructed| [443](https://github.com/oasis-tcs/odata-specs/issues/443)
[Section 11.4.2](#CreateanEntity)| Services can validate non-insertable property values in insert payloads| [356](https://github.com/oasis-tcs/odata-specs/issues/356)
+|Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) Deep-insert response includes at least the properties present in the request| [363](https://github.com/oasis-tcs/odata-specs/issues/363)
[Section 11.4.3](#UpdateanEntity)| Services can validate non-updatable property values in update payloads| [356](https://github.com/oasis-tcs/odata-specs/issues/356)
[Section 11.4.4](#UpsertanEntity)| Upserts to single-valued non-containment navigation properties| [455](https://github.com/oasis-tcs/odata-specs/issues/455)
[Section 11.4.9.3](#UpdateaComplexProperty)| Setting a complex property to a different type| [534](https://github.com/oasis-tcs/odata-specs/issues/534)
@@ -4300,8 +4301,7 @@ original target URL extended with the navigation path to this related
entity.
On success, the service MUST create all entities and relate them. If the
-service responds with [`201 Created`](#ResponseCode201Created), the response MUST be expanded to at
-least the level that was present in the deep-insert request.
+service responds with [`201 Created`](#ResponseCode201Created), the response MUST be expanded to include at least the entities and properties that were specified in the deep-insert request.
Clients MAY associate an id with individual nested entities in the
request by applying the
diff --git a/odata-protocol/1 Introduction.md b/odata-protocol/1 Introduction.md
index b43b3c1c..f1dc9565 100644
--- a/odata-protocol/1 Introduction.md
+++ b/odata-protocol/1 Introduction.md
@@ -36,6 +36,9 @@ Response code `204 No Content` after successful data modification if requested r
[Section ##CreateanEntity]|
Services can validate non-insertable property values in insert payloads|
[356](https://github.com/oasis-tcs/odata-specs/issues/356)
+|Section ##CreateRelatedEntitiesWhenCreatinganEntity]
+Deep-insert response includes at least the properties present in the request|
+[363](https://github.com/oasis-tcs/odata-specs/issues/363)
[Section ##UpdateanEntity]|
Services can validate non-updatable property values in update payloads|
[356](https://github.com/oasis-tcs/odata-specs/issues/356)
diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md
index 67be5abc..8ee964bd 100644
--- a/odata-protocol/11.4 Data Modification.md
+++ b/odata-protocol/11.4 Data Modification.md
@@ -285,8 +285,8 @@ original target URL extended with the navigation path to this related
entity.
On success, the service MUST create all entities and relate them. If the
-service responds with [`201 Created`](#ResponseCode201Created), the response MUST be expanded to at
-least the level that was present in the deep-insert request.
+service responds with [`201 Created`](#ResponseCode201Created), the response MUST be expanded to
+include at least the entities and properties that were specified in the deep-insert request.
Clients MAY associate an id with individual nested entities in the
request by applying the
From ff14732045e46423b0752921e720d46b13827c5c Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 26 Nov 2024 09:46:02 +0100
Subject: [PATCH 16/19] Bump cross-spawn from 7.0.3 to 7.0.6 (#2032)
Bumps [cross-spawn](https://github.com/moxystudio/node-cross-spawn) from
7.0.3 to 7.0.6.
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/moxystudio/node-cross-spawn/blob/master/CHANGELOG.md">cross-spawn's
changelog</a>.</em></p>
<blockquote>
<h3><a
href="https://github.com/moxystudio/node-cross-spawn/compare/v7.0.5...v7.0.6">7.0.6</a>
(2024-11-18)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>update cross-spawn version to 7.0.5 in package-lock.json (<a
href="https://github.com/moxystudio/node-cross-spawn/commit/f700743918d901eff92960e15a8dd68f87bd4176">f700743</a>)</li>
</ul>
<h3><a
href="https://github.com/moxystudio/node-cross-spawn/compare/v7.0.4...v7.0.5">7.0.5</a>
(2024-11-07)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>fix escaping bug introduced by backtracking (<a
href="https://github.com/moxystudio/node-cross-spawn/commit/640d391fde65388548601d95abedccc12943374f">640d391</a>)</li>
</ul>
<h3><a
href="https://github.com/moxystudio/node-cross-spawn/compare/v7.0.3...v7.0.4">7.0.4</a>
(2024-11-07)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>disable regexp backtracking (<a
href="https://redirect.github.com/moxystudio/node-cross-spawn/issues/160">#160</a>)
(<a
href="https://github.com/moxystudio/node-cross-spawn/commit/5ff3a07d9add449021d806e45c4168203aa833ff">5ff3a07</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/77cd97f3ca7b62c904a63a698fc4a79bf41977d0"><code>77cd97f</code></a>
chore(release): 7.0.6</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/6717de49ff1e5de49622488dcb9c33fb25370c85"><code>6717de4</code></a>
chore: upgrade standard-version</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/f700743918d901eff92960e15a8dd68f87bd4176"><code>f700743</code></a>
fix: update cross-spawn version to 7.0.5 in package-lock.json</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/9a7e3b2165917367f74b8365faad9873b30d7263"><code>9a7e3b2</code></a>
chore: fix build status badge</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/085268352dcbcad8064c64c5efb25268b4023184"><code>0852683</code></a>
chore(release): 7.0.5</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/640d391fde65388548601d95abedccc12943374f"><code>640d391</code></a>
fix: fix escaping bug introduced by backtracking</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/bff0c87c8b627c4e6d04ec2449e733048bebb464"><code>bff0c87</code></a>
chore: remove codecov</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/a7c6abc6fee79641d45b452fe6217deaa1bd0973"><code>a7c6abc</code></a>
chore: replace travis with github workflows</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/9b9246e0969e86656d7ccd527716bc3c18842a19"><code>9b9246e</code></a>
chore(release): 7.0.4</li>
<li><a
href="https://github.com/moxystudio/node-cross-spawn/commit/5ff3a07d9add449021d806e45c4168203aa833ff"><code>5ff3a07</code></a>
fix: disable regexp backtracking (<a
href="https://redirect.github.com/moxystudio/node-cross-spawn/issues/160">#160</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/moxystudio/node-cross-spawn/compare/v7.0.3...v7.0.6">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
You can disable automated security fix PRs for this repo from the
[Security Alerts
page](https://github.com/oasis-tcs/odata-specs/network/alerts).
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
package-lock.json | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/package-lock.json b/package-lock.json
index 791d70a2..d597c57d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1073,9 +1073,10 @@
}
},
"node_modules/cross-spawn": {
- "version": "7.0.3",
- "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz",
- "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==",
+ "version": "7.0.6",
+ "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+ "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+ "license": "MIT",
"dependencies": {
"path-key": "^3.1.0",
"shebang-command": "^2.0.0",
From 42b5c0dfd25d7fbfdabe2a7274ea62b3d00741cb Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 9 Dec 2024 13:10:50 +0100
Subject: [PATCH 17/19] Bump path-to-regexp and express (#2037)
---
package-lock.json | 18 +++++++++++-------
1 file changed, 11 insertions(+), 7 deletions(-)
diff --git a/package-lock.json b/package-lock.json
index d597c57d..db62351e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1353,9 +1353,9 @@
}
},
"node_modules/express": {
- "version": "4.21.1",
- "resolved": "https://registry.npmjs.org/express/-/express-4.21.1.tgz",
- "integrity": "sha512-YSFlK1Ee0/GC8QaO91tHcDxJiE/X4FbpAyQWkxAvG6AXCuR65YzK8ua6D9hvi/TzUfZMpc+BwuM1IPw8fmQBiQ==",
+ "version": "4.21.2",
+ "resolved": "https://registry.npmjs.org/express/-/express-4.21.2.tgz",
+ "integrity": "sha512-28HqgMZAmih1Czt9ny7qr6ek2qddF4FclbMzwhCREB6OFfH+rXAnuNCwo1/wFvrtbgsQDb4kSbX9de9lFbrXnA==",
"license": "MIT",
"dependencies": {
"accepts": "~1.3.8",
@@ -1377,7 +1377,7 @@
"methods": "~1.1.2",
"on-finished": "2.4.1",
"parseurl": "~1.3.3",
- "path-to-regexp": "0.1.10",
+ "path-to-regexp": "0.1.12",
"proxy-addr": "~2.0.7",
"qs": "6.13.0",
"range-parser": "~1.2.1",
@@ -1392,6 +1392,10 @@
},
"engines": {
"node": ">= 0.10.0"
+ },
+ "funding": {
+ "type": "opencollective",
+ "url": "https://opencollective.com/express"
}
},
"node_modules/extract-zip": {
@@ -2711,9 +2715,9 @@
}
},
"node_modules/path-to-regexp": {
- "version": "0.1.10",
- "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.10.tgz",
- "integrity": "sha512-7lf7qcQidTku0Gu3YDPc8DJ1q7OOucfa/BSsIwjuh56VU7katFvuM8hULfkwB3Fns/rsVF7PwPKVw1sl5KQS9w==",
+ "version": "0.1.12",
+ "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.12.tgz",
+ "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==",
"license": "MIT"
},
"node_modules/pend": {
From c94f42448dc37488c8cb8a5821e8ee73778be04a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Wed, 11 Dec 2024 09:00:05 +0100
Subject: [PATCH 18/19] Bump nanoid and mocha (#2039)
---
package-lock.json | 145 ++++++++++++++++++++--------------------------
package.json | 2 +-
2 files changed, 63 insertions(+), 84 deletions(-)
diff --git a/package-lock.json b/package-lock.json
index db62351e..69e5eb1b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -13,7 +13,7 @@
"c8": "^8.0.0",
"express": "^4",
"js-yaml": "^4.1.0",
- "mocha": "^10.2.0",
+ "mocha": "^10.8.2",
"pandoc-filter": "^2.2.0",
"puppeteer": "^22.14.0"
},
@@ -429,9 +429,9 @@
"license": "MIT"
},
"node_modules/ansi-colors": {
- "version": "4.1.1",
- "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.1.tgz",
- "integrity": "sha512-JoX0apGbHaUJBNl6yF+p6JAFYZ666/hhCGKN5t9QFjbJQKUU/g8MNbFDbvfrgKXvI1QpZplPOnwIo99lX/AAmA==",
+ "version": "4.1.3",
+ "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.3.tgz",
+ "integrity": "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==",
"engines": {
"node": ">=6"
}
@@ -1172,9 +1172,9 @@
"license": "BSD-3-Clause"
},
"node_modules/diff": {
- "version": "5.0.0",
- "resolved": "https://registry.npmjs.org/diff/-/diff-5.0.0.tgz",
- "integrity": "sha512-/VTCrvm5Z0JGty/BWHljh+BAiw3IK+2j87NGMu8Nwc/f48WoDAC395uomO9ZD117ZOBaHmkX1oyLvkVM/aIT3w==",
+ "version": "5.2.0",
+ "resolved": "https://registry.npmjs.org/diff/-/diff-5.2.0.tgz",
+ "integrity": "sha512-uIFDxqpRZGZ6ThOk84hEfqWoHx2devRFvpTZcTHur85vImfaxUbTW9Ryh4CpCuDnToOP1CEtXKIgytHBPVff5A==",
"engines": {
"node": ">=0.3.1"
}
@@ -2345,9 +2345,9 @@
}
},
"node_modules/minimatch": {
- "version": "5.0.1",
- "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.0.1.tgz",
- "integrity": "sha512-nLDxIFRyhDblz3qMuq+SoRZED4+miJ/G+tdDrjkkkRnjAsBexeGpgjLEQ0blJy7rHhR2b93rhQY4SvyWu9v03g==",
+ "version": "5.1.6",
+ "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.6.tgz",
+ "integrity": "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==",
"dependencies": {
"brace-expansion": "^2.0.1"
},
@@ -2370,31 +2370,30 @@
"license": "MIT"
},
"node_modules/mocha": {
- "version": "10.2.0",
- "resolved": "https://registry.npmjs.org/mocha/-/mocha-10.2.0.tgz",
- "integrity": "sha512-IDY7fl/BecMwFHzoqF2sg/SHHANeBoMMXFlS9r0OXKDssYE1M5O43wUY/9BVPeIvfH2zmEbBfseqN9gBQZzXkg==",
- "dependencies": {
- "ansi-colors": "4.1.1",
- "browser-stdout": "1.3.1",
- "chokidar": "3.5.3",
- "debug": "4.3.4",
- "diff": "5.0.0",
- "escape-string-regexp": "4.0.0",
- "find-up": "5.0.0",
- "glob": "7.2.0",
- "he": "1.2.0",
- "js-yaml": "4.1.0",
- "log-symbols": "4.1.0",
- "minimatch": "5.0.1",
- "ms": "2.1.3",
- "nanoid": "3.3.3",
- "serialize-javascript": "6.0.0",
- "strip-json-comments": "3.1.1",
- "supports-color": "8.1.1",
- "workerpool": "6.2.1",
- "yargs": "16.2.0",
- "yargs-parser": "20.2.4",
- "yargs-unparser": "2.0.0"
+ "version": "10.8.2",
+ "resolved": "https://registry.npmjs.org/mocha/-/mocha-10.8.2.tgz",
+ "integrity": "sha512-VZlYo/WE8t1tstuRmqgeyBgCbJc/lEdopaa+axcKzTBJ+UIdlAB9XnmvTCAH4pwR4ElNInaedhEBmZD8iCSVEg==",
+ "dependencies": {
+ "ansi-colors": "^4.1.3",
+ "browser-stdout": "^1.3.1",
+ "chokidar": "^3.5.3",
+ "debug": "^4.3.5",
+ "diff": "^5.2.0",
+ "escape-string-regexp": "^4.0.0",
+ "find-up": "^5.0.0",
+ "glob": "^8.1.0",
+ "he": "^1.2.0",
+ "js-yaml": "^4.1.0",
+ "log-symbols": "^4.1.0",
+ "minimatch": "^5.1.6",
+ "ms": "^2.1.3",
+ "serialize-javascript": "^6.0.2",
+ "strip-json-comments": "^3.1.1",
+ "supports-color": "^8.1.1",
+ "workerpool": "^6.5.1",
+ "yargs": "^16.2.0",
+ "yargs-parser": "^20.2.9",
+ "yargs-unparser": "^2.0.0"
},
"bin": {
"_mocha": "bin/_mocha",
@@ -2402,18 +2401,14 @@
},
"engines": {
"node": ">= 14.0.0"
- },
- "funding": {
- "type": "opencollective",
- "url": "https://opencollective.com/mochajs"
}
},
"node_modules/mocha/node_modules/debug": {
- "version": "4.3.4",
- "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz",
- "integrity": "sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==",
+ "version": "4.4.0",
+ "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.0.tgz",
+ "integrity": "sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA==",
"dependencies": {
- "ms": "2.1.2"
+ "ms": "^2.1.3"
},
"engines": {
"node": ">=6.0"
@@ -2424,10 +2419,24 @@
}
}
},
- "node_modules/mocha/node_modules/debug/node_modules/ms": {
- "version": "2.1.2",
- "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
- "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w=="
+ "node_modules/mocha/node_modules/glob": {
+ "version": "8.1.0",
+ "resolved": "https://registry.npmjs.org/glob/-/glob-8.1.0.tgz",
+ "integrity": "sha512-r8hpEjiQEYlF2QU0df3dS+nxxSIreXQS1qRhMJM0Q5NDdR386C7jb7Hwwod8Fgiuex+k0GFjgft18yvxm5XoCQ==",
+ "deprecated": "Glob versions prior to v9 are no longer supported",
+ "dependencies": {
+ "fs.realpath": "^1.0.0",
+ "inflight": "^1.0.4",
+ "inherits": "2",
+ "minimatch": "^5.0.1",
+ "once": "^1.3.0"
+ },
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/isaacs"
+ }
},
"node_modules/mocha/node_modules/ms": {
"version": "2.1.3",
@@ -2448,31 +2457,12 @@
"url": "https://github.com/chalk/supports-color?sponsor=1"
}
},
- "node_modules/mocha/node_modules/yargs-parser": {
- "version": "20.2.4",
- "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.4.tgz",
- "integrity": "sha512-WOkpgNhPTlE73h4VFAFsOnomJVaovO8VqLDzy5saChRBFQFBoMYirowyW+Q9HB4HFF4Z7VZTiG3iSzJJA29yRA==",
- "engines": {
- "node": ">=10"
- }
- },
"node_modules/ms": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz",
"integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==",
"license": "MIT"
},
- "node_modules/nanoid": {
- "version": "3.3.3",
- "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.3.tgz",
- "integrity": "sha512-p1sjXuopFs0xg+fPASzQ28agW1oHD7xDsd9Xkf3T15H3c/cifrFHVwrh74PdoklAPi+i7MdRsE47vm2r6JoB+w==",
- "bin": {
- "nanoid": "bin/nanoid.cjs"
- },
- "engines": {
- "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
- }
- },
"node_modules/negotiator": {
"version": "0.6.3",
"resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz",
@@ -2990,17 +2980,6 @@
"minimatch": "^5.1.0"
}
},
- "node_modules/readdir-glob/node_modules/minimatch": {
- "version": "5.1.6",
- "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.6.tgz",
- "integrity": "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==",
- "dependencies": {
- "brace-expansion": "^2.0.1"
- },
- "engines": {
- "node": ">=10"
- }
- },
"node_modules/readdirp": {
"version": "3.6.0",
"resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz",
@@ -3119,9 +3098,9 @@
"license": "MIT"
},
"node_modules/serialize-javascript": {
- "version": "6.0.0",
- "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-6.0.0.tgz",
- "integrity": "sha512-Qr3TosvguFt8ePWqsvRfrKyQXIiW+nGbYpy8XK24NQHE83caxWt+mIymTT19DGFbNWNLfEwsrkSmN64lVWB9ag==",
+ "version": "6.0.2",
+ "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-6.0.2.tgz",
+ "integrity": "sha512-Saa1xPByTTq2gdeFZYLLo+RFE35NHZkAbqZeWNd3BpzppeVisAqpDjcp8dyf6uIvEqJRd46jemmyA4iFIeVk8g==",
"dependencies": {
"randombytes": "^2.1.0"
}
@@ -3588,9 +3567,9 @@
}
},
"node_modules/workerpool": {
- "version": "6.2.1",
- "resolved": "https://registry.npmjs.org/workerpool/-/workerpool-6.2.1.tgz",
- "integrity": "sha512-ILEIE97kDZvF9Wb9f6h5aXK4swSlKGUcOEGiIYb2OOu/IrDU9iwj0fD//SsA6E5ibwJxpEvhullJY4Sl4GcpAw=="
+ "version": "6.5.1",
+ "resolved": "https://registry.npmjs.org/workerpool/-/workerpool-6.5.1.tgz",
+ "integrity": "sha512-Fs4dNYcsdpYSAfVxhnl1L5zTksjvOJxtC5hzMNl+1t9B8hTJTdKDyZ5ju7ztgPy+ft9tBFXoOlDNiOT9WUXZlA=="
},
"node_modules/wrap-ansi": {
"version": "7.0.0",
diff --git a/package.json b/package.json
index acb45b76..3de225e9 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
"c8": "^8.0.0",
"express": "^4",
"js-yaml": "^4.1.0",
- "mocha": "^10.2.0",
+ "mocha": "^10.8.2",
"pandoc-filter": "^2.2.0",
"puppeteer": "^22.14.0"
},
From 5bade310669f02f705a34541cca941a7dd79064d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= <heiko.theissen@sap.com>
Date: Wed, 8 Jan 2025 17:32:05 +0100
Subject: [PATCH 19/19] Simple grouping with untyped properties or open types
(#2034)
In the simple grouping algorithm, the last sub-bullet point of the
projection function says:
> Otherwise, if $p'$ is a prefix of a path in $G$, let $v[q]=s_G
(u[q],p')$
and the recursively called function $s_G$ assumes that its first
argument is a structured instance. But if $q$ is an untyped property or
a property of an open type, $u[q]$ can also be primitive<sup>1</sup>,
and then the first bullet point does not make sense:
> Let $v$ be an instance of the type of $u$ without properties and
without entity-id.
I suggest to rephrase the last sub-bullet point so that the recursive
call is omitted in such cases. This is the least invasive change and its
leads to $q$ being omitted from the projection.
<sup>1</sup> Of course $u[q]$ can also be primitive if $q$ declares a
primitive type, but the problem occurs only if $p'$ is a prefix of a
path in $G$, which means for a grouping criterion of the form $q/r$ or
$s/q/r$. And if $q$ declares a primitive type, $q/r$ does not make sense
at all.
---
docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html | 2 +-
docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md | 2 +-
odata-data-aggregation-ext/3.2 Basic Aggregation.md | 2 +-
3 files changed, 3 insertions(+), 3 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 c9d45241..fdd665fe 100644
--- a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html
+++ b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.html
@@ -1981,7 +1981,7 @@ <h4 id="3231-simple-grouping"><a id="SimpleGrouping" href="#SimpleGrouping">3.2.
<ul>
<li>If <span class="math inline">\(u\)</span> has a subtype of the type addressed by <span class="math inline">\(p\)</span> and <span class="math inline">\(q\)</span> is only declared on that subtype, let <span class="math inline">\(p'=p/p''/q\)</span> where <span class="math inline">\(p''\)</span> is a type-cast to the subtype, otherwise let <span class="math inline">\(p'=p/q\)</span>.</li>
<li>If <span class="math inline">\(p'\)</span> occurs in <span class="math inline">\(G\)</span>, let <span class="math inline">\(v[q]=u[q]\)</span>.</li>
-<li>Otherwise, if <span class="math inline">\(p'\)</span> is a prefix of a path in <span class="math inline">\(G\)</span>, let <span class="math inline">\(v[q]=s_G(u[q],p')\)</span>.</li>
+<li>Otherwise, if <span class="math inline">\(p'\)</span> is a prefix of a path in <span class="math inline">\(G\)</span> and <span class="math inline">\(u[q]\)</span> has a structured type, let <span class="math inline">\(v[q]=s_G(u[q],p')\)</span>.</li>
</ul></li>
<li>Return <span class="math inline">\(v\)</span>.</li>
</ul></li>
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 7c9ac06b..5f220079 100644
--- a/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md
+++ b/docs/odata-data-aggregation-ext/odata-data-aggregation-ext.md
@@ -1461,7 +1461,7 @@ The output set of the `groupby` transformation is constructed in five steps.
- For each structural or navigation property $q$ of $u$:
- If $u$ has a subtype of the type addressed by $p$ and $q$ is only declared on that subtype, let $p'=p/p''/q$ where $p''$ is a type-cast to the subtype, otherwise let $p'=p/q$.
- If $p'$ occurs in $G$, let $v[q]=u[q]$.
- - Otherwise, if $p'$ is a prefix of a path in $G$, let $v[q]=s_G(u[q],p')$.
+ - Otherwise, if $p'$ is a prefix of a path in $G$ and $u[q]$ has a structured type, let $v[q]=s_G(u[q],p')$.
- Return $v$.
2. The input set is split into subsets where two instances are in the same subset if their projections are [the same](#SamenessandOrder). If [representations of the same non-transient entity](#SamenessandOrder) are encountered during the comparison of two projections, the service MUST assign them to one subset with the merged representation if they are complementary and MUST reject the request if they are contradictory.
3. The set transformations from the second parameter are applied to each subset, resulting in a new set of potentially different structure and cardinality. Associated with each resulting set is the common projection of the instances in the subset from which the resulting set was computed.
diff --git a/odata-data-aggregation-ext/3.2 Basic Aggregation.md b/odata-data-aggregation-ext/3.2 Basic Aggregation.md
index 0fbc63be..14a73416 100644
--- a/odata-data-aggregation-ext/3.2 Basic Aggregation.md
+++ b/odata-data-aggregation-ext/3.2 Basic Aggregation.md
@@ -350,7 +350,7 @@ The output set of the `groupby` transformation is constructed in five steps.
- For each structural or navigation property $q$ of $u$:
- If $u$ has a subtype of the type addressed by $p$ and $q$ is only declared on that subtype, let $p'=p/p''/q$ where $p''$ is a type-cast to the subtype, otherwise let $p'=p/q$.
- If $p'$ occurs in $G$, let $v[q]=u[q]$.
- - Otherwise, if $p'$ is a prefix of a path in $G$, let $v[q]=s_G(u[q],p')$.
+ - Otherwise, if $p'$ is a prefix of a path in $G$ and $u[q]$ has a structured type, let $v[q]=s_G(u[q],p')$.
- Return $v$.
2. The input set is split into subsets where two instances are in the same subset if their projections are [the same](#SamenessandOrder). If [representations of the same non-transient entity](#SamenessandOrder) are encountered during the comparison of two projections, the service MUST assign them to one subset with the merged representation if they are complementary and MUST reject the request if they are contradictory.
3. The set transformations from the second parameter are applied to each subset, resulting in a new set of potentially different structure and cardinality. Associated with each resulting set is the common projection of the instances in the subset from which the resulting set was computed.