diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html index 8eb5d574..0c891868 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.html +++ b/docs/odata-csdl-xml/odata-csdl-xml.html @@ -1934,7 +1934,8 @@

Attribute TypeFor collection-valued parameters the value of Type is the character sequence Collection( followed by the qualified name of the parameter’s type, followed by a closing parenthesis ).

Attribute Nullable

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

-

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.

Annotation Core.OptionalParameter

A parameter that is annotated with the term Core.OptionalParameter MAY be omitted when invoking the function or action.

diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md index 9b762167..a44d8e64 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.md +++ b/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. ::: ### Annotation `Core.OptionalParameter` diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 3a793819..e7348360 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -413,6 +413,11 @@

Allow common expressions in action payloads 341 + +Section 18 +Omission of collection-valued action parameters +2045 + @@ -2098,7 +2103,8 @@

}

Inside a batch request the common expressions can also be value references starting with $, as introduced in OData-Protocol, section 11.7.6.

-

Non-binding parameters that are nullable or annotated with the term Core.OptionalParameter defined in OData-VocCore MAY be omitted from the request body. If an omitted 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 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 null.

+

Non-binding single-valued parameters that are nullable or annotated with the term Core.OptionalParameter defined in OData-VocCore 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 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 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 null.

+

The interpretation of an omitted non-binding collection-valued parameter is up to the service regardless of its nullability or optionality. Possible interpretations include assuming an empty collection or, for parameters not annotated as Core.OptionalParameter, reporting an error.

Example 54:

{
diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md
index 2eb36dbd..18367aaa 100644
--- a/docs/odata-json-format/odata-json-format.md
+++ b/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)
 
 ## 1.2 Glossary
 
@@ -3150,10 +3151,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
@@ -3162,6 +3163,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`.
 
+The interpretation of an omitted non-binding collection-valued parameter
+is up to the service regardless of its nullability or optionality.
+Possible interpretations include assuming an empty collection or,
+for parameters not annotated as `Core.OptionalParameter`, reporting an error.
+
 ::: example
 Example 54:
 ```json
diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
index a9d0bc7f..9b5fd053 100644
--- a/docs/odata-protocol/odata-protocol.html
+++ b/docs/odata-protocol/odata-protocol.html
@@ -1079,8 +1079,9 @@ 
8.2.8.6 Preference omit-values

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

+
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 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 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 Core.Permissions and a value of None, see OData-VocCore.

 
Properties with null or default values MUST be included in delta payloads, if modified.

 
The response to a POST operation MUST include any properties not set to their default value, and the response to a PUT or PATCH operation MUST include any properties whose values were changed as part of the operation.

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index 8204fb98..82e77b34 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -1498,17 +1498,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
diff --git a/odata-csdl/12 Action and Function.md b/odata-csdl/12 Action and Function.md
index 23358fb3..500054c1 100644
--- a/odata-csdl/12 Action and Function.md	
+++ b/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`
diff --git a/odata-json-format/1 Introduction.md b/odata-json-format/1 Introduction.md
index fe81cf42..c80346ae 100644
--- a/odata-json-format/1 Introduction.md	
+++ b/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
 
diff --git a/odata-json-format/16 Bound Function.md b/odata-json-format/16 Bound Function.md
index 9cb2d9da..40659fd2 100644
--- a/odata-json-format/16 Bound Function.md	
+++ b/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`.
 
+The interpretation of an omitted non-binding collection-valued parameter
+is up to the service regardless of its nullability or optionality.
+Possible interpretations include assuming an empty collection or,
+for parameters not annotated as `Core.OptionalParameter`, reporting an error.
+
 ::: example
 Example ##ex:
 ```json
diff --git a/odata-protocol/8 Header Fields.md b/odata-protocol/8 Header Fields.md
index e85c0b97..3a58fbf0 100644
--- a/odata-protocol/8 Header Fields.md	
+++ b/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