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

Clarify "Expand to the level present in the deep insert request" #2025

Merged
merged 2 commits into from
Nov 20, 2024
Merged

Clarify "Expand to the level present in the deep insert request" #2025

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f9635cc
Fixes #363
ralfhandl Oct 31, 2024
a646a00
Rephrased
ralfhandl Nov 20, 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
17 changes: 11 additions & 6 deletions docs/odata-protocol/odata-protocol.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -584,31 +584,36 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/356">356</a></td>
</tr>
<tr class="odd">
<td>Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) Deep-insert response includes at least the properties present in the request</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/363">363</a></td>
<td></td>
</tr>
<tr class="even">
<td><a href="#UpdateanEntity">Section 11.4.3</a></td>
<td>Services can validate non-updatable property values in update payloads</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/356">356</a></td>
</tr>
<tr class="even">
<tr class="odd">
<td><a href="#UpsertanEntity">Section 11.4.4</a></td>
<td>Upserts to single-valued non-containment navigation properties</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/455">455</a></td>
</tr>
<tr class="odd">
<tr class="even">
<td><a href="#UpdateaComplexProperty">Section 11.4.9.3</a></td>
<td>Setting a complex property to a different type</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/534">534</a></td>
</tr>
<tr class="even">
<tr class="odd">
<td><a href="#ReplaceaCollectionofEntities">Section 11.4.13</a></td>
<td>Semantics of <code>continue-on-error</code> when replacing a collection of entities</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/358">358</a></td>
</tr>
<tr class="odd">
<tr class="even">
<td><a href="#Conformance">Section 12</a></td>
<td>Allow <code>400 Bad Request</code> in addition to <code>501 Not Implemented</code> for unsupported functionality</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/391">391</a></td>
</tr>
<tr class="even">
<tr class="odd">
<td><a href="#InteroperableODataClients">Section 12.3</a></td>
<td>Encoding of plus character in URLs</td>
<td><a href="https://github.com/oasis-tcs/odata-specs/issues/485">485</a></td>
Expand Down Expand Up @@ -2370,7 +2375,7 @@ <h4 id="11422-create-related-entities-when-creating-an-entity"><a id="CreateRela
<p>A request to create an entity that includes related entities, represented using the appropriate inline representation, is referred to as a “deep insert”.</p>
<p>Media entities MUST contain the format-specific representation of their media stream as a virtual property <code>$value</code> when nested within a deep insert.</p>
<p>Each included related entity is processed observing the rules for <a href="#CreateanEntity">creating an entity</a> as if it was posted against the original target URL extended with the navigation path to this related entity.</p>
<p>On success, the service MUST create all entities and relate them. If the service responds with <a href="#ResponseCode201Created"><code>201 Created</code></a>, the response MUST be expanded to at least the level that was present in the deep-insert request.</p>
<p>On success, the service MUST create all entities and relate them. If the service responds with <a href="#ResponseCode201Created"><code>201 Created</code></a>, the response MUST be expanded to include at least the entities and properties that were specified in the deep-insert request.</p>
<p>Clients MAY associate an id with individual nested entities in the request by applying the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> term using the namespace or alias defined for the <a href="#ODataVocCore">OData-VocCore</a> vocabulary in the service’s <code>$metadata</code> document. Services that respond with <a href="#ResponseCode201Created"><code>201 Created</code></a> SHOULD annotate the entities in the response using the same <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> value as specified in the request. Services SHOULD advertise support for deep inserts, including support for returning the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a>, through the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepInsertSupport"><code>Capabilities.DeepInsertSupport</code></a> term, defined in <a href="#ODataVocCap">OData-VocCap</a>; services that advertise support through <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepInsertSupport"><code>Capabilities.DeepInsertSupport</code></a> MUST return the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> for the inserted or updated entities.</p>
<p>The <code>continue-on-error</code> preference is not supported for deep insert operations.</p>
<p>On failure, the service MUST NOT create any of the entities.</p>
Expand Down
4 changes: 2 additions & 2 deletions docs/odata-protocol/odata-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,7 @@ Section | Feature / Change | Issue
[Section 10.2](#CollectionofEntities)| Context URLs use parentheses-style keys without percent-encoding| [368](https://github.com/oasis-tcs/odata-specs/issues/368)
[Section 11.4](#DataModification)| Response code `204 No Content` after successful data modification if requested response could not be constructed| [443](https://github.com/oasis-tcs/odata-specs/issues/443)
[Section 11.4.2](#CreateanEntity)| Services can validate non-insertable property values in insert payloads| [356](https://github.com/oasis-tcs/odata-specs/issues/356)
|Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) Deep-insert response includes at least the properties present in the request| [363](https://github.com/oasis-tcs/odata-specs/issues/363)
[Section 11.4.3](#UpdateanEntity)| Services can validate non-updatable property values in update payloads| [356](https://github.com/oasis-tcs/odata-specs/issues/356)
[Section 11.4.4](#UpsertanEntity)| Upserts to single-valued non-containment navigation properties| [455](https://github.com/oasis-tcs/odata-specs/issues/455)
[Section 11.4.9.3](#UpdateaComplexProperty)| Setting a complex property to a different type| [534](https://github.com/oasis-tcs/odata-specs/issues/534)
Expand Down Expand Up @@ -4289,8 +4290,7 @@ original target URL extended with the navigation path to this related
entity.

On success, the service MUST create all entities and relate them. If the
service responds with [`201 Created`](#ResponseCode201Created), the response MUST be expanded to at
least the level that was present in the deep-insert request.
service responds with [`201 Created`](#ResponseCode201Created), the response MUST be expanded to include at least the entities and properties that were specified in the deep-insert request.

Clients MAY associate an id with individual nested entities in the
request by applying the
Expand Down
3 changes: 3 additions & 0 deletions odata-protocol/1 Introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ Response code `204 No Content` after successful data modification if requested r
[Section ##CreateanEntity]|
Services can validate non-insertable property values in insert payloads|
[356](https://github.com/oasis-tcs/odata-specs/issues/356)
|Section ##CreateRelatedEntitiesWhenCreatinganEntity]
Deep-insert response includes at least the properties present in the request|
[363](https://github.com/oasis-tcs/odata-specs/issues/363)
[Section ##UpdateanEntity]|
Services can validate non-updatable property values in update payloads|
[356](https://github.com/oasis-tcs/odata-specs/issues/356)
Expand Down
4 changes: 2 additions & 2 deletions odata-protocol/11.4 Data Modification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,8 +285,8 @@ original target URL extended with the navigation path to this related
entity.

On success, the service MUST create all entities and relate them. If the
service responds with [`201 Created`](#ResponseCode201Created), the response MUST be expanded to at
least the level that was present in the deep-insert request.
service responds with [`201 Created`](#ResponseCode201Created), the response MUST be expanded to
include at least the entities and properties that were specified in the deep-insert request.

Clients MAY associate an id with individual nested entities in the
request by applying the
Expand Down