diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termcodesystem_schema.svg b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termcodesystem_schema.svg new file mode 100644 index 00000000000..508e054d203 --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termcodesystem_schema.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termconceptmap_schema.svg b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termconceptmap_schema.svg new file mode 100644 index 00000000000..9bda238882b --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termconceptmap_schema.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termvalueset_schema.svg b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termvalueset_schema.svg new file mode 100644 index 00000000000..70c08dd7211 --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/images/termvalueset_schema.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa/terminology.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa/terminology.md new file mode 100644 index 00000000000..1347f3afbd1 --- /dev/null +++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa/terminology.md @@ -0,0 +1,284 @@ +# Terminology + +HAPI FHIR JPA Server includes an `IValidationSupport` class, `JpaPersistedResourceValidationSupport`, which can be used to validate terminology using CodeSystem, ValueSet and ConceptMap resources provided by the JPA Server. Terminology can be loaded into the JPA Server using standard FHIR REST APIs (PUT and POST) as well as using the hapi-fhir-cli [upload-terminology](/hapi-fhir/docs/tools/hapi_fhir_cli.html#upload-terminology) command. + +# Versioning of Terminology + +CodeSystem resources can be versioned as described in the FHIR specification [here](http://hl7.org/fhir/codesystem.html#versioning). Similarly, for ValueSet and ConceptMap resources that are defined with a versioned CodeSystem can also be versioned. + +Versions for CodeSystem, ValueSet and ConceptMap resources are differentiated from each other by the CodeSystem.version, ValueSet.version and ConceptMap.version properties respectively. Each version of a given CodeSystem, ValueSet and ConceptMap resource will have a separate resource entity. + +When queries or operations are performed involving CodeSystem, ValueSet, or ConceptMap resources that are versioned and no version parameter is provided, the JPA Server will reference the most recently updated version. + +Delta Add and Remove modes in hapi-fhir-cli upload-terminology command will only apply to most recently updated version. Import from csv and export to csv hapi-fhir-cli commands will only apply to most recently updated version. + +# Terminology Schemas + +This page provides schema for tables that are used to complement and to map relationships between the CodeSystem, ValueSet, and ConceptMap resources and the various properties associated with these resources that are used or referenced by terminology operations. + +## CodeSystem Tables + +Resources + +The TRM_CODESYSTEM_VER table indicates a single CodeSystem resource with a specific version. It can be used to map terminology concepts, represented by various TRM_CONCEPT_* tables to a single CodeSystem version. The TRM_CODESYSTEM table is used to model the canonical representation of a single CodeSystem and maps to a single TRM_CODESYSTEM_VER row which is treated as the current version of the CodeSystem (i.e. the version selected if no version is specified). For example, two CodeSystem resources `CodeSystem/loinc-2.67` and `CodeSystem/loinc-2.68` might have the same CodeSystem.url, e.g. `http://loinc.org` but different CodeSystem.version values. In this case each will each have exactly one row in the TRM_CODESYSTEM_VER table, but there will be only one row in the TRM_CODESYSTEM table which will link only to the most recently updated TRM_CODESYSTEM_VER resource. + +### Columns + +The following list are the main key columns in the TRM_CODESYSTEM_VER table that are used to join to the TRM_CODESYSTEM table and TRM_CONCEPT_* tables. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameRelationshipsDatatypeNullableDescription
PIDLong + Persistent ID of the TRM_CODESYSTEM_VER row. +
RES_IDLong + Persistent ID of the CodeSystem resource in the HFJ_RESOURCE table. +
CODESYSTEM_PIDLongNullable + Persistent ID of the TRM_CODESYSTEM row for canonical CodeSystem. +
CS_VERSION_IDLongNullable + This is the optional CodeSystem.version of the CodeSystem resource. +
+ +The TRM_CODESYSTEM_VER table will have exactly one row for each unique combination of CODESYSTEM_PID and CS_VERSION_ID. + +The following list are the main key columns in the TRM_CODESYSTEM table. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameRelationshipsDatatypeNullableDescription
PIDLong + Persistent ID of the TRM_CODESYSTEM row. +
CODE_SYSTEM_URIString + URL of the CodeSystem resource. +
CURRENT_VERSION_PIDLongNullable + Persistent ID of the TRM_CODESYSTEM_VER row for current version of the CodeSystem. +
CS_NAMEStringNullable + CodeSystem.name value for this CodeSystem resource. +
RES_IDLongNullable + Persistent ID of the current version CodeSystem resource in the HFJ_RESOURCE table. +
+ +The TRM_CODESYSTEM table will have exactly one row for each unique CODE_SYSTEM_URI value. + +## ValueSet Tables + +Resources + +The TRM_VALUESET table indicates a single ValueSet resource with a specific version. It can be used to map terminology concepts, represented by the TRM_VALUESET_CONCEPT and TRM_VALUESET_C_DESIGNATION tables to a single ValueSet resource. + +### Columns + +The following list are the main key columns in the TRM_VALUESET table that are used to join to the TRM_VALUESET_CONCEPT and TRM_VALUESET_C_DESIGNATION tables. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameRelationshipsDatatypeNullableDescription
PIDLong + Persistent ID of the TRM_VALUESET row. +
RES_IDLong + Persistent ID of the ValueSet resource in the HFJ_RESOURCE table. +
URLString + Canonical URL for ValueSet. +
VERStringNullable + Version ID for this ValueSet resource. +
+ +The TRM_VALUESET table will have exactly one row for each unique combination of URL and VER. + +## ConceptMap Tables + +Resources + +The TRM_CONCEPTMAP table indicates a single ConceptMap resource with a specific version. It can be used to map terminology concepts to one another in groups. + +### Columns + +The following list are the main key columns in the TRM_CONCEPTMAP table that are used to join to the TRM_CONCEPTMAP_* tables. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameRelationshipsDatatypeNullableDescription
PIDLong + Persistent ID of the TRM_CONCEPTMAP row. +
RES_IDLong + Persistent ID of the ConceptMap resource in the HFJ_RESOURCE table. +
SOURCE_URLStringNullable + URL of source ValueSet to be mapped. +
TARGET_URLStringNullable + URL of target ValueSet to be mapped. +
URLString + Canonical URL for ConceptMap. +
VERStringNullable + Version ID for this ConceptMap resource. +
+ +The TRM_CONCEPTMAP table will have exactly one row for each unique combination of URL and VER.