Omission of collection-valued parameters/properties

docs/odata-csdl-xml/odata-csdl-xml.html

@@ -1934,7 +1934,8 @@ <h3><a id="AttributeType.23.2" href="#AttributeType.23.2">Attribute <code>Type</
 <p>For collection-valued parameters the value of <code>Type</code> is the character sequence <code>Collection(</code> followed by the qualified name of the parameter’s type, followed by a closing parenthesis <code>)</code>.</p>
 <h3><a id="AttributeNullable.23.3" href="#AttributeNullable.23.3">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>The value <code>true</code> means that the parameter accepts a <code>null</code> value.</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>
 </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>

docs/odata-csdl-xml/odata-csdl-xml.md

@@ -2846,7 +2846,13 @@ 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`.
 
-The value `true` means that the parameter accepts a `null` value.
+For single-valued parameters the value `true` means that the parameter
+accepts a `null` value.
+
+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.23.4" href="#AnnotationCoreOptionalParameter.23.4">Annotation `Core.OptionalParameter`</a>

docs/odata-json-format/odata-json-format.html

@@ -413,6 +413,11 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
 <td>Allow common expressions in action payloads</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/341">341</a></td>
 </tr>
+<tr class="even">
+<td><a href="#ActionInvocation">Section 18</a></td>
+<td>Omission of collection-valued action parameters</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/2045">2045</a></td>
+</tr>
 </tbody>
 </table>
 </details>
@@ -2098,7 +2103,8 @@ <h1 id="18-action-invocation"><a id="ActionInvocation" href="#ActionInvocation">
 <span id="cb60-10"><a href="#cb60-10" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
 </div>
 <p>Inside a batch request the common expressions can also be value references starting with <code>$</code>, as introduced in <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ReferencingValuesfromResponseBodies">OData-Protocol, section 11.7.6</a>.</p>
-<p>Non-binding parameters that are nullable or 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 from the request body. If an omitted parameter is not annotated (and thus nullable), it MUST be interpreted as having the <code>null</code> value. 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. Note: a nullable non-binding parameter is equivalent to being annotated as optional with a default value of <code>null</code>.</p>
+<p>Non-binding single-valued parameters that are nullable or 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 from the request body. If an omitted single-valued parameter is not annotated (and thus nullable), it MUST be interpreted as having the <code>null</code> value. 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. Note: a nullable non-binding parameter is equivalent to being annotated as optional with a default value of <code>null</code>.</p>
+<p>Non-binding collection-valued parameters MAY be omitted from the request body regardless of nullability or optionality. The interpretation of such an omitted parameter is up to the service, possible interpretations include assuming an empty collection or, for parameters not annotated as <code>Core.OptionalParameter</code>, reporting an error.</p>
 <div class="example">
 <p>Example 54:</p>
 <div class="sourceCode" id="cb61"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb61-1"><a href="#cb61-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>

docs/odata-json-format/odata-json-format.md

@@ -223,6 +223,7 @@ Section | Feature / Change | Issue
 [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)
+[Section 18](#ActionInvocation)| Omission of collection-valued action parameters| [2045](https://github.com/oasis-tcs/odata-specs/issues/2045)
 
 ## <a id="Glossary" href="#Glossary">1.2 Glossary</a>
 
@@ -3148,10 +3149,10 @@ Content-Type: application/json
 Inside a batch request the common expressions can also be value references
 starting with `$`, as introduced in [OData-Protocol, section 11.7.6](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#ReferencingValuesfromResponseBodies).
 
-Non-binding parameters that are nullable or annotated with the term
+Non-binding single-valued parameters that are nullable or annotated with the term
 [`Core.OptionalParameter`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter) defined in
 [OData-VocCore](#ODataVocCore) MAY be omitted from the request body.
-If an omitted parameter is not annotated (and thus nullable), it MUST be
+If an omitted single-valued parameter is not annotated (and thus nullable), it MUST be
 interpreted as having the `null` value. If it is annotated
 and the annotation specifies a `DefaultValue`, the omitted
 parameter is interpreted as having that default value. If omitted and
@@ -3160,6 +3161,11 @@ how to interpret the omitted parameter. Note: a nullable non-binding
 parameter is equivalent to being annotated as optional with a default
 value of `null`.
 
+Non-binding collection-valued parameters MAY be omitted from the request body regardless
+of nullability or optionality. The interpretation of such an omitted parameter is up to the service,
+possible interpretations include assuming an empty collection or,
+for parameters not annotated as `Core.OptionalParameter`, reporting an error.
+
 ::: example
 Example 54:
 ```json

docs/odata-protocol/odata-protocol.html

@@ -1076,8 +1076,9 @@ <h4 id="8285-preference-maxpagesize-odatamaxpagesize"><a id="Preferencemaxpagesi
 <h4 id="8286-preference-omit-values"><a id="Preferenceomitvalues" href="#Preferenceomitvalues">8.2.8.6 Preference <code>omit-values</code></a></h4>
 </summary>
 <p>The <code>omit-values</code> preference specifies values that MAY be omitted from a response payload. Valid values are <code>nulls</code> or <code>defaults</code>.</p>
-<p>If <code>nulls</code> is specified, then the service MAY omit properties containing null values from the response, in which case it MUST specify the <code>Preference-Applied</code> response header with <code>omit-values=nulls</code>.</p>
-<p>If <code>defaults</code> is specified, then the service MAY omit properties containing default values from the response, including nulls for properties that have no other defined default value. Nulls MUST be included for properties that have a non-null default value defined. If the service omits default values, it MUST specify the <code>Preference-Applied</code> response header with <code>omit-values=defaults</code>.</p>
+<p>If <code>nulls</code> is specified, then the service MAY omit single-valued properties having null values from the response, in which case it MUST specify the <code>Preference-Applied</code> response header with <code>omit-values=nulls</code>.</p>
+<p>If <code>defaults</code> is specified, then the service MAY omit single-valued properties having default values from the response, including nulls for properties that have no other defined default value. Nulls MUST be included for properties that have a non-null default value defined. If the service omits default values, it MUST specify the <code>Preference-Applied</code> response header with <code>omit-values=defaults</code>.</p>
+<p>Collection-valued properties cannot be omitted in this way.</p>
 <p>Properties with instance annotations are not affected by this preference and MUST be included in the payload if they would be included without this preference. Clients MUST NOT try to reconstruct a null or default value for properties for which an instance annotation is present and no property value is present, for example if the property is omitted due to permissions and has been replaced with the instance annotation <code>Core.Permissions</code> and a value of <code>None</code>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
 <p>Properties with null or default values MUST be included in delta payloads, if modified.</p>
 <p>The response to a <code>POST</code> operation MUST include any properties not set to their default value, and the response to a <code>PUT</code> or <code>PATCH</code> operation MUST include any properties whose values were changed as part of the operation.</p>

docs/odata-protocol/odata-protocol.md

@@ -1497,17 +1497,19 @@ SHOULD be used.
 The `omit-values` preference specifies values that MAY be omitted from a
 response payload. Valid values are `nulls` or `defaults`.
 
-If `nulls` is specified, then the service MAY omit properties containing
+If `nulls` is specified, then the service MAY omit single-valued properties having
 null values from the response, in which case it MUST specify the
 `Preference-Applied` response header with `omit-values=nulls`.
 
-If `defaults` is specified, then the service MAY omit properties
-containing default values from the response, including nulls for
+If `defaults` is specified, then the service MAY omit single-valued properties
+having default values from the response, including nulls for
 properties that have no other defined default value. Nulls MUST be
 included for properties that have a non-null default value defined. If
 the service omits default values, it MUST specify the
 `Preference-Applied` response header with `omit-values=defaults`.
 
+Collection-valued properties cannot be omitted in this way.
+
 Properties with instance annotations are not affected by this preference
 and MUST be included in the payload if they would be included without
 this preference. Clients MUST NOT try to reconstruct a null or default

odata-csdl/12 Action and Function.md

@@ -428,7 +428,13 @@ 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`.
 
-The value `true` means that the parameter accepts a `null` value.
+For single-valued parameters the value `true` means that the parameter
+accepts a `null` value.
+
+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.
 :::
 
 ### ##subisec Annotation `Core.OptionalParameter`

odata-json-format/1 Introduction.md

@@ -42,6 +42,9 @@ Removed reference to obsolete version of GeoJSON|
 [Section ##ActionInvocation]| 
 Allow common expressions in action payloads| 
 [341](https://github.com/oasis-tcs/odata-specs/issues/341)
+[Section ##ActionInvocation]| 
+Omission of collection-valued action parameters| 
+[2045](https://github.com/oasis-tcs/odata-specs/issues/2045)
 
 ## ##subsec Glossary
 

odata-json-format/16 Bound Function.md

@@ -325,10 +325,10 @@ Content-Type: application/json
 Inside a batch request the common expressions can also be value references
 starting with `$`, as introduced in [#OData-Protocol#ReferencingValuesfromResponseBodies].
 
-Non-binding parameters that are nullable or annotated with the term
+Non-binding single-valued parameters that are nullable or annotated with the term
 [`Core.OptionalParameter`]($$$OData-VocCore$$$#OptionalParameter) defined in
 [OData-VocCore](#ODataVocCore) MAY be omitted from the request body.
-If an omitted parameter is not annotated (and thus nullable), it MUST be
+If an omitted single-valued parameter is not annotated (and thus nullable), it MUST be
 interpreted as having the `null` value. If it is annotated
 and the annotation specifies a `DefaultValue`, the omitted
 parameter is interpreted as having that default value. If omitted and
@@ -337,6 +337,11 @@ how to interpret the omitted parameter. Note: a nullable non-binding
 parameter is equivalent to being annotated as optional with a default
 value of `null`.
 
+Non-binding collection-valued parameters MAY be omitted from the request body regardless
+of nullability or optionality. The interpretation of such an omitted parameter is up to the service,
+possible interpretations include assuming an empty collection or,
+for parameters not annotated as `Core.OptionalParameter`, reporting an error.
+
 ::: example
 Example ##ex:
 ```json

odata-protocol/8 Header Fields.md

@@ -599,17 +599,19 @@ SHOULD be used.
 The `omit-values` preference specifies values that MAY be omitted from a
 response payload. Valid values are `nulls` or `defaults`.
 
-If `nulls` is specified, then the service MAY omit properties containing
+If `nulls` is specified, then the service MAY omit single-valued properties having
 null values from the response, in which case it MUST specify the
 `Preference-Applied` response header with `omit-values=nulls`.
 
-If `defaults` is specified, then the service MAY omit properties
-containing default values from the response, including nulls for
+If `defaults` is specified, then the service MAY omit single-valued properties
+having default values from the response, including nulls for
 properties that have no other defined default value. Nulls MUST be
 included for properties that have a non-null default value defined. If
 the service omits default values, it MUST specify the
 `Preference-Applied` response header with `omit-values=defaults`.
 
+Collection-valued properties cannot be omitted in this way.
+
 Properties with instance annotations are not affected by this preference
 and MUST be included in the payload if they would be included without
 this preference. Clients MUST NOT try to reconstruct a null or default