Unique resource identifiers when sending new data to a server

[cookeac]

This issue is a placeholder to be elaborated.
It covers the question of how objects should be identified when sent to a server by a client - using UUIDs, client issued identifiers, assuming the server will issue identifiers, etc.

[cookeac]

This item has been discussed in meetings:

• 23 October
• 3 December

My recommendations:

1. For referring to a resource on a server, we already have the link semantic @self defined in icarResource.json. This provides us with a server-defined link that can be used for updates and references.
2. Provide guidance that id within icarEventCoreResource.json must be globally unique. This should be a UUID but could be manufactured by the data source or its wrapper using a namespace to make it unique.
3. Consider replacing id (string) within icarEventCoreResource.json with a scheme and Id combination (icarEventIdentifier). However, this would be a breaking change.
4. Consider adding alternativeIdentifiers[] within icarEventCoreResource.json to support an array of alternative identifiers in scheme and ID format.

[erwinspeybroeck]

Can we in the meantime add a sourceId in the meta data? That could be used to facilitate updating resources.

[cookeac]

Current documentation for id in icarEventCoreResource.json is:

 "id": {
          "type": "string",
          "description": "Unique identifier in the source system for this event."
        }

I propose that we consider refactoring this as follows:

 "id": {
          "type": "string",
          "description": "Globally unique identifier (uuid or proxy) in the (serving or sending) system for this event."
        }
 "sourceId": {
          "type": "string",
          "description": "Globally unique identifier (uuid or proxy) in the origin system for this event."
        }

This avoids changing the meaning of id as it has been used to date, or changing its format (to an icarIdentifierType). It stops short of requiring all systems to maintain and share a list of all internal IDs that have ever been used.

In practical use:

• If you are a client of a server just seeking to PUT/POST etc data, then use id or better still, use the URL in @self (defined in icarResource.json).
• If you are trying to synchronise data and really focused on unique events, check the sourceId.

[cookeac]

We agreed on 11 February 2021 that:

1. We will add sourceId alongside the existing source in icarMetaDataType. Although these are separate fields (to avoid breaking changes), they should be treated like the scheme and id components of an icarIdentifierType.
2. Implementers should populate these fields when creating new events, and the sourceId should be unique (ideally a UUID).
3. Implementers should keep and transfer these source values, even if they assign new Ids to events or resources.
4. We consider that eventually an alternativeIdentifiers[] array should be added to all resources (it is currently available for icarAnimalCoreResource) but we will wait until there is clear demand.

[alamers]

I've added these principles to https://github.com/adewg/ICAR/wiki/Design-Principles

[cookeac]

Resolved by #197 and changes to the Wiki