Merge branch 'main' into 1973/put-navprop

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">&quot;TopSellingProducts&quot;:</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,14 +4383,17 @@ <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>
 <li><a href="#Name.14.1"><code>$Name</code></a></li>
 <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>

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)