API docs by Redocly

EHR API (latest)

Specifications Editorial Committee openEHR: info@openehr.org URL: https://specifications.openehr.org/ License: Creative Commons Attribution-NoDerivs 3.0 Unported
© 2003 - 2022 The openEHR Foundation
The openEHR Foundation is an independent, non-profit foundation, facilitating the sharing of health records by consumers and clinicians via open specifications, clinical models and open platform implementations.
Licence image Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/
Support Issues: Problem Reports
Web: specifications.openEHR.org

Amendment Record

Issue Details Raiser, Implementer Completed
Release-1.0.3
5.1 SPECITS-66: Migrate REST API specs to OpenAPI Specification S Iancu 19 Dec 2022
Release-1.0.2
4.2 SPECITS-41: Add double quotes to ETag and If-Match headers S Iancu 21 Mar 2021
4.1 SPECITS-49: Describing Resource Identification; add clarification over getting COMPOSITIONs by with `version_uid` vs `versioned_object_uid` J Smolka, M Polajnar, S Iancu 08 Mar 2021
4.0 SPECITS-52: Fix wrong example on revision history of the VERSIONED_COMPOSITION and VERSIONED_EHR_STATUS J Smolka, S Iancu 06 Mar 2021
Release-1.0.1
3.2 SPECITS-38: Fix response status code for semantic validation errors (fixes also SPECPR-298) P Pazos, S Iancu 01 Oct 2019
3.1 SPECITS-40: Fix and improve documentation on EHR (fixes also SPECPR-312) P Pazos, S Iancu 28 Sep 2019
3.0 SPECITS-32: Fix typos and minor documentary errors (fixes SPECPR-253, SPECPR-255, SPECPR-298, SPECPR-333, SPECPR-337) J Smolka, P Pazos, E Sundvall, T Beale, S Iancu 1 Sep 2019
2.2 SPECITS-24: Added changelog J Smolka, S Iancu 12 May 2019
SPECITS-25, SPECITS-29: Change layout and structure J Smolka, S Iancu 12 May 2019
2.1 Update links to new openEHR specifications website S Iancu 16 Dec 2018
Release-1.0.0

Intro

Acknowledgements

Editor

  • Sebastian Iancu, Architect, Code24, Netherlands

Contributors

This specification benefited from wide formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following people for their contributions.

  • Birger Haarbrandt, MSc, Peter L. Reichertz Institut for Medical Informatics (PLRI), Germany
  • Bjørn Næss, DIPS, Norway
  • Bostjan Lah, Senior Architect, Better, Slovenia
  • Erik Sundvall, Information Architect at Karolinska University Hospital, Sweden
  • Heath Frankel, Ocean Informatics, Australia
  • Ian McNicoll MD, FreshEHR, UK
  • Jake Smolka, Software Engineer, Better, Slovenia
  • Matija Polajnar, PhD, Software Engineer, Better, Slovenia
  • Pablo Pazos Gutierrez, Senior engineer, CaboLabs, Uruguay
  • Rong Chen MD, PhD, Cambio Healthcare Systems, Sweden
  • Sebastian Iancu, Architect, Code24, Netherlands
  • Seref Arikan, MEcon, Ocean Informatics UK, Centre for Health Informatics and Multi-professional Education (CHIME) UK
  • Thomas Beale, Ars Semantica UK, openEHR Foundation Management Board

Trademarks

Preface

Purpose

This specification describes service endpoints, resources and operations as well as details of requests and responses that interacts with EHR openEHR API in a RESTful manner.

Prerequisite documents for reading this document include:

Related documents include:

Status

This specification is in the STABLE state, and can be downloaded as OpenAPI specification file (in YAML format) for validation, or for code generators. Users are encouraged to comment on and/or advise on these paragraphs as well as the main content.

The development version of this document can be found at https://specifications.openehr.org/releases/ITS-REST/latest/ehr.html.

Feedback

Feedback may be provided on the Implementation Technology Specifications forum.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the ITS component Change Request tracker.

Conformance

tbd.

EHR

Management of EHRs. Actions upon resources of this group are also formally described in the I_EHR_SERVICE Abstract Service Model interface.

Create EHR

Create a new EHR with an auto-generated identifier.

An EHR_STATUS resource needs to be always created and committed in the new EHR. This resource MAY be also supplied by the client as the request body. If not supplied, a default EHR_STATUS will be used by the service with following attributes:

  • is_queryable: true
  • is_modifiable: true
  • subject: a PARTY_SELF object

All other required EHR attributes and resources will be automatically created as needed by the EHR creation semantics.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json

An EHR_STATUS resource MAY be also supplied by the client as the request body.

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "EHR_STATUS"
required
any (PARTY_PROXY)
is_queryable
required
boolean
Default: true
is_modifiable
required
boolean
Default: true
other_details
object (ITEM_STRUCTURE)

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Response samples

Content type
application/json
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

Get EHR by subject id

Retrieve the EHR with the specified subject_id and subject_namespace.

These subject parameters will be matched against EHR's EHR_STATUS.subject.external_ref.id.value and EHR_STATUS.subject.external_ref.namespace values.

query Parameters
subject_id
required
string
Example: subject_id=ins01

The EHR subject id.

subject_namespace
required
string
Example: subject_namespace=examples

The EHR subject id namespace.

Responses

Response samples

Content type
application/json
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

Create EHR with id

Create a new EHR with the specified ehr_id identifier.

The value of the ehr_id unique identifier MUST be valid HIER_OBJECT_ID value. It is strongly RECOMMENDED that an UUID always be used for this.

An EHR_STATUS resource needs to be always created and committed in the new EHR. This resource MAY be also supplied by the client as the request body. If not supplied, a default EHR_STATUS will be used by the service with following attributes:

  • is_queryable: true
  • is_modifiable: true
  • subject: a PARTY_SELF object

All other required EHR attributes and resources will be automatically created as needed by the EHR creation semantics.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json

An EHR_STATUS resource MAY be also supplied by the client as the request body.

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "EHR_STATUS"
required
any (PARTY_PROXY)
is_queryable
required
boolean
Default: true
is_modifiable
required
boolean
Default: true
other_details
object (ITEM_STRUCTURE)

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Response samples

Content type
application/json
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

Get EHR by id

Retrieve the EHR with the specified ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

Responses

Response samples

Content type
application/json
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

EHR_STATUS

Management of EHR_STATUS and VERSIONED_EHR_STATUS resources. Actions upon resources of this group are also formally described in the I_EHR_STATUS Abstract Service Model interface.

Get EHR_STATUS by version id

Retrieves a particular version of the EHR_STATUS identified by version_uid and associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

version_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2

VERSION identifier taken from VERSION.uid.value.

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Get EHR_STATUS at time

Retrieves a version of the EHR_STATUS associated with the EHR identified by ehr_id.

If version_at_time is supplied, retrieves the version extant at specified time, otherwise retrieves the latest EHR_STATUS version.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Update EHR_STATUS

Updates EHR_STATUS associated with the EHR identified by ehr_id.

The existing latest version_uid of EHR_STATUS resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

The response will contain the updated EHR_STATUS resource when the Prefer header has a value of return=representation.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
If-Match
required
string
Example: "6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"

Header to make the request conditional. Together with ETag request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions"). The format is always an version_uid identifier enclosed by double quotes. The operation will be performed only if the existing latest version_uid of the resource (i.e. the preceding_version_uid) matches this header's value.

Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json

The new EHR_STATUS.

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "EHR_STATUS"
required
any (PARTY_PROXY)
is_queryable
required
boolean
Default: true
is_modifiable
required
boolean
Default: true
other_details
object (ITEM_STRUCTURE)

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

Get versioned EHR_STATUS

Retrieves a VERSIONED_EHR_STATUS associated with an EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

Responses

Response samples

Content type
application/json
{
  • "uid": {
    },
  • "owner_id": {
    },
  • "time_created": {
    }
}

Get versioned EHR_STATUS revision history

Retrieves revision history of the VERSIONED_EHR_STATUS associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get versioned EHR_STATUS version at time

Retrieves a VERSION from the VERSIONED_EHR_STATUS associated with the EHR identified by ehr_id.

If version_at_time is supplied, retrieves the VERSION extant at specified time, otherwise retrieves the latest VERSION.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

Responses

Response samples

Content type
application/json
Example
{
  • "_type": "ORIGINAL_VERSION",
  • "contribution": {
    },
  • "signature": "string",
  • "commit_audit": {
    },
  • "data": {
    },
  • "uid": {
    },
  • "preceding_version_uid": {
    },
  • "other_input_version_uids": [
    ],
  • "lifecycle_state": {
    },
  • "attestations": [
    ]
}

Get versioned EHR_STATUS version by id

Retrieves a VERSION identified by version_uid of an EHR_STATUS associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

version_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2

VERSION identifier taken from VERSION.uid.value.

Responses

Response samples

Content type
application/json
Example
{
  • "_type": "ORIGINAL_VERSION",
  • "contribution": {
    },
  • "signature": "string",
  • "commit_audit": {
    },
  • "data": {
    },
  • "uid": {
    },
  • "preceding_version_uid": {
    },
  • "other_input_version_uids": [
    ],
  • "lifecycle_state": {
    },
  • "attestations": [
    ]
}

COMPOSITION

Management of COMPOSITION and VERSIONED_COMPOSITION resources. Actions upon resources of this group are also formally described in the I_EHR_COMPOSITION Abstract Service Model interface.

Create COMPOSITION

Creates the first version of a new COMPOSITION in the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json

The COMPOSITION.

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "COMPOSITION"
required
object (CODE_PHRASE)
required
object (CODE_PHRASE)
required
object (DV_CODED_TEXT)
required
object (EVENT_CONTEXT)
required
any (PARTY_PROXY)
content
required
Array of objects (CONTENT_ITEM)

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Get COMPOSITION

Retrieves a version of the COMPOSITION identified by uid_based_id and associated with the EHR identified by ehr_id.

The uid_based_id can take a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a version_uid), or a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid). The former is used to retrieve a specific known version of the COMPOSITION (e.g. one identified by 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1), whereas the later (e.g. an identifier like 8849182c-82ad-4088-a07f-48ead4180515) is be used to retrieve a version from the version container whenever the version_tree_id is unknown or irrelevant (such as when most recent version is requested).

When the uid_based_id has the form of a HIER_OBJECT_ID, if the version_at_time is supplied, retrieves the version extant at specified time, otherwise retrieves the latest COMPOSITION version.

See Resource identification for more details about the identifiers usage and meaning.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

uid_based_id
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

An abstract identifier: it can take a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a version_uid), or a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid).

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Update COMPOSITION

Updates COMPOSITION identified by uid_based_id and associated with the EHR identified by ehr_id.

The uid_based_id can take only a form of an HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid).

If the request body already contains a COMPOSITION.uid.value, it must match the uid_based_id in the URL.

The existing latest version_uid of COMPOSITION resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

uid_based_id
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515

An identifier in a form of a HIER_OBJECT_ID identifier taken from VERSIONED_OBJECT.uid.value (i.e. a versioned_object_uid).

header Parameters
If-Match
required
string
Example: "6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"

Header to make the request conditional. Together with ETag request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions"). The format is always an version_uid identifier enclosed by double quotes. The operation will be performed only if the existing latest version_uid of the resource (i.e. the preceding_version_uid) matches this header's value.

Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json

The new COMPOSITION.

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "COMPOSITION"
required
object (CODE_PHRASE)
required
object (CODE_PHRASE)
required
object (DV_CODED_TEXT)
required
object (EVENT_CONTEXT)
required
any (PARTY_PROXY)
content
required
Array of objects (CONTENT_ITEM)

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

Delete COMPOSITION

Deletes the COMPOSITION identified by uid_based_id and associated with the EHR identified by ehr_id.

The uid_based_id MUST be in a form of an OBJECT_VERSION_ID identifier taken from the last (most recent) VERSION.uid.value, representing the preceding_version_uid to be deleted.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

uid_based_id
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

An identifier in a form of an OBJECT_VERSION_ID identifier taken from VERSION.uid.value (i.e. a version_uid).

Responses

Get versioned COMPOSITION

Retrieves a VERSIONED_COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

versioned_object_uid
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

Responses

Response samples

Content type
application/json
{
  • "uid": {
    },
  • "owner_id": {
    },
  • "time_created": {
    }
}

Get versioned COMPOSITION revision history

Retrieves revision history of the VERSIONED_COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

versioned_object_uid
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get versioned COMPOSITION version at time

Retrieves a VERSION from the VERSIONED_COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id.

If version_at_time is supplied, retrieves the VERSION extant at specified time, otherwise retrieves the latest VERSION.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

versioned_object_uid
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

Responses

Response samples

Content type
application/json
Example
{
  • "_type": "ORIGINAL_VERSION",
  • "contribution": {
    },
  • "signature": "string",
  • "commit_audit": {
    },
  • "data": {
    },
  • "uid": {
    },
  • "preceding_version_uid": {
    },
  • "other_input_version_uids": [
    ],
  • "lifecycle_state": {
    },
  • "attestations": [
    ]
}

Get versioned COMPOSITION version by id

Retrieves a VERSION identified by version_uid of a VERSIONED_COMPOSITION identified by versioned_object_uid and associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

versioned_object_uid
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

version_uid
required
string
Example: 8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1

VERSION identifier taken from VERSION.uid.value.

Responses

Response samples

Content type
application/json
Example
{
  • "_type": "ORIGINAL_VERSION",
  • "contribution": {
    },
  • "signature": "string",
  • "commit_audit": {
    },
  • "data": {
    },
  • "uid": {
    },
  • "preceding_version_uid": {
    },
  • "other_input_version_uids": [
    ],
  • "lifecycle_state": {
    },
  • "attestations": [
    ]
}

DIRECTORY

Management of the directory FOLDER resource. Actions upon resources of this group are also formally described in the I_EHR_DIRECTORY Abstract Service Model interface.

Create directory

Creates a new directory FOLDER associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json

The directory.

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "FOLDER"
Array of objects (OBJECT_REF)
folders
Array of objects (FOLDER)
details
object (ITEM_STRUCTURE)

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Update directory

Updates directory FOLDER associated with the EHR identified by ehr_id.

The existing latest version_uid of directory FOLDER resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
If-Match
required
string
Example: "6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"

Header to make the request conditional. Together with ETag request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions"). The format is always an version_uid identifier enclosed by double quotes. The operation will be performed only if the existing latest version_uid of the resource (i.e. the preceding_version_uid) matches this header's value.

Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json

The new directory.

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "FOLDER"
Array of objects (OBJECT_REF)
folders
Array of objects (FOLDER)
details
object (ITEM_STRUCTURE)

Responses

Request samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Delete directory

Deletes directory FOLDER associated with the EHR identified by ehr_id.

The existing latest version_uid of directory FOLDER resource (i.e. the preceding_version_uid) must be specified in the If-Match header.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
If-Match
required
string
Example: "6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::1"

Header to make the request conditional. Together with ETag request tag, it helps to prevent simultaneous updates of a resource from overwriting each other ("mid-air collisions"). The format is always an version_uid identifier enclosed by double quotes. The operation will be performed only if the existing latest version_uid of the resource (i.e. the preceding_version_uid) matches this header's value.

Responses

Get folder in directory version at time

Retrieves the version of the directory FOLDER associated with the EHR identified by ehr_id. If version_at_time is supplied, retrieves the version extant at specified time, otherwise retrieves the latest directory FOLDER version.

If path is supplied, retrieves from the directory only the sub-FOLDER that is associated with that path.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string
Example: version_at_time=2015-01-20T19:30:22.765+01:00

A given time in the extended ISO 8601 format.

path
string
Example: path=episodes/a/b/c

A path to a sub-folder; consists of slash-separated values of the name attribute of FOLDERs in the directory.

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

Get folder in directory version

Retrieves a particular version of the directory FOLDER identified by version_uid and associated with the EHR identified by ehr_id.

If path is supplied, retrieves from the directory only the sub-FOLDER that is associated with that path.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

version_uid
required
string
Example: 6cb19121-4307-4648-9da0-d62e4d51f19b::openEHRSys.example.com::2

VERSION identifier taken from VERSION.uid.value.

query Parameters
path
string
Example: path=episodes/a/b/c

A path to a sub-folder; consists of slash-separated values of the name attribute of FOLDERs in the directory.

Responses

Response samples

Content type
application/json
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

CONTRIBUTION

Management of CONTRIBUTION resource. Actions upon resources of this group are also formally described in the I_EHR_CONTRIBUTION Abstract Service Model interface.

Create CONTRIBUTION

We will use the relaxed CONTRIBUTION with the following optional attributes:

  • uid: when provided, it will be accepted in case is not in-use, otherwise error will be returned
  • audit.time_committed: server will always set it
  • audit.system_id: when provided, it will be validated
path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

header Parameters
Prefer
string
Default: return=minimal
Enum: "return=representation" "return=minimal"

Request header to indicate the preference over response details. The response will contain the entire resource when the Prefer header has a value of return=representation.

Request Body schema: application/json

The CONTRIBUTION.

object (HIER_OBJECT_ID)
required
Array of objects (UPDATE_VERSION)
required
object (UPDATE_AUDIT)

The set of attributes required to document the committal of an information item to a repository. Used by the server to create an AUDIT_DETAILS object.

Responses

Request samples

Content type
application/json
{
  • "uid": {
    },
  • "versions": [
    ],
  • "audit": {
    }
}

Response samples

Content type
application/json
{
  • "uid": {
    },
  • "versions": [
    ],
  • "audit": {
    }
}

Get CONTRIBUTION by id

Retrieves a CONTRIBUTION identified by contribution_uid and associated with the EHR identified by ehr_id.

path Parameters
ehr_id
required
string
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

contribution_uid
required
string
Example: 0826851c-c4c2-4d61-92b9-410fb8275ff0

The CONTRIBUTION uid.

Responses

Response samples

Content type
application/json
{
  • "uid": {
    },
  • "versions": [
    ],
  • "audit": {
    }
}

EHR

This resource is formally specified in Reference Model as the EHR class.

object (HIER_OBJECT_ID)
object (HIER_OBJECT_ID)
object (OBJECT_REF)
object (OBJECT_REF)
object (DV_DATE_TIME)
{
  • "system_id": {
    },
  • "ehr_id": {
    },
  • "ehr_status": {
    },
  • "ehr_access": {
    },
  • "time_created": {
    }
}

EHR_STATUS

The following resources are formally specified in the Reference Model as EHR_STATUS and VERSIONED_EHR_STATUS classes.

The EHR_STATUS resource:

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "EHR_STATUS"
required
any (PARTY_PROXY)
is_queryable
required
boolean
Default: true
is_modifiable
required
boolean
Default: true
other_details
object (ITEM_STRUCTURE)
{
  • "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
  • "name": {
    },
  • "uid": {
    },
  • "subject": {
    },
  • "is_queryable": true,
  • "is_modifiable": true
}

The VERSIONED_EHR_STATUS resource:

_type
string
Default: "VERSIONED_EHR_STATUS"
required
object (HIER_OBJECT_ID)
required
object (OBJECT_REF)
required
object (DV_DATE_TIME)
{
  • "uid": {
    },
  • "owner_id": {
    },
  • "time_created": {
    }
}

COMPOSITION

The following resources are formally specified in the Reference Model as COMPOSITION and VERSIONED_COMPOSITION classes.

The COMPOSITION resource:

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "COMPOSITION"
required
object (CODE_PHRASE)
required
object (CODE_PHRASE)
required
object (DV_CODED_TEXT)
required
object (EVENT_CONTEXT)
required
any (PARTY_PROXY)
content
required
Array of objects (CONTENT_ITEM)
{
  • "archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
  • "name": {
    },
  • "uid": {
    },
  • "archetype_details": {
    },
  • "language": {
    },
  • "territory": {
    },
  • "category": {
    },
  • "composer": {
    },
  • "context": {
    },
  • "content": [ ]
}

The abstract CONTENT_ITEM class, used in COMPOSITION:

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
required
object (CODE_PHRASE)
required
object (CODE_PHRASE)
Array of objects (PARTICIPATION)
object (OBJECT_REF)
required
any (PARTY_PROXY)
any (PARTY_PROXY)
_type
required
string
data
required
object (ITEM_STRUCTURE)
Example
{
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "language": {
    },
  • "encoding": {
    },
  • "other_participations": [
    ],
  • "workflow_id": {
    },
  • "subject": {
    },
  • "provider": {
    },
  • "_type": "ADMIN_ENTRY",
  • "data": { }
}

The abstract ITEM_STRUCTURE class, used in CONTENT_ITEM:

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "ITEM_SINGLE"
required
object (ELEMENT)
Example
{
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "_type": "ITEM_SINGLE",
  • "item": {
    }
}

The VERSIONED_COMPOSITION resource:

_type
string
Default: "VERSIONED_COMPOSITION"
required
object (HIER_OBJECT_ID)
required
object (OBJECT_REF)
required
object (DV_DATE_TIME)
{
  • "uid": {
    },
  • "owner_id": {
    },
  • "time_created": {
    }
}

DIRECTORY

This resource is formally specified in Reference Model in the directory section, using FOLDER class.

required
any (DV_TEXT)
archetype_node_id
required
string
any (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
_type
string
Default: "FOLDER"
Array of objects (OBJECT_REF)
folders
Array of objects (FOLDER)
details
object (ITEM_STRUCTURE)
{
  • "archetype_node_id": "openEHR-EHR-FOLDER.directory.v1",
  • "name": {
    },
  • "uid": {
    },
  • "items": [ ],
  • "folders": [ ]
}

CONTRIBUTION

The following resources are formally specified in the Reference Model as the CONTRIBUTION class.

A new CONTRIBUTION to be committed:

object (HIER_OBJECT_ID)
required
Array of objects (UPDATE_VERSION)
required
object (UPDATE_AUDIT)

The set of attributes required to document the committal of an information item to a repository. Used by the server to create an AUDIT_DETAILS object.

{
  • "uid": {
    },
  • "versions": [
    ],
  • "audit": {
    }
}

A retrieved CONTRIBUTION:

required
object (HIER_OBJECT_ID)
required
Array of objects (OBJECT_REF)
required
object (AUDIT_DETAILS)

The set of attributes required to document the committal of an information item to a repository.

{
  • "uid": {
    },
  • "versions": [
    ],
  • "audit": {
    }
}