Define a mechanism to distinguish between inserted and updated entities in a Delta message

[ralfhandl]

In a delta response, Added and Changed entities are represented as Entities in the delta response. There is no way for the client to distinguish between an Inserted entity and a Changed entity. If the client is using the delta response to keep data in a cache or data warehouse in sync, then the distinction between an Inserted and Updated entity doesn't really matter. The client would do an upsert of the Inserted / Updated entity. If the entity exists it gets updated and if it doesn't it gets inserted.

However, in cases where the changes are being tracked for auditing or reporting purposes, it is useful to be able to distinguish between an inserted or updated entity. There is a difference between inserted and updated entities in a delta response in that an inserted entity must include all selected properties where as an updated entity must only include all selected properties that changed. The distinction is not reliable for detecting the difference though. It is possible that all of the selected properties of an existing entity have change and it is also possible that a server would always return all selected properties of an updated entity.

Consider adding an optional @Inserted or @Updated annotation or both to make the distinction between the Inserted and Updated entities, This is similar to the @removed annotation that already exists.

When a delta payload is provided to the service in the body of an update request, the @Inserted or @Updated annotations would typically would not be needed, but it should be fine to include them if for example the delta payload was originally received as a delta response.

Proposal

Define optional annotation @Core.PreviousState:"Existed" to allow making the distinction between added and changed entities.

This approach intentionally differs from the existing @removed control information, which is a required marker for deleted entities.

The presence or absence of the instance annotation does not alter the idempotent nature of a delta message, nor does it alter the UPSERT nature of an added/changed entity.

The recipient of a delta message may use the instance annotation for optimization, and still has to process any received added/changed entity as an UPSERT.

Annotation sketch: [https://github.com/oasis-tcs/odata-vocabularies/pull/201]

Imported from ODATA-1239