EHR endpoint responds with ehr_status as type "EHR_STATUS" instead of "OBJECT_REF"

[joshuagrisham-karolinska]

Hello! I have been running some tests against different openEHR implementations using a fork of the test suite at https://github.com/ehrbase/integration-tests and have stumbled on a few things that seem a bit "off" with EHRBase, so plan to submit some bugs to try and start the discussions going on them!

First is that from what I can tell (without at all being an "expert" on this) is that it seems like the ehr_status reference that is being returned from the /ehr endpoint in EHRBase is returning an instance of EHR_STATUS instead of an instance of OBJECT_REF

I understand that this might have quite a bit of impact/reach as it is a relatively fundamental thing here, so maybe it is good if someone can investigate this properly and make sure everything looks right compared to the spec vs not?

For example with the ehr_status attribute uid vs id, what I see in EHRBase is that a request to /ehr is returning this:

...
  "ehr_status": {
    "uid": "..."
    ...
  }
...

But from what I can see both in the REST API spec and the SM / BASE specification it seems like it should be id instead?

...
  "ehr_status": {
    "id": "..."
    ...
  }
...

Environment information

{
  "ehrbase_version": "0.25.0-SNAPSHOT",
  "openehr_sdk_version": "1.25.0-SNAPSHOT",
  "archie_version": "2.0.1",
  "jvm_version": "Eclipse Adoptium 17.0.6+10",
  "os_version": "Linux amd64 5.15.90.1-microsoft-standard-WSL2",
  "postgres_version": "PostgreSQL 13.4 on x86_64-pc-linux-musl, compiled by gcc (Alpine 10.3.1_git20210424) 10.3.1 20210424, 64-bit"
}

Steps to reproduce

Create an EHR using the REST API and fetch it using either:

• POST to /ehr with header Prefer: return=representation, or
• POST to /ehr then GET to /ehr/:ehr_id

(for example by runing the following command against the default EHRBase service from the docker-compose example)

curl --silent --request POST --header 'Prefer: return=representation' http://ehrbase-user:SuperSecretPassword@localhost:8080/ehrbase/rest/openehr/v1/ehr | jq .

Actual result

Response's ehr_status object seems to be of type EHR_STATUS and does not have all of the same attributes as OBJECT_REF (for example that $.ehr_status.uid is given instead of $.ehr_status.id)

{
  "system_id": {
    "_type": "HIER_OBJECT_ID",
    "value": "ae22c348-fe8b-455d-829f-0aaf104aa83b"
  },
  "ehr_id": {
    "_type": "HIER_OBJECT_ID",
    "value": "d04326aa-cbcf-42cc-91b7-8b54716f7bd7"
  },
  "ehr_status": {
    ... an EHR_STATUS instance is returned instead of an OBJECT_REF? ...
    "_type": "EHR_STATUS",
    "name": {
      "_type": "DV_TEXT",
      "value": "EHR Status"
    },
    "subject": {
      "_type": "PARTY_SELF"
    },
    "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
    "uid": {
      "_type": "HIER_OBJECT_ID",
      "value": "b80be12c-a97d-4d3d-95fb-ae65c02ca8fd::local.ehrbase.org::1"
    },
    "is_modifiable": true,
    "is_queryable": true
  },
  "time_created": {
    "_type": "DV_DATE_TIME",
    "value": "2023-03-13T10:28:19.950Z"
  }
}

Expected result

The ehr_status object in the response from /ehr should be an instance of OBJECT_REF instead, per the REST API specification.

Further information

I did not see it returned in the response, but wonder if there is any case for /ehr to return the ehr_access object, and if so, if it might have the same issue? As per the spec it is the same object type (OBJECT_REF) which should be returned there as well (and not EHR_ACCESS)

[sebastian-iancu]

Some references from the official openEHR specs over the years that might be also useful:

• 1.0.0 released in 2018 https://specifications.openehr.org/releases/ITS-REST/Release-1.0.0/ehr.html#ehr-ehr-post without example response
• 1.0.1 released in 2019 https://specifications.openehr.org/releases/ITS-REST/Release-1.0.1/ehr.html#ehr-ehr-post with example response
• 1.0.2 released in 2021 https://specifications.openehr.org/releases/ITS-REST/Release-1.0.2/ehr.html#ehr-ehr-post with example response
• 1.0.3 released in 2022 https://specifications.openehr.org/releases/ITS-REST/Release-1.0.3/ehr.html#tag/EHR/operation/ehr_create, with example, based on OAS 3.0 format

These were mentioning that "... The new EHR resource is returned in the body when the request's Prefer header value is return=representation, otherwise only headers are returned ...", which implies the RM structure of the EHR, for example:

{
  ...,
  "ehr_status": {
    "id": {
      "_type": "OBJECT_VERSION_ID",
      "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
    },
    "namespace": "local",
    "type": "EHR_STATUS"
  },
  ...
}

There is however another request-header controlling the resolve of the OBJECT_REFs in the response:

Prefer: return=representation, resolve_refs

Perhaps this is enabled by default in some implementations?!

This issue might be also related to a missmatch between REST API and outdated SM specifications around EHR vs EHR_SUMMARY resource.