Uri Package :: openEHR Specifications (Local Build)

Overview

The data_types.uri package includes two types used for referring to information resources. The DV_URI type allows data values which are references to objects on the world wide web to be created. Its specialisation, DV_EHR_URI, enables any element in an openEHR record to be identified in the same way as other objects on the web. The DV_EHR_URI type is convenient, because it is a string, like any other URI, and is therefore easily transportable and processable. Because it has its own scheme space, 'ehr', instances can be globally unique, as long as EHR identification is globally unique. DV_EHR_URIs are used to express all runtime paths in the EHR. The uri Package is illustrated below.

Figure 1. rm.data_types.uri package

Requirements

This package meets the requirement for a DATA_VALUE subtype which represents a W3C Uniform Resource Identifier (URI). A common example of where this might be used is to represent a reference to a clinical guideline or other justifying document associated with an intervention or treatment plan recorded in the EHR.

URIs are a superset of Uniform Resource Locators (URLs) (although the two are often confused, even within the W3C), and can be used to specify the location of any information item, regardless of its type, location or storage method, as long as a URI "scheme" exists for that type of information.

There is an additional requirement for a kind of URI that can point at an EHR data item, either inside the same EHR containing the link, or in another EHR. This is the basis of implementing logical references in the EHR and between EHRs.

Design

A simple design approach is used whereby a URI is represented as a String, and appropriate functions are defined to extract the various parts according to the syntax of URIs defined by Tim Berners-Lee (IETF RFC 3986). An EHR specific subtype is defined, whose scheme is 'ehr', and which contains further attributes enabling the instances of the type to record what kind of object they are referring to.

So-called 'plain-text URIs' that contain RFC-3986 forbidden characters such as spaces etc, are allowed on the basis of human readability, but must be RFC-3986 encoded prior to use in e.g. REST APIs or other contexts relying on machine-level conformance.

Definitions

The following symbolic definitions are used in the classes below.

Ehr_scheme: String = "ehr"

Class Descriptions

DV_URI Class

Definition
Effective
BMM
UML

Class	DV_URI
Description	A reference to an object which structurally conforms to the Universal Resource Identifier (URI) RFC-3986 standard. The reference is contained in the `value` attribute, which is a `String`. So-called 'plain-text URIs' that contain RFC-3986 forbidden characters such as spaces etc, are allowed on the basis that they need to be RFC-3986 encoded prior to use in e.g. REST APIs or other contexts relying on machine-level conformance.
Inherit	`DATA_VALUE`
Attributes	Signature	Meaning
1..1	value: `String`	Value of URI as a String. 'Plain-text' URIs are allowed, enabling better readability, but must be RFC-3986 encoded in use.
Functions	Signature	Meaning
1..1	scheme (): `String`	A distributed information 'space' in which information objects exist. The scheme simultaneously specifies an information space and a mechanism for accessing objects in that space. For example if scheme = "ftp", it identifies the information space in which all ftp-able objects exist, and also the application - ftp - which can be used to access them. Values may include: "ftp", "telnet", "mailto", etc. Refer to RFC-3986 for a full list.
1..1	path (): `String`	A string whose format is a function of the scheme. Identifies the location in <scheme>-space of an information entity. Typical values include hierarchical directory paths for any machine. For example, with scheme = "ftp", path might be `"/pub/images/image_01"`. The strings "." and ".." are reserved for use in the path. Paths may include internet/intranet location identifiers of the form: `sub_domain…domain`, e.g. `"info.cern.ch"`.
1..1	fragment_id (): `String`	A part of, a fragment or a sub-function within an object. Allows references to sub-parts of objects, such as a certain line and character position in a text object. The syntax and semantics are defined by the application responsible for the object.
1..1	query (): `String`	Query string to send to application implied by scheme and path. Enables queries to applications, including databases to be included in the URI. Supports any query meaningful to the server, including SQL.
Invariants	Value_valid: `not value.is_empty`

Class

DV_URI

Description

A reference to an object which structurally conforms to the Universal Resource Identifier (URI) RFC-3986 standard. The reference is contained in the value attribute, which is a String. So-called 'plain-text URIs' that contain RFC-3986 forbidden characters such as spaces etc, are allowed on the basis that they need to be RFC-3986 encoded prior to use in e.g. REST APIs or other contexts relying on machine-level conformance.

Inherit

DATA_VALUE

Attributes

Signature

Meaning

1..1

value: String

Value of URI as a String. 'Plain-text' URIs are allowed, enabling better readability, but must be RFC-3986 encoded in use.

Functions

Signature

Meaning

1..1

scheme (): String

A distributed information 'space' in which information objects exist. The scheme simultaneously specifies an information space and a mechanism for accessing objects in that space. For example if scheme = "ftp", it identifies the information space in which all ftp-able objects exist, and also the application - ftp - which can be used to access them. Values may include: "ftp", "telnet", "mailto", etc. Refer to RFC-3986 for a full list.

1..1

path (): String

A string whose format is a function of the scheme. Identifies the location in <scheme>-space of an information entity. Typical values include hierarchical directory paths for any machine. For example, with scheme = "ftp", path might be "/pub/images/image_01". The strings "." and ".." are reserved for use in the path. Paths may include internet/intranet location identifiers of the form: sub_domain…domain, e.g. "info.cern.ch".

1..1

fragment_id (): String

A part of, a fragment or a sub-function within an object. Allows references to sub-parts of objects, such as a certain line and character position in a text object. The syntax and semantics are defined by the application responsible for the object.

1..1

query (): String

Query string to send to application implied by scheme and path. Enables queries to applications, including databases to be included in the URI. Supports any query meaningful to the server, including SQL.

Invariants

Value_valid: not value.is_empty

DV_URI
A reference to an object which structurally conforms to the Universal Resource Identifier (URI) RFC-3986 standard. The reference is contained in the `value` attribute, which is a `String`. So-called 'plain-text URIs' that contain RFC-3986 forbidden characters such as spaces etc, are allowed on the basis that they need to be RFC-3986 encoded prior to use in e.g. REST APIs or other contexts relying on machine-level conformance.
Inherits: BASIC_DEFINITIONS, OPENEHR_DEFINITIONS, DATA_VALUE
Constants
BASIC_DEFINITIONS.CR: `Character = '\015'` [1..1]	Carriage return character.
BASIC_DEFINITIONS.LF: `Character = '\012'` [1..1]	Line feed character.
BASIC_DEFINITIONS.Any_type_name: `String = "Any"` [1..1]
BASIC_DEFINITIONS.Regex_any_pattern: `String = ".*"` [1..1]
BASIC_DEFINITIONS.Default_encoding: `String = "UTF-8"` [1..1]
BASIC_DEFINITIONS.None_type_name: `String = "None"` [1..1]
OPENEHR_DEFINITIONS.Local_terminology_id: `String = "local"` [1..1]	Predefined terminology identifier to indicate it is local to the knowledge resource in which it occurs, e.g. an archetype
Attributes
value: `String` [1..1]	Value of URI as a String. 'Plain-text' URIs are allowed, enabling better readability, but must be RFC-3986 encoded in use.
Functions
scheme (): `String` [1..1]	A distributed information 'space' in which information objects exist. The scheme simultaneously specifies an information space and a mechanism for accessing objects in that space. For example if scheme = "ftp", it identifies the information space in which all ftp-able objects exist, and also the application - ftp - which can be used to access them. Values may include: "ftp", "telnet", "mailto", etc. Refer to RFC-3986 for a full list.
path (): `String` [1..1]	A string whose format is a function of the scheme. Identifies the location in <scheme>-space of an information entity. Typical values include hierarchical directory paths for any machine. For example, with scheme = "ftp", path might be `"/pub/images/image_01"`. The strings "." and ".." are reserved for use in the path. Paths may include internet/intranet location identifiers of the form: `sub_domain…domain`, e.g. `"info.cern.ch"`.
fragment_id (): `String` [1..1]	A part of, a fragment or a sub-function within an object. Allows references to sub-parts of objects, such as a certain line and character position in a text object. The syntax and semantics are defined by the application responsible for the object.
query (): `String` [1..1]	Query string to send to application implied by scheme and path. Enables queries to applications, including databases to be included in the URI. Supports any query meaningful to the server, including SQL.
Invariants
Value_valid: `not value.is_empty`

DV_URI

A reference to an object which structurally conforms to the Universal Resource Identifier (URI) RFC-3986 standard. The reference is contained in the value attribute, which is a String. So-called 'plain-text URIs' that contain RFC-3986 forbidden characters such as spaces etc, are allowed on the basis that they need to be RFC-3986 encoded prior to use in e.g. REST APIs or other contexts relying on machine-level conformance.

Inherits: BASIC_DEFINITIONS, OPENEHR_DEFINITIONS, DATA_VALUE

Constants

BASIC_DEFINITIONS.CR: Character = '\015' [1..1]

Carriage return character.

BASIC_DEFINITIONS.LF: Character = '\012' [1..1]

Line feed character.

BASIC_DEFINITIONS.Any_type_name: String = "Any" [1..1]

BASIC_DEFINITIONS.Regex_any_pattern: String = ".*" [1..1]

BASIC_DEFINITIONS.Default_encoding: String = "UTF-8" [1..1]

BASIC_DEFINITIONS.None_type_name: String = "None" [1..1]

OPENEHR_DEFINITIONS.Local_terminology_id: String = "local" [1..1]

Predefined terminology identifier to indicate it is local to the knowledge resource in which it occurs, e.g. an archetype

Attributes

value: String [1..1]

Value of URI as a String. 'Plain-text' URIs are allowed, enabling better readability, but must be RFC-3986 encoded in use.

Functions

scheme (): String [1..1]

A distributed information 'space' in which information objects exist. The scheme simultaneously specifies an information space and a mechanism for accessing objects in that space. For example if scheme = "ftp", it identifies the information space in which all ftp-able objects exist, and also the application - ftp - which can be used to access them. Values may include: "ftp", "telnet", "mailto", etc. Refer to RFC-3986 for a full list.

path (): String [1..1]

A string whose format is a function of the scheme. Identifies the location in <scheme>-space of an information entity. Typical values include hierarchical directory paths for any machine. For example, with scheme = "ftp", path might be "/pub/images/image_01". The strings "." and ".." are reserved for use in the path. Paths may include internet/intranet location identifiers of the form: sub_domain…domain, e.g. "info.cern.ch".

fragment_id (): String [1..1]

A part of, a fragment or a sub-function within an object. Allows references to sub-parts of objects, such as a certain line and character position in a text object. The syntax and semantics are defined by the application responsible for the object.

query (): String [1..1]

Query string to send to application implied by scheme and path. Enables queries to applications, including databases to be included in the URI. Supports any query meaningful to the server, including SQL.

Invariants

Value_valid: not value.is_empty

{
    "name": "DV_URI",
    "documentation": "A reference to an object which structurally conforms to the Universal Resource Identifier (URI) RFC-3986 standard. The reference is contained in the `_value_` attribute, which is a `String`. So-called 'plain-text URIs' that contain RFC-3986 forbidden characters such as spaces etc, are allowed on the basis that they need to be RFC-3986 encoded prior to use in e.g. REST APIs or other contexts relying on machine-level conformance.",
    "ancestors": [
        "DATA_VALUE"
    ],
    "properties": {
        "value": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "value",
            "documentation": "Value of URI as a String. 'Plain-text' URIs are allowed, enabling better readability, but must be RFC-3986 encoded in use.",
            "is_mandatory": true,
            "type": "String"
        }
    },
    "functions": {
        "scheme": {
            "name": "scheme",
            "documentation": "A distributed information 'space' in which  information objects  exist. The scheme simultaneously specifies an information space and a mechanism for accessing objects in  that  space.  For  example  if  scheme  = \"ftp\", it identifies the information space in which  all  ftp-able objects  exist,  and also the application - ftp - which can be used to access them. Values may include: \"ftp\", \"telnet\", \"mailto\", etc. Refer to RFC-3986 for a full list. \n",
            "result": {
                "_type": "P_BMM_SIMPLE_TYPE",
                "type": "String"
            }
        },
        "path": {
            "name": "path",
            "documentation": "A string whose format is  a  function  of  the  scheme. Identifies   the   location  in  <scheme>-space  of  an information entity. Typical values include hierarchical directory  paths  for  any  machine.  For example, with scheme = \"ftp\", path might be `\"/pub/images/image_01\"`. The strings \".\" and \"..\" are reserved for use in the path. Paths may include internet/intranet location identifiers of the form: `sub_domain...domain`, e.g. `\"info.cern.ch\"`. ",
            "result": {
                "_type": "P_BMM_SIMPLE_TYPE",
                "type": "String"
            }
        },
        "fragment_id": {
            "name": "fragment_id",
            "documentation": "A part of, a  fragment  or  a  sub-function  within  an object. Allows references to sub-parts of objects, such as a certain line and character  position  in  a  text object. The  syntax  and semantics are defined by the application responsible for the object. \n",
            "result": {
                "_type": "P_BMM_SIMPLE_TYPE",
                "type": "String"
            }
        },
        "query": {
            "name": "query",
            "documentation": "Query string to send to application implied  by  scheme and  path.  Enables  queries  to applications, including databases  to  be  included in  the  URI. Supports any query meaningful to the server, including SQL. \n",
            "result": {
                "_type": "P_BMM_SIMPLE_TYPE",
                "type": "String"
            }
        }
    },
    "invariants": {
        "Value_valid": "not value.is_empty"
    }
}

DV_EHR_URI Class

Definition
Effective
BMM
UML

Class	DV_EHR_URI
Description	A `DV_EHR_URI` is a `DV_URI` which has the scheme name 'ehr', and which can only reference items in EHRs. Used to reference items in an EHR, which may be the same as the current EHR (containing this link), or another.
Inherit	`DV_URI`
Invariants	Scheme_valid: `scheme.is_equal (Ehr_scheme)`

Class

DV_EHR_URI

Description

A DV_EHR_URI is a DV_URI which has the scheme name 'ehr', and which can only reference items in EHRs.

Used to reference items in an EHR, which may be the same as the current EHR (containing this link), or another.

Inherit

DV_URI

Invariants

Scheme_valid: scheme.is_equal (Ehr_scheme)

DV_EHR_URI
A `DV_EHR_URI` is a `DV_URI` which has the scheme name 'ehr', and which can only reference items in EHRs. Used to reference items in an EHR, which may be the same as the current EHR (containing this link), or another.
Inherits: BASIC_DEFINITIONS, OPENEHR_DEFINITIONS, DATA_VALUE, DV_URI
Constants
BASIC_DEFINITIONS.CR: `Character = '\015'` [1..1]	Carriage return character.
BASIC_DEFINITIONS.LF: `Character = '\012'` [1..1]	Line feed character.
BASIC_DEFINITIONS.Any_type_name: `String = "Any"` [1..1]
BASIC_DEFINITIONS.Regex_any_pattern: `String = ".*"` [1..1]
BASIC_DEFINITIONS.Default_encoding: `String = "UTF-8"` [1..1]
BASIC_DEFINITIONS.None_type_name: `String = "None"` [1..1]
OPENEHR_DEFINITIONS.Local_terminology_id: `String = "local"` [1..1]	Predefined terminology identifier to indicate it is local to the knowledge resource in which it occurs, e.g. an archetype
Attributes
DV_URI.value: `String` [1..1]	Value of URI as a String. 'Plain-text' URIs are allowed, enabling better readability, but must be RFC-3986 encoded in use.
Functions
DV_URI.scheme (): `String` [1..1]	A distributed information 'space' in which information objects exist. The scheme simultaneously specifies an information space and a mechanism for accessing objects in that space. For example if scheme = "ftp", it identifies the information space in which all ftp-able objects exist, and also the application - ftp - which can be used to access them. Values may include: "ftp", "telnet", "mailto", etc. Refer to RFC-3986 for a full list.
DV_URI.path (): `String` [1..1]	A string whose format is a function of the scheme. Identifies the location in <scheme>-space of an information entity. Typical values include hierarchical directory paths for any machine. For example, with scheme = "ftp", path might be `"/pub/images/image_01"`. The strings "." and ".." are reserved for use in the path. Paths may include internet/intranet location identifiers of the form: `sub_domain…domain`, e.g. `"info.cern.ch"`.
DV_URI.fragment_id (): `String` [1..1]	A part of, a fragment or a sub-function within an object. Allows references to sub-parts of objects, such as a certain line and character position in a text object. The syntax and semantics are defined by the application responsible for the object.
DV_URI.query (): `String` [1..1]	Query string to send to application implied by scheme and path. Enables queries to applications, including databases to be included in the URI. Supports any query meaningful to the server, including SQL.
Invariants
DV_URI.Value_valid: `not value.is_empty`
Scheme_valid: `scheme.is_equal (Ehr_scheme)`

DV_EHR_URI

A DV_EHR_URI is a DV_URI which has the scheme name 'ehr', and which can only reference items in EHRs.

Used to reference items in an EHR, which may be the same as the current EHR (containing this link), or another.

Inherits: BASIC_DEFINITIONS, OPENEHR_DEFINITIONS, DATA_VALUE, DV_URI

Constants

BASIC_DEFINITIONS.CR: Character = '\015' [1..1]

Carriage return character.

BASIC_DEFINITIONS.LF: Character = '\012' [1..1]

Line feed character.

BASIC_DEFINITIONS.Any_type_name: String = "Any" [1..1]

BASIC_DEFINITIONS.Regex_any_pattern: String = ".*" [1..1]

BASIC_DEFINITIONS.Default_encoding: String = "UTF-8" [1..1]

BASIC_DEFINITIONS.None_type_name: String = "None" [1..1]

OPENEHR_DEFINITIONS.Local_terminology_id: String = "local" [1..1]

Predefined terminology identifier to indicate it is local to the knowledge resource in which it occurs, e.g. an archetype

Attributes

DV_URI.value: String [1..1]

Value of URI as a String. 'Plain-text' URIs are allowed, enabling better readability, but must be RFC-3986 encoded in use.

Functions

DV_URI.scheme (): String [1..1]

A distributed information 'space' in which information objects exist. The scheme simultaneously specifies an information space and a mechanism for accessing objects in that space. For example if scheme = "ftp", it identifies the information space in which all ftp-able objects exist, and also the application - ftp - which can be used to access them. Values may include: "ftp", "telnet", "mailto", etc. Refer to RFC-3986 for a full list.

DV_URI.path (): String [1..1]

A string whose format is a function of the scheme. Identifies the location in <scheme>-space of an information entity. Typical values include hierarchical directory paths for any machine. For example, with scheme = "ftp", path might be "/pub/images/image_01". The strings "." and ".." are reserved for use in the path. Paths may include internet/intranet location identifiers of the form: sub_domain…domain, e.g. "info.cern.ch".

DV_URI.fragment_id (): String [1..1]

A part of, a fragment or a sub-function within an object. Allows references to sub-parts of objects, such as a certain line and character position in a text object. The syntax and semantics are defined by the application responsible for the object.

DV_URI.query (): String [1..1]

Query string to send to application implied by scheme and path. Enables queries to applications, including databases to be included in the URI. Supports any query meaningful to the server, including SQL.

Invariants

DV_URI.Value_valid: not value.is_empty

Scheme_valid: scheme.is_equal (Ehr_scheme)

{
    "name": "DV_EHR_URI",
    "documentation": "A `DV_EHR_URI` is a `DV_URI` which has the scheme name 'ehr', and which can only reference items in EHRs. \n\nUsed to reference items in an EHR, which may be the same as the current EHR (containing this link), or another.",
    "ancestors": [
        "DV_URI"
    ],
    "invariants": {
        "Scheme_valid": "scheme.is_equal (Ehr_scheme)"
    }
}

Syntaxes

DV_EHR_URI Syntax

The syntax of a DV_EHR_URI is an openEHR path, inside the 'ehr' URI scheme-space, and is one of the forms:

ehr://system_id/ehr_id/top_level_structure_locator/path_inside_top_level_structure
ehr:/ehr_id
ehr:/ehr_id/top_level_structure_locator
ehr:/ehr_id/top_level_structure_locator/path_inside_top_level_structure

The syntax is described in more detail in the openEHR Architecture Overview. DV_EHR_URIs are used as a mechanism for referencing in the EHR, ensuring readability by humans, as well as validity when extracts are transmitted elsewhere: even if the target of a path is not present, the path can be used to locate the missing item on demand.