Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support functions and actions taking/returning delta payloads #2005

Merged
merged 8 commits into from
Oct 2, 2024
Merged

Support functions and actions taking/returning delta payloads #2005

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9036a06
Add description of Core.IsDelta to ReturnType and Parameter
mikepizzo Sep 26, 2024
722ed49
Merge branch 'main' into DeltaFunctions
ralfhandl Sep 27, 2024
ff5aef0
Make new text representation-independent
ralfhandl Sep 27, 2024
e2e7750
Merge branch 'DeltaFunctions' of https://github.com/oasis-tcs/odata-s…
ralfhandl Sep 27, 2024
75a6482
make section Core.IsDelta representation-independent
ralfhandl Sep 27, 2024
f5f1d68
Revert accidental change
ralfhandl Sep 27, 2024
5aac772
Nit
ralfhandl Sep 27, 2024
d1d3db1
Only example is representation-specific
ralfhandl Sep 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions docs/odata-csdl-json/odata-csdl-json.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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 />
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
32 changes: 29 additions & 3 deletions docs/odata-csdl-json/odata-csdl-json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.


-------
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
Loading