From 3571d78b20cc9e74fb2dbafd99afb259b8f4a371 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Wed, 2 Oct 2024 17:52:42 +0200 Subject: [PATCH 1/3] 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 @@

4.6.5 Control Information: nextLink (odata.nextLink)

The nextLink control information indicates that a response is only a subset of the requested collection. It contains a URL that allows retrieving the next subset of the requested collection.

-

This control information can also be applied to expanded to-many navigation properties.

+

This control information can also be applied to expanded to-many navigation properties and to collections of primitive or complex values.

4.6.6 Control Information: delta (odata.delta)

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. ### 4.6.6 Control Information: `delta` (`odata.delta`) 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 @@ -

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.

+

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. 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 preference. The service may apply this requested page size or implement a page size different than, or in the absence of, this preference.

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 Accept header. OData services may use the reserved system query option $skiptoken when building next links. Its content is opaque, service-specific, and must only follow the rules for URL query parts.

OData clients MUST NOT use the system query option $skiptoken when constructing requests.

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 Date: Wed, 2 Oct 2024 09:00:17 -0700 Subject: [PATCH 2/3] 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 @@

+Section 12 +Actions and functions can take, and return, delta payloads +348 + + Section 14.3.13 Constant Geo values in annotations 654 - + Section 14.3.14 Constant Stream values in annotations 654 - + Section 14.4.1.2 New path evaluation rules for annotations targeting annotations and external targeting via container 575 - + Section 14.4.7 Nested If without else part in collections 326 - + Section 17 Additional conformance clauses for version 4.02 @@ -2010,6 +2015,9 @@

$Nullable

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

For single-valued return types the value true means that the action or function MAY return a single null value. The value false means that the action or function will never return a null value and instead will fail with an error response if it cannot compute a result.

+

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.

+

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.

12.9 Parameter

@@ -2021,7 +2029,7 @@

12.9 ParameterThe facets MaxLength, Precision, Scale, or SRID can be used as appropriate to specify value restrictions of the parameter, as well as the Unicode facet for 4.01 or greater payloads.

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.

-

$Parameter

+

$Parameter

The value of $Parameter is an array. The array contains one object per parameter.

Parameter Object

A parameter object MUST contain the member $Name, and it MAY contain the members $Type, $Collection, $Nullable, $MaxLength, $Unicode, $Precision, $Scale, and $SRID.

@@ -2037,6 +2045,9 @@

$Nullable

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.

+

All parameters marked as optional MUST come after any parameters not marked as optional. The binding parameter MUST NOT be marked as optional.

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 $Parameter member.

"TopSellingProducts": [
@@ -2058,6 +2069,9 @@ 
$Nullable

   }
 ]
+

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.

+

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.

@@ -2501,7 +2515,7 @@

14.1.2 A Parameter -Action of Function Parameter +Action or Function Parameter Property @@ -4369,7 +4383,8 @@

$Type
  • $Collection
  • $Nullable
    • -
  • $Parameter
    • +
  • Annotation Core.IsDelta
    • +
  • $Parameter
  • Parameter Object
  • Entity Container Object
      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. ::: +### 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`](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. + ## 12.9 Parameter 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} -### `$Parameter` +### `$Parameter` 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. ::: + +### Annotation `Core.OptionalParameter` + +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. ``` ::: +### 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`](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 @@

      464 +Section 12 +Actions and functions can take, and return, delta payloads +348 + + Section 14.3.13 Constant Geo values in annotations 654 - + Section 14.3.14 Constant Stream values in annotations 654 - + Section 14.4.1.2 New path evaluation rules for annotations targeting annotations and external targeting via container 575 - + Section 14.4.7 Nested If without else part in collections 326 - + Section 17 Additional conformance clauses for version 4.02 @@ -1896,6 +1901,9 @@

      Attribute For other 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.

      For single-valued return types the value true means that the action or function MAY return a single null value. The value false means that the action or function will never return a null value and instead will fail with an error response if it cannot compute a result.

      +

      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.

      +

      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.

      12.9 Parameter

      @@ -1919,6 +1927,9 @@

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

      +

      Annotation Core.OptionalParameter

      +

      A parameter that is annotated with the term Core.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.

      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 edm:Parameter element.

      <Function Name="TopSellingProducts">
@@ -1926,6 +1937,9 @@ 
      Attribute   <ReturnType Type="Collection(self.Product)" />
 </Function>
      +

      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.

      +

      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.

      @@ -2318,7 +2332,7 @@

      14.1.2 A Parameter -Action of Function Parameter +Action or Function Parameter Property @@ -4040,12 +4054,15 @@

      Attribute Type
    • Attribute Nullable
      • +
    • Annotation Core.IsDelta

  • Element edm:Parameter
  • Element edm:EntityContainer
      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. ::: +### 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`](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. + ## 12.9 Parameter 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} ### Element `edm:Parameter` @@ -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. ::: +### Annotation `Core.OptionalParameter` + +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. ``` ::: +### 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`](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 @@

      Table of Contents

    • 10.14 Collection of Complex or Primitive Types
    • 10.15 Complex or Primitive Type
    • 10.16 Operation Result
      • -
    • 10.17 Delta Payload Response
      • -
    • 10.18 Item in a Delta Payload Response
      • +
    • 10.17 Delta Payload
      • +
    • 10.18 Item in a Delta Payload
    • 10.19 $all Response
    • 10.20 $crossjoin Response
    • @@ -1563,7 +1563,7 @@

    1
    -

    10.17 Delta Payload Response

    +

    10.17 Delta Payload

    Context URL template:

    {context-url}#{entity-set}{/type-name}{select-list}/$delta
@@ -1577,10 +1577,10 @@ 
    update request body for a collection of entities is simply the fragment #$delta.
    -

    10.18 Item in a Delta Payload Response

    +

    10.18 Item in a Delta Payload

    Context URL templates:

    {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
 ```
 :::
 
-## 10.17 Delta Payload Response
+## 10.17 Delta Payload
 
 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`.
 
-## 10.18 Item in a Delta Payload Response
+## 10.18 Item in a Delta Payload
 
 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.
 
 ```
 :::
+
+### ##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 
Date: Wed, 2 Oct 2024 18:03:53 +0200
Subject: [PATCH 3/3] 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 @@ 
    441
 
 
+Section 5.1.3
+Nested query options can only appear once per expand item
+2004
+
+
 Section 5.1.8
 Allow alternative $search syntax
 293
@@ -2259,7 +2264,7 @@ 
    $compute, $select, $expand, and $levels for all navigation properties, plus $filter, $orderby, $skip, $top, $count, and $search for collection-valued navigation properties.
    
+
    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, $select, $expand, and $levels for all navigation properties, plus $filter, $orderby, $skip, $top, $count, and $search for collection-valued navigation properties.
    
 
    
 
    Example 124: all categories and for each category all related products with a discontinued date equal to null
    
 
    http://host/service/Categories?$expand=Products($filter=DiscontinuedDate eq null)
    
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)
 
 ## 1.2 Glossary
@@ -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),