From 64142b5643f74c6023b457a384eba1dff51d278c Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 24 Jul 2024 17:15:22 +0200 Subject: [PATCH 1/2] Transient entities in JSON (#1942) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - [x] Fixes #1928 - [x] Align with Protocol (transient entities may have a read URL) - [x] Adjusted Protocol (transient entities may have an entity id) --------- Co-authored-by: Heiko Theißen --- docs/odata-json-format/odata-json-format.html | 10 +++++++--- docs/odata-json-format/odata-json-format.md | 18 +++++++++--------- docs/odata-protocol/odata-protocol.html | 2 +- docs/odata-protocol/odata-protocol.md | 5 +++-- odata-json-format/1 Introduction.md | 3 +++ odata-json-format/4 Common Characteristics.md | 17 ++++++++--------- odata-protocol/1 Introduction.md | 5 +++-- 7 files changed, 34 insertions(+), 26 deletions(-) diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index c99d1bcd..1ef20a2c 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -334,11 +334,16 @@

368 +Section 4.5.8 +Transient entities can be identifiable +1928 + + Section 4.5.12 mediaContentType can be null 536 - + Section 7, Section A.2 Removed reference to obsolete version of GeoJSON 456 @@ -679,9 +684,8 @@

RFC3986.

Note that the entity-id MUST be invariant across languages, so if key values are language dependent then the id MUST be included if it does not match convention for the localized key values. If the id is represented, it MAY be a relative URL.

-

If the entity is transient (see OData-Protocol), the id control information MUST appear in OData 4.0 payloads and have the null value. In 4.01 payloads transient entities need not have the id control information, and 4.01 clients MUST treat entities with neither id control information nor a full set of key properties as transient entities.

+

If the entity is transient (see OData-Protocol), the id control information MUST appear in OData 4.0 payloads and have the null value. In 4.01 or greater payloads transient entities need not have the id control information, and clients receiving such payloads MUST treat entities with neither id control information nor a full set of key properties as transient entities. In 4.02 payloads transient entities MAY have the id control information with a non-null URI value, for example to allow solving a circular dependency by injecting an entity reference instead of repeating the transient entity. The URI value SHOULD follow the pattern odata:transient:{some-generated-identifier-unique-within-the-response}, and if the transient entity cannot be re-read its readLink control information SHOULD have the null value.

The id control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification.

-

Entities with id equal to null cannot be compared to other entities, reread, or updated. If metadata=minimal is specified and the id is not present in the entity, then the canonical URL MUST be used as the entity-id.

diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index 8c0d7f3f..67c52ea7 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -216,6 +216,7 @@ An OData JSON payload may represent: Section | Feature / Change | Issue --------|------------------|------ [Section 4.5.1](#ControlInformationcontextodatacontext)| Fragment portion of Context URL is not percent-encoded| [368](https://github.com/oasis-tcs/odata-specs/issues/368) +[Section 4.5.8](#ControlInformationidodataid)| Transient entities can be identifiable| [1928](https://github.com/oasis-tcs/odata-specs/issues/1928) [Section 4.5.12](#ControlInformationmediaodatamedia)| `mediaContentType` can be `null`| [536](https://github.com/oasis-tcs/odata-specs/issues/536) [Section 7](#StructuralProperty), [Section A.2](#InformativeReferences)| Removed reference to obsolete version of GeoJSON| [456](https://github.com/oasis-tcs/odata-specs/issues/456) @@ -964,21 +965,20 @@ URL](#RelativeURLs). If the entity is transient (see [OData-Protocol](#ODataProtocol)), the `id` control information MUST appear in OData 4.0 payloads -and have the `null` value. In 4.01 payloads transient -entities need not have the `id` control information, and 4.01 -clients MUST treat entities with neither `id` control +and have the `null` value. In 4.01 or greater payloads transient +entities need not have the `id` control information, and +clients receiving such payloads MUST treat entities with neither `id` control information nor a full set of key properties as transient entities. +In 4.02 payloads transient entities MAY have the `id` control information with a non-null URI value, +for example to allow solving a circular dependency by injecting an +[entity reference](#EntityReference) instead of repeating the transient entity. +The URI value SHOULD follow the pattern `odata:transient:{some-generated-identifier-unique-within-the-response}`, +and if the transient entity cannot be re-read its `readLink` control information SHOULD have the `null` value. The `id` control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification. -Entities with `id` equal to `null` cannot be -compared to other entities, reread, or updated. If -[`metadata=minimal`](#metadataminimalodatametadataminimal) -is specified and the `id` is not present in the entity, then -the canonical URL MUST be used as the entity-id. - ### 4.5.9 Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`) The `editLink` control information contains diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 5b265d00..edfe1806 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -673,7 +673,7 @@

4.3 Transient Entities

 -

Transient entities are instances of an entity type that are dynamically generated on request and only exist within a response payload. They do not possess an entity-id or an update URL and consequently cannot be updated. A transient entity may have a read URL, which generates a new transient entity using the same algorithm.

+

Transient entities are instances of an entity type that are dynamically generated on request and only exist within a response payload. They do not possess an update URL and consequently cannot be updated. A transient entity may have a read URL, which generates a new transient entity using the same algorithm, and they may have an entity id if a repeated occurrence in a response needs to be replaced with an entity reference.

4.4 Default Namespaces

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index e8e0120e..e11e9f2c 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -618,8 +618,9 @@ one or both of them may differ from convention. Transient entities are instances of an entity type that are dynamically generated on request and only exist within a response payload. -They do not possess an entity-id or an update URL and consequently cannot be updated. -A transient entity may have a read URL, which generates a new transient entity using the same algorithm. +They do not possess an update URL and consequently cannot be updated. +A transient entity may have a read URL, which generates a new transient entity using the same algorithm, +and they may have an entity id if a repeated occurrence in a response needs to be replaced with an entity reference. ## 4.4 Default Namespaces diff --git a/odata-json-format/1 Introduction.md b/odata-json-format/1 Introduction.md index de6d5929..06a8a5ef 100644 --- a/odata-json-format/1 Introduction.md +++ b/odata-json-format/1 Introduction.md @@ -24,6 +24,9 @@ Section | Feature / Change | Issue [Section ##ControlInformationcontextodatacontext]| Fragment portion of Context URL is not percent-encoded| [368](https://github.com/oasis-tcs/odata-specs/issues/368) +[Section ##ControlInformationidodataid]| +Transient entities can be identifiable| +[1928](https://github.com/oasis-tcs/odata-specs/issues/1928) [Section ##ControlInformationmediaodatamedia]| `mediaContentType` can be `null`| [536](https://github.com/oasis-tcs/odata-specs/issues/536) diff --git a/odata-json-format/4 Common Characteristics.md b/odata-json-format/4 Common Characteristics.md index 8190d1c1..3fe40dd9 100644 --- a/odata-json-format/4 Common Characteristics.md +++ b/odata-json-format/4 Common Characteristics.md @@ -419,21 +419,20 @@ URL](#RelativeURLs). If the entity is transient (see [OData-Protocol](#ODataProtocol)), the `id` control information MUST appear in OData 4.0 payloads -and have the `null` value. In 4.01 payloads transient -entities need not have the `id` control information, and 4.01 -clients MUST treat entities with neither `id` control +and have the `null` value. In 4.01 or greater payloads transient +entities need not have the `id` control information, and +clients receiving such payloads MUST treat entities with neither `id` control information nor a full set of key properties as transient entities. +In 4.02 payloads transient entities MAY have the `id` control information with a non-null URI value, +for example to allow solving a circular dependency by injecting an +[entity reference](#EntityReference) instead of repeating the transient entity. +The URI value SHOULD follow the pattern `odata:transient:{some-generated-identifier-unique-within-the-response}`, +and if the transient entity cannot be re-read its `readLink` control information SHOULD have the `null` value. The `id` control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification. -Entities with `id` equal to `null` cannot be -compared to other entities, reread, or updated. If -[`metadata=minimal`](#metadataminimalodatametadataminimal) -is specified and the `id` is not present in the entity, then -the canonical URL MUST be used as the entity-id. - ### ##subsubsec Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`) The `editLink` control information contains diff --git a/odata-protocol/1 Introduction.md b/odata-protocol/1 Introduction.md index 579ae929..97b8f2d7 100644 --- a/odata-protocol/1 Introduction.md +++ b/odata-protocol/1 Introduction.md @@ -301,8 +301,9 @@ one or both of them may differ from convention. Transient entities are instances of an entity type that are dynamically generated on request and only exist within a response payload. -They do not possess an entity-id or an update URL and consequently cannot be updated. -A transient entity may have a read URL, which generates a new transient entity using the same algorithm. +They do not possess an update URL and consequently cannot be updated. +A transient entity may have a read URL, which generates a new transient entity using the same algorithm, +and they may have an entity id if a repeated occurrence in a response needs to be replaced with an entity reference. ## ##subsec Default Namespaces From 0fcf9c3b6ba98e5d3039befcf83dcbddab2078a2 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 24 Jul 2024 17:23:29 +0200 Subject: [PATCH 2/2] Clarify key values in upsert along navigation properties (#1924) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - [x] Fixes #402 --------- Co-authored-by: Heiko Theißen --- docs/odata-protocol/odata-protocol.html | 2 +- docs/odata-protocol/odata-protocol.md | 6 +++--- odata-protocol/11.4 Data Modification.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index edfe1806..444a9395 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -2403,7 +2403,7 @@

1

Upserts are not supported against entities whose keys’ values are generated by the service. Services MUST fail an update request to a URL that would identify such an entity and the entity does not yet exist.

Similarly, services MUST fail an update request to the URL of a media entity that does not yet exist. However, a PUT request to the media edit URL of a media entity does have Upsert semantics, in that the media entity is created with the specified media stream if it does not already exist, otherwise the media stream of the existing media entity is updated.

Singleton entities can be upserted if they are nullable. Services supporting this SHOULD advertise it by annotating the singleton with the term Capabilities.UpdateRestrictions (nested property Upsertable with value true) defined in OData-VocCap.

-

Key and other non-updatable properties, as well as dependent properties that are not tied to key properties of the principal entity, MUST be ignored by the service in processing the Upsert request.

+

A key property whose value is provided in the request URL SHOULD be omitted from the request body. If key properties are provided in the request URL and the request body with different values, services MUST either fail the request or ignore the value in the request body.

To ensure that an update request is not treated as an insert, the client MAY specify an If-Match header in the update request. The service MUST NOT treat an update request containing an If-Match header as an insert.

A PUT or PATCH request MUST NOT be treated as an update if an If-None-Match header is specified with a value of *.

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index e11e9f2c..b71610bf 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -4561,9 +4561,9 @@ supporting this SHOULD advertise it by annotating the singleton with the term `Capabilities.UpdateRestrictions` (nested property `Upsertable` with value `true`) defined in [OData-VocCap](#ODataVocCap). -Key and other non-updatable properties, as well as dependent properties -that are not tied to key properties of the principal entity, MUST be -ignored by the service in processing the Upsert request. +A key property whose value is provided in the request URL SHOULD be omitted from the request body. +If key properties are provided in the request URL and the request body with different values, +services MUST either fail the request or ignore the value in the request body. To ensure that an update request is not treated as an insert, the client MAY specify an [`If-Match`](#HeaderIfMatch) header in the update diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index 6b97d7fb..25ff840c 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -577,9 +577,9 @@ supporting this SHOULD advertise it by annotating the singleton with the term `Capabilities.UpdateRestrictions` (nested property `Upsertable` with value `true`) defined in [OData-VocCap](#ODataVocCap). -Key and other non-updatable properties, as well as dependent properties -that are not tied to key properties of the principal entity, MUST be -ignored by the service in processing the Upsert request. +A key property whose value is provided in the request URL SHOULD be omitted from the request body. +If key properties are provided in the request URL and the request body with different values, +services MUST either fail the request or ignore the value in the request body. To ensure that an update request is not treated as an insert, the client MAY specify an [`If-Match`](#HeaderIfMatch) header in the update