From 22180d126ebd092b687bc0e0c7f7a5dea1af3cab Mon Sep 17 00:00:00 2001 From: mikepizzo Date: Tue, 15 Oct 2024 17:36:31 -0700 Subject: [PATCH] Clarify ordering constraints of deleted entity in JSON payload --- docs/odata-json-format/odata-json-format.html | 10 ++++++---- docs/odata-json-format/odata-json-format.md | 9 ++++++--- odata-json-format/1 Introduction.md | 3 +++ odata-json-format/15 Delta Payload.md | 7 ++++--- odata-json-format/4 Common Characteristics.md | 2 ++ 5 files changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 50fe4189..c175ff66 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -399,12 +399,13 @@

456 -Section 18 -Allow common expressions in action payloads -341 +Section 15.3 +type control information, if present, must come immediately after removed + +

1985 Section 18| Allow common expressions in action payloads| 341

1.2 Glossary

@@ -634,6 +635,7 @@

To support streaming scenarios the following payload ordering constraints have to be met:

  • If present, the context control information MUST be the first property in the JSON object.
    • +
  • For 4.01 deleted entities, the @removed control information MUST appear after context, if present, and before any other property or control information.
  • The type control information, if present, MUST appear next in the JSON object.
  • The id and etag control information MUST appear before any property, property annotation, or property control information.
  • All annotations or control information for a structural or navigation property MUST appear as a group immediately before the property itself. The one exception is the nextLink of a collection which MAY appear after the collection it annotates.
    • @@ -1477,7 +1479,7 @@

    15.3 Del

    In OData 4.01 payloads the deleted-entity object MUST include the following properties, regardless of the specified metadata value:

    • Control information removed, whose value is an object that MAY contain a property named reason. If present, the value of reason MUST be either deleted if the entity was deleted (destroyed), or changed if the entity was removed from membership in the result either due to change in value such that the entity no longer matches the defining query or because the entity was removed from the collection. The object MAY include annotations, and clients SHOULD NOT error due to the presence of additional properties that MAY be defined by future versions of this specification. For ordered payloads, the control information removed MUST immediately follow the context control information, if present, otherwise it MUST be the first property in the deleted entity.

      • -

    • Control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an update request, an alternate key (see Alternate Keys in OData-URL) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields. For ordered payloads, the control information id, if present, MUST immediately follow the control information removed.

      • +

    • Control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an update request, an alternate key (see Alternate Keys in OData-URL) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields. For ordered payloads, the control information id, if present, MUST appear following the control information removed and, if present, type, and before any other properties or control information.

    For full metadata the context control information MUST be included. It also MUST be included if the entity set of the deleted entity cannot be determined from the surrounding context.

    The deleted-entity object MAY include additional properties of the entity, as well as annotations, and MAY include related entities, related deleted entities, or a delta or full representation of a related collection of entities, to represent related entities that have been modified or deleted.

    diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index 0dc397f1..1e4f749f 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -220,6 +220,8 @@ Section | Feature / Change | Issue [Section 4.6.8](#ControlInformationidodataid)| Transient entities can be identifiable| [1928](https://github.com/oasis-tcs/odata-specs/issues/1928) [Section 4.6.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) +[Section 15.3](#DeletedEntity) | `type` control information, if present, must come immediately after `removed` | +[1985](https://github.com/oasis-tcs/odata-specs/issues/1985) [Section 18](#ActionInvocation)| Allow common expressions in action payloads| [341](https://github.com/oasis-tcs/odata-specs/issues/341) ## 1.2 Glossary @@ -711,6 +713,7 @@ constraints have to be met: - If present, the `context` control information MUST be the first property in the JSON object. +- For 4.01 deleted entities, the `@removed` control information MUST appear after `context`, if present, and before any other property or control information. - The `type` control information, if present, MUST appear next in the JSON object. @@ -2300,9 +2303,9 @@ following properties, regardless of the specified MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the `id` control information and other primary key fields. For [ordered payloads](#PayloadOrderingConstraints), the control information - `id`, if present, MUST immediately follow the control - information - [`removed`](#ControlInformationremovedodataremoved). + `id`, if present, MUST appear following the control information + [`removed`](#ControlInformationremovedodataremoved) and, if present, [`type`](#ControlInformationtypeodatatype), and before any other + properties or control information. For full metadata the [`context`](#ControlInformationcontextodatacontext) diff --git a/odata-json-format/1 Introduction.md b/odata-json-format/1 Introduction.md index 86925999..9d8e31c5 100644 --- a/odata-json-format/1 Introduction.md +++ b/odata-json-format/1 Introduction.md @@ -33,6 +33,9 @@ Transient entities can be identifiable| [Section ##StructuralProperty], [Section ##InformativeReferences]| Removed reference to obsolete version of GeoJSON| [456](https://github.com/oasis-tcs/odata-specs/issues/456) +[Section ##DeletedEntity] | +`type` control information, if present, must come immediately after `removed` | +[1985](https://github.com/oasis-tcs/odata-specs/issues/1985) [Section ##ActionInvocation]| Allow common expressions in action payloads| [341](https://github.com/oasis-tcs/odata-specs/issues/341) diff --git a/odata-json-format/15 Delta Payload.md b/odata-json-format/15 Delta Payload.md index 95b2bff0..eb5309af 100644 --- a/odata-json-format/15 Delta Payload.md +++ b/odata-json-format/15 Delta Payload.md @@ -211,9 +211,10 @@ following properties, regardless of the specified MAY be used in place of the entity's primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the `id` control information and other primary key fields. For [ordered payloads](#PayloadOrderingConstraints), the control information - `id`, if present, MUST immediately follow the control - information - [`removed`](#ControlInformationremovedodataremoved). + `id`, if present, MUST appear following the control information + [`removed`](#ControlInformationremovedodataremoved) and, if present, + [`type`](#ControlInformationtypeodatatype), and before any other + properties or control information. For full metadata the [`context`](#ControlInformationcontextodatacontext) diff --git a/odata-json-format/4 Common Characteristics.md b/odata-json-format/4 Common Characteristics.md index daa44aa1..071f62b5 100644 --- a/odata-json-format/4 Common Characteristics.md +++ b/odata-json-format/4 Common Characteristics.md @@ -164,6 +164,8 @@ constraints have to be met: - If present, the `context` control information MUST be the first property in the JSON object. +- For 4.01 deleted entities, the `@removed` control information MUST appear + after `context`, if present, and before any other property or control information. - The `type` control information, if present, MUST appear next in the JSON object.