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

Description

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/development/ehr.html.

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
optional

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

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

See ITEM_STRUCTURE schema details.

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 <uuid>
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
optional

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

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

See ITEM_STRUCTURE schema details.

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 <uuid>
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.

When there are ITEM_TAGs associated with the retrieved EHR_STATUS, they will be returned as openehr-item-tag response header.

path Parameters
ehr_id
required
string <uuid>
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.

When there are ITEM_TAGs associated with the retrieved EHR_STATUS, they will be returned as openehr-item-tag response header.

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

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string <datetime>
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.

A list of ITEM_TAGs can be associated with the updated EHR_STATUS, in which case a openehr-item-tag request header is needed to be set as well. The corresponding response header will return ITEM_TAGs as they were set by the server.

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 <uuid>
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.

Array of objects (UPDATE_ITEM_TAG)
Example: key="category",value="final"; key="flag",value="follow-up",target_path="/composition/start_time/value"

The (semicolon-separated) list of all ITEM_TAG to be set or updated and associated with the given VERSION or VERSIONED_OBJECT.

Request Body schema: application/json
required

The new EHR_STATUS.

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

See ITEM_STRUCTURE schema details.

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 <uuid>
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 <uuid>
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 <uuid>
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string <datetime>
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 <uuid>
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.

A list of ITEM_TAGs can be associated with the COMPOSITION, in which case a openehr-item-tag request header is needed to be set as well. The corresponding response header will return ITEM_TAGs as they were set by the server.

path Parameters
ehr_id
required
string <uuid>
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.

Array of objects (UPDATE_ITEM_TAG)
Example: key="category",value="final"; key="flag",value="follow-up",target_path="/composition/start_time/value"

The (semicolon-separated) list of all ITEM_TAG to be set or updated and associated with the given VERSION or VERSIONED_OBJECT.

Request Body schema: application/json
required

The COMPOSITION.

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

See CONTENT_ITEM schema details.

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.

When there are ITEM_TAGs associated with the retrieved COMPOSITION, they will be returned as openehr-item-tag response header.

path Parameters
ehr_id
required
string <uuid>
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 <datetime>
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.

A list of ITEM_TAGs can be associated with the updated COMPOSITION, in which case a openehr-item-tag request header is needed to be set as well. The corresponding response header will return ITEM_TAGs as they were set by the server.

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

EHR identifier taken from EHR.ehr_id.value.

uid_based_id
required
string <uuid>
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.

Array of objects (UPDATE_ITEM_TAG)
Example: key="category",value="final"; key="flag",value="follow-up",target_path="/composition/start_time/value"

The (semicolon-separated) list of all ITEM_TAG to be set or updated and associated with the given VERSION or VERSIONED_OBJECT.

Request Body schema: application/json
required

The new COMPOSITION.

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

See CONTENT_ITEM schema details.

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 <uuid>
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 <uuid>
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

versioned_object_uid
required
string <uuid>
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 <uuid>
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

versioned_object_uid
required
string <uuid>
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 <uuid>
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

VERSIONED_COMPOSITION identifier taken from VERSIONED_COMPOSITION.uid.value.

query Parameters
version_at_time
string <datetime>
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 <uuid>
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

versioned_object_uid
required
string <uuid>
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 <uuid>
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
required

The directory.

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

See ITEM_STRUCTURE schema details.

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 <uuid>
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
required

The new directory.

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

See ITEM_STRUCTURE schema details.

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 <uuid>
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

Response samples

Content type
application/json
{
  • "message": "Error message",
  • "validationErrors": [
    ]
}

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 <uuid>
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

query Parameters
version_at_time
string <datetime>
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 <uuid>
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 <uuid>
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
required

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 <uuid>
Example: 7d44b88c-4199-4bad-97dc-d78268e01398

EHR identifier taken from EHR.ehr_id.value.

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

The CONTRIBUTION uid.

Responses

Response samples

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

ITEM_TAG

Management of ITEM_TAG resources.

Get EHR tags

Retrieves the list of ITEM_TAG resources associated with any target VERSION or VERSIONED_OBJECT within the EHR identified by ehr_id.

This list can be filtered by the given one or more tag_key, tag_value, tag_target_path query parameters. In case no such parameter is provided then all ITEM_TAG will be retrieved.

This will return an empty list when there is no matching ITEM_TAG associated with any target within given EHR.

More then one ITEM_TAG may be associated with a single target, in which case they are uniquely identified by their key and target_path pair attributes.

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

EHR identifier taken from EHR.ehr_id.value.

query Parameters
tag_key
string
Example: tag_key=flag
tag_value
string
Example: tag_value=follow-up
tag_target_path
string
Example: tag_target_path=/context/start_time/value

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get COMPOSITION tags

Retrieves the list of all ITEM_TAG resources associated with a given target COMPOSITION version or VERSIONED_COMPOSITION identified by uid_based_id and owned by 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 get the tags of a particular (target) version of the COMPOSITION version (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 get the tags of the target VERSIONED_COMPOSITION container, which semantically are equivalent to tags targeting the latest version.

This will return an empty list when there is no ITEM_TAG associated with the given target.

More then one ITEM_TAG may be associated with a single target COMPOSITION or VERSIONED_COMPOSITION, in which case they are uniquely identified by their key and target_path pair attributes.

path Parameters
ehr_id
required
string <uuid>
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).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update COMPOSITION tags

Updates the list of all ITEM_TAG resources associated with a given target COMPOSITION version or VERSIONED_COMPOSITION identified by uid_based_id and owned by 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 update the tags of a particular COMPOSITION version (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 update the tags of the target VERSIONED_COMPOSITION container, which semantically are equivalent to tags targeting the latest version.

Providing an empty list will effectively remove all ITEM_TAG associated with the given target.

More then one ITEM_TAG may be associated with a single target, in which case they are uniquely identified by their key and target_path pair attributes.

path Parameters
ehr_id
required
string <uuid>
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).

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
required
Array
key
required
string

Tag key (identifier)

value
string

Tag value

target_path
string

An AQL path withing the target used to tag a fine-grained element

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Delete COMPOSITION tags

Deletes the ITEM_TAG resource(s) identified by tag_key, associated with a given target COMPOSITION version or VERSIONED_COMPOSITION identified by uid_based_id and owned by 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 delete the tags a particular (target) version of the COMPOSITION version (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 delete the tags of the target VERSIONED_COMPOSITION container, which semantically are equivalent to tags targeting the latest version.

path Parameters
ehr_id
required
string <uuid>
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).

key
required
string
Example: flag

The ITEM_TAG key.

Responses

Get EHR_STATUS tags

Retrieves the list of all ITEM_TAG resources associated with a given target EHR_STATUS version or VERSIONED_EHR_STATUS identified by uid_based_id and owned by 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 get the tags of a particular (target) version of the EHR_STATUS version (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 get the tags of the target VERSIONED_EHR_STATUS container, which semantically are equivalent to tags targeting the latest version.

This will return an empty list when there is no ITEM_TAG associated with the given target.

More then one ITEM_TAG may be associated with a single target EHR_STATUS or VERSIONED_EHR_STATUS, in which case they are uniquely identified by their key and target_path pair attributes.

path Parameters
ehr_id
required
string <uuid>
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).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update EHR_STATUS tags

Updates the list of all ITEM_TAG resources associated with a given target EHR_STATUS version or VERSIONED_EHR_STATUS identified by uid_based_id and owned by 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 update the tags of a particular EHR_STATUS version (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 update the tags of the target VERSIONED_EHR_STATUS container, which semantically are equivalent to tags targeting the latest version.

Providing an empty list will effectively remove all ITEM_TAG associated with the given target.

More then one ITEM_TAG may be associated with a single target, in which case they are uniquely identified by their key and target_path pair attributes.

path Parameters
ehr_id
required
string <uuid>
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).

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
required
Array
key
required
string

Tag key (identifier)

value
string

Tag value

target_path
string

An AQL path withing the target used to tag a fine-grained element

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Delete EHR_STATUS tags

Deletes the ITEM_TAG resource(s) identified by tag_key, associated with a given target EHR_STATUS version or VERSIONED_EHR_STATUS identified by uid_based_id and owned by 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 delete the tags a particular (target) version of the EHR_STATUS version (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 delete the tags of the target VERSIONED_EHR_STATUS container, which semantically are equivalent to tags targeting the latest version.

path Parameters
ehr_id
required
string <uuid>
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).

key
required
string
Example: flag

The ITEM_TAG key.

Responses

CONTENT_ITEM

The abstract CONTENT_ITEM class:

_type
required
string
required
object (DV_TEXT)
archetype_node_id
required
string
object (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
object (PARTY_PROXY)
object (PARTY_PROXY)
data
required
object (ITEM_STRUCTURE)

See ITEM_STRUCTURE schema details.

Example
{
  • "_type": "ADMIN_ENTRY",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "language": {
    },
  • "encoding": {
    },
  • "other_participations": [
    ],
  • "workflow_id": {
    },
  • "subject": {
    },
  • "provider": {
    },
  • "data": { }
}

ITEM

The abstract ITEM class:

_type
string
required
object (DV_TEXT)
archetype_node_id
required
string
object (UID_BASED_ID)
Array of objects (LINK)
object (ARCHETYPED)
object (FEEDER_AUDIT)
object (DV_CODED_TEXT)
object (DATA_VALUE)
object (DV_TEXT)
Example
{
  • "_type": "ELEMENT",
  • "name": {
    },
  • "archetype_node_id": "string",
  • "uid": {
    },
  • "links": [
    ],
  • "archetype_details": {
    },
  • "feeder_audit": {
    },
  • "null_flavour": {
    },
  • "value": {
    },
  • "null_reason": {
    }
}

ITEM_STRUCTURE

The abstract ITEM_STRUCTURE class:

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