Add description of Core.IsDelta to ReturnType and Parameter

Add description of Core.OptionalParameter to Parameter
Add, to introduction, that functions and actions can take, and return, delta payloads

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>
@@ -2004,7 +2009,10 @@ <h3><a id="Type.13.5" href="#Type.13.5"><code>$Type</code></a> and <a id="Collec
 <p>For single-valued return types the value of <code>$Type</code> is the qualified name of the returned type.</p>
 <p>For collection-valued return types the value of <code>$Type</code> is the qualified name of the returned item type, and the member <code>$Collection</code> MUST be present with the literal value <code>true</code>.</p>
 <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>
+<h3><a id="AnnotationCoreIsDelta.13.7" href="#AnnotationCoreIsDelta.13.7">Annotation <code>Core.IsDelta</code></a></h3>
+<p>The <code>$ReturnType</code> of a function or action that returns results as a delta payload is annotated 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 entries as well as changes to related entities and relationships, according to the format-specific delta representation.</p>
+<h3><a id="Nullable.13.8" href="#Nullable.13.8"><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>
@@ -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>
@@ -2032,10 +2040,16 @@ <h3><a id="Type.14.2" href="#Type.14.2"><code>$Type</code></a> and <a id="Collec
 <p>For single-valued parameters the value of <code>$Type</code> is the qualified name of the accepted type.</p>
 <p>For collection-valued parameters the value of <code>$Type</code> is the qualified name of the accepted item type, and the member <code>$Collection</code> MUST be present with the literal value <code>true</code>.</p>
 <p>Absence of the <code>$Type</code> member means the type is <code>Edm.String</code>.</p>
-<h3><a id="Nullable.14.4" href="#Nullable.14.4"><code>$Nullable</code></a></h3>
+<h3><a id="AnnotationCoreIsDelta.14.4" href="#AnnotationCoreIsDelta.14.4">Annotation <code>Core.IsDelta</code></a></h3>
+<p>A <code>$Parameter</code> that accepts a delta payload is annotated 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 entries as well as changes to related entities and relationships, according to the format-specific delta representation.</p>
+<h3><a id="Nullable.14.5" href="#Nullable.14.5"><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>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>
+<h3><a id="AnnotationCoreOptionalParameter.14.6" href="#AnnotationCoreOptionalParameter.14.6">Annotation <code>Core.OptionalParameter</code></a></h3>
+<p>A <code>$Parameter</code> object 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>
 <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>
@@ -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>
@@ -4368,15 +4382,18 @@ <h1 id="appendix-b-table-of-json-objects-and-members"><a id="TableofJSONObjectsa
 <li><a href="#ReturnType.13.4"><code>$ReturnType</code></a></li>
 <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.7">Annotation <code>Core.IsDelta</code></a></li>
+<li><a href="#Nullable.13.8"><code>$Nullable</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="#AnnotationCoreIsDelta.14.4">Annotation <code>Core.IsDelta</code></a></li>
+<li><a href="#Nullable.14.5"><code>$Nullable</code></a></li>
+<li><a href="#AnnotationCoreOptionalParameter.14.6">Annotation <code>Core.OptionalParameter</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)
@@ -2889,7 +2890,15 @@ present with the literal value `true`.
 
 Absence of the `$Type` member means the type is `Edm.String`.
 
-### <a id="Nullable.13.7" href="#Nullable.13.7">`$Nullable`</a>
+### <a id="AnnotationCoreIsDelta.13.7" href="#AnnotationCoreIsDelta.13.7">Annotation `Core.IsDelta`</a>
+
+The `$ReturnType` of a function or action that returns results as a delta payload
+is annotated 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 entries as well as changes to related entities and relationships, according to the format-specific delta representation.
+
+### <a id="Nullable.13.8" href="#Nullable.13.8">`$Nullable`</a>
 
 The value of `$Nullable` is one of the Boolean literals `true` or
 `false`. Absence of the member means `false`.
@@ -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.
@@ -2963,7 +2972,15 @@ present with the literal value `true`.
 
 Absence of the `$Type` member means the type is `Edm.String`.
 
-### <a id="Nullable.14.4" href="#Nullable.14.4">`$Nullable`</a>
+### <a id="AnnotationCoreIsDelta.14.4" href="#AnnotationCoreIsDelta.14.4">Annotation `Core.IsDelta`</a>
+
+A `$Parameter` that accepts a delta payload
+is annotated 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 entries as well as changes to related entities and relationships, according to the format-specific delta representation.
+
+### <a id="Nullable.14.5" href="#Nullable.14.5">`$Nullable`</a>
 
 The value of `$Nullable` is one of the Boolean literals `true` or
 `false`. Absence of the member means `false`.
@@ -2975,6 +2992,12 @@ For collection-valued parameters the parameter value will always be a
 collection that MAY be empty. In this case `$Nullable` applies to items
 of the collection and specifies whether the collection MAY contain
 `null` values.
+
+### <a id="AnnotationCoreOptionalParameter.14.6" href="#AnnotationCoreOptionalParameter.14.6">Annotation `Core.OptionalParameter`</a>
+A `$Parameter` object 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}
@@ -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
@@ -6214,13 +6237,16 @@ https://openui5.hana.ondemand.com/topic/87aac894a40640f89920d7b2a414499b.
   - [`$ReturnType`](#ReturnType.13.4)
   - [`$Type`](#Type.13.5)
   - [`$Collection`](#Collection.13.6)
-  - [`$Nullable`](#Nullable.13.7)
-  - [`$Parameter`](#Parameter.13.8)
+  - [Annotation `Core.IsDelta`](#AnnotationCoreIsDelta.13.7)
+  - [`$Nullable`](#Nullable.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.IsDelta`](#AnnotationCoreIsDelta.14.4)
+  - [`$Nullable`](#Nullable.14.5)
+  - [Annotation `Core.OptionalParameter`](#AnnotationCoreOptionalParameter.14.6)
 - [Entity Container Object](#EntityContainerObject.15)
   - [`$Extends`](#Extends.15.1)
 - [Entity Set Object](#EntitySetObject.16)