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