Add support for TAGS

Goal

Need to add REST API support for openEHR Tags package (ITEM_TAG).

Comments:

:

• Background: In e.g. the Swedish openEHR RFI, TAGs combined with ABAC have surfaced as one of the most interesting ways to solve complex Swedish legal requirements regarding access control. In use cases like that one would like want/need to have some ways of adding tags in the same atomic transaction as adding/modifying COMPOSITIONs (and likely other versioned objects).

• A JSON (and likely an XML) serialisation format for ITEM_TAG needs to be specified. (Perhaps it already exists?)

• An API to modify ITEM_TAGs independently of changes to versioned objects (for non-atomic use cases) is needed. Perhaps some validation rules also, e.g. not allowing tagging of non-existing objects?

• One possible way to modify the REST spec to optionally allow combined tag+composition atomic modifications is to allow contributing also ITEM_TAG objects in the .../contribution POST call.

• Also it would be good if the …/composition API endpoint had some convenient way of optionally setting/modifying tags atomically together with the composition creation/change, perhaps via http headers following existing patterns, so something like openEHR-ITEM_TAG: key="my_nice_key", value="...", target_path="..." (ITEM_TAG.target would be the current COMPOSTION and ITEM_TAG.owner would be the current EHR)

• Another important thing is how to standardise the API (headers?) for using tags for filtering and querying (as defined in the tag “semantics” section). Adding stuff to AQL right now might be contentious, but allowing optional filtering via http-headers in the …/query API could be a fairly easy thing to define and add as an optional feature to the REST ITS. Perhaps DIPS, Better and others using already using TAGS could describe what filtering operations you support and how?

REST WG:

• POST|PUT|GET|DELETE /v1/ehr/{ehr_id}/(composition|folder..)/{version_uid}/tags[/{tag_key}[/{target_path}]] - Update tags on a COMPOSITION (and FOLDERs?). Existing tags will be replaced

• question: does the tags should also consider target_path? do we need to support case where more tags with same key is used for same target but with different target_path ?

• perhaps querying/filtering of tagged objects can be done like: GET /v1/ehr/{ehr_id}/(composition|folder..)?tags[key]=value

• adding tags on creation-time on compositions via headers in case of committing composition resource, and inline inside the contribution resource.

• GET /v1/ehr/{ehr_id}/tags - Get all tags currently defined in the CDR for the current EHR; Dips: GET /v1/tag/keys - Get all tags keys currently defined in the CDR (DIPS variant)

• Seref: maybe support tag incrementally, i.e. allow it to be used in Composition endpoint but not allow the full constraint semantics for tag to be used for aql because it may make it difficult for the implementers to apply the tag constraint to aql results (what if the tag.target_path is not in the SELECT OF AQL?)

• Sidharth: What will happen if a composition is created with a tag atomically during POST, but is updated using PUT without the tags using the API

• Sidharth/Erik: Strategy for filtering based on tags: 

  • OR tags: composition?tag=key1,key2

  • AND tags: composition?tag=key1&tag=key2

• What should happen when we update a composition and the tags are pointing to a specific (previous) version, or to a path that does not exists inside the composition

• Erik: perhaps we should add an invariant, stating that a path should be only used when the target is a version<T>.

• Erik: should we support logic not() on query params?

See also