DECOR-terminology
Contents
General
Holds code systems, value sets, and associations between dataset concepts and terminology.
Elements
valueSet
0..* optional. Contains either a reference to another value set, or defines a complete value set.
A referencing value set is usually contained in a DECOR Repository. The key attribute is @ref pointing to the id of value set in a repository. Referring to a value set in the repository makes all version of that value set with that id available to the project.
A defining value set typically specifies coded concepts. In addition exceptional codes (exceptions) may be specified. It is also possible to combine complete code systems or included value sets with specific coded concepts and exceptions. A defining value set has three key attributes: @id, @name and @effectiveDate.
 | The value set
|
| A referencing value set SHOULD NOT contain any complete code systems or coded concepts or exceptions of its own. |
@id
A mandatory globally unique, non-semantic, identifier for the value set as the primary identifier, typically an OID.
@name
A required name for the value set as a secondary identifier. Please note that there is no guarantee that the name is globally unique. However names SHALL be unique within a single DECOR project.
@effectiveDate
The mandatory date (and time) as a version indicator. The date denotes after which the value set can be considered for use. Use of the value set prior to this date would be considered an invalid use of the value set.
@ref
If this value set refers to another value set rather than defining its own set, then this attribute contains the globally unique, non-semantic, identifier for that referenced value set as the primary identifier. All versions of the respective value set are made available to the DECOR project. It is up to the dataset terminologyAssociation and/or template vocabulary elements to determine which exact version(s) is/are bound in the project.
There is no content allowed when specifying a referencing value set (no descriptions, concept lists etc.).
@expirationDate
The optional date (and time) at which the value set becomes stale (and should undergo a review for [clinical] relevance and accuracy). Use of the value set after this date would be considered venturesome.
@statusCode
The mandatory status of a defining value set. According to the Business Requirements for Value Set Registries ART-DECOR uses the following subset of status codes of a value set (in bold).
| statusCode | Description |
|---|---|
| new | Value set just created and is new and work in progress to become a draft/finalized value set. Beyond the author, nobody should look at this value set unless it's status code is draft or finalized. |
| draft | Value set under development (nascent). Metadata and value set may be incomplete. Entered primarily to encourage other users to be aware of ongoing process. |
| final | Value set has been published by the custodian organization and deemed fit for use. May have associated adoption and annotation metadata |
| deprecated | Value set retired: No longer fit for use. Information available for historical reference. |
| rejected | Value set is rejected |
| cancelled | Value set is withdrawn |
 | A value set registry may consider all status codes (also those in italics) that are defined in the Business Requirements for Value Set Registries. The value set itself is considered to need only the codes mentioned above and the experience of several years using ART-DECOR showed that this is sufficient. |
@displayName
The required human readable display name for the value set for orientation purposes. This is not intended for machine processing and typically created in the project’s language or in English.
@versionLabel
The optional human readable version label for the value set to be able to determine the correct version of a value set. This is not intended for machine processing.
@experimental
Value set is for testing purposes, not real usage. Note that all artifacts in an experimental project are also considered experimental.
Sub-elements of value set
Sub-elements of value set are
- desc
- conceptList
- completeCodeSystem
desc
0..*. An optional free text natural language description of the intent and scope of the value set. The purpose is to provide the author’s initial intent for the value set. Format: string with optional HTML tagging (XHTML). Supports @language, see @defaultLanguage.
completeCodeSystem
0..*. An optional relation of this value set to a complete code system such as ICD-10 or HL7's ActCode.
@codeSystem
A mandatory globally unique, non-semantic, reference to the code system.
@codeSystemName
An optional name for the code system
@codeSystemVersion
An optional specific version string for the code system
@flexibility
An optional static or dynamic binding for the code system that is referred. Default value is 'dynamic'.
<completeCodeSystem codeSystem="2.16.840.1.113883.5.4" codeSystemName="HL7 Act Code"/>
conceptList
0..1 Contains the list of coded concepts or exceptions or inclusions of value sets defined elsewhere. Coded concepts and exceptions both carry the same attributes. Exceptional concepts reflect reason for the absence of data and correspond to NullFlavors in HL7 V3. Note that the same coded concept can occur more than once in a value set at different hierarchical levels.
concept or exception
@code
1..1. A mandatory code from a code system
@codeSystem
A mandatory globally unique, non-semantic, reference to the code system of the code
@codeSystemName
An optional name for the code system of the code
@codeSystemVersion
An optional specific version string for the code system of the code
@displayName
The optional human readable display name for the code for orientation purposes. This display name corresponds to an official display name or synonym for the code in the code system.
@level
A required integer indicating the hierarchical level of the coded concept within the code system that the code comes from
@type
A required code for the type of code as indicated by the code system. Valid values are:
| Type | Description |
|---|---|
| A | Abstract; a term that has children in the specialization hierarchy, but is not, itself, selectable and therefore deemed abstract. |
| S | Specializable; a term that has children in the specialization hierarchy, and is also selectable and therefore deemed specializable. |
| L | Leaf; a term that has no children in the specialization hierarchy, and is selectable, and therefore deemed to be a leaf. |
| D | Deprecated; a term that should not be used any longer |
include
You may include coded concepts of another value set (defined elsewhere) by simply referring to that value set.
@ref
A required identifier of the value set to be included.
<include ref="2.16.840.1.113883.11.1"/>
@flexibility
An optional static or dynamic binding for the value set that is included. Default value is 'dynamic', meaning: the latest available version.
@exception
An optional boolean value that determines if the included value sets coded concepts should be included as exceptions or as regular coded concepts. Note that this switch applies to all coded concepts in the included value set. Default is false.
@ordinal
Relevant for codes in an ordinal system, like Glasgow Coma Scale, to reflect the order of the code in the set.
designation
Designations are language dependent display names for the code. For any language there might be multiple, each specifying the type (fully specified name, preferred, synonym, ...).
desc
You may add a description for convenience, but should note that most of the time the description here overlaps with the designation/description of the coded concept
Examples
<valueSet ref="2.16.840.1.113883.2.4.999.1"
name="MedicationCodesRxNorm"
displayName="Medication Code From RxNorm">
<desc language="en-US">Medication codes from RxNorm</desc>
</valueSet>
<valueSet id="2.16.840.1.113883.2.4.999.1"
name="MedicationCodesRxNorm"
effectiveDate="2012-10-01T00:00:00"
displayName="Medication Code From RxNorm"
statusCode="final">
<desc language="en-US">Medication codes from RxNorm</desc>
<completeCodeSystem codeSystem="2.16.840.1.113883.6.88" codeSystemName="RxNorm"/>
<conceptList>
<exception code="OTH" codeSystem="2.16.840.1.113883.5.1008"
displayName="Other" level="0" type="L"/>
</conceptList>
</valueSet>
<valueSet id="2.16.840.1.113883.1.11.19897"
name="ActConsentType"
effectiveDate="2009-10-01T00:00:00"
displayName="ActConsentType"
statusCode="final">
<conceptList>
<concept code="_ActConsentType" codeSystem="2.16.840.1.113883.5.4"
displayName="ActConsentType" level="0" type="A"/>
<concept code="ICOL" codeSystem="2.16.840.1.113883.5.4"
displayName="information collection" level="1" type="L"/>
<concept code="IDSCL" codeSystem="2.16.840.1.113883.5.4"
displayName="information disclosure" level="1" type="L"/>
<concept code="INFA" codeSystem="2.16.840.1.113883.5.4"
displayName="information access" level="1" type="S"/>
<concept code="INFAO" codeSystem="2.16.840.1.113883.5.4"
displayName="access only" level="2" type="L"/>
<concept code="INFASO" codeSystem="2.16.840.1.113883.5.4"
displayName="access and save only" level="2" type="L"/>
<concept code="IRDSCL" codeSystem="2.16.840.1.113883.5.4"
displayName="information redisclosure" level="1" type="L"/>
<concept code="RESEARCH" codeSystem="2.16.840.1.113883.5.4"
displayName="research information" level="1" type="S"/>
<concept code="RSDID" codeSystem="2.16.840.1.113883.5.4"
displayName="de-identified information access" level="2" type="L"/>
<concept code="RSREID" codeSystem="2.16.840.1.113883.5.4"
displayName="re-identifiable information access" level="2" type="L"/>
</conceptList>
</valueSet>
<valueSet id="2.16.840.1.113883.2.4.999.1.3"
name="NullFlavorUNKandOTH"
effectiveDate="2013-10-01T00:00:00"
displayName="NullFlavor UNK and OTH"
statusCode="final">
<conceptList>
<concept code="UNK" codeSystem="2.16.840.1.113883.5.1008"
displayName="Unknown" level="0" type="L"/>
<concept code="OTH" codeSystem="2.16.840.1.113883.5.1008"
displayName="Other" level="0" type="L"/>
</conceptList>
</valueSet>
<valueSet id="2.16.840.1.113883.2.4.999.1.2"
name="ActConsentTypeWithNulls"
effectiveDate="2013-10-01T00:00:00"
displayName="ActConsentType with nulls"
statusCode="final">
<conceptList>
<include ref="2.16.840.1.113883.1.11.19897"
flexibility="2009-10-01T00:00:00"/>
<exception code="UNK" codeSystem="2.16.840.1.113883.5.1008"
displayName="Unknown" level="0" type="L"/>
<exception code="OTH" codeSystem="2.16.840.1.113883.5.1008"
displayName="Other" level="0" type="L"/>
</conceptList>
</valueSet>
Alternatively this same value set ActConsentTypeWithNulls could be done using:
<valueSet id="2.16.840.1.113883.2.4.999.1.2"
name="ActConsentTypeWithNulls"
effectiveDate="2013-10-01T00:00:00"
displayName="ActConsentType with nulls"
statusCode="final">
<conceptList>
<include ref="2.16.840.1.113883.1.11.19897"
flexibility="2009-10-01T00:00:00"/>
<include ref="2.16.840.1.113883.2.4.999.1.3"
flexibility="2013-10-01T00:00:00" exception="true"/>
</conceptList>
</valueSet>
terminologyAssociation
Terminology association may be used to establish a link between terms and data set elements, concept lists or concept list elements. Ideally there is one coded concept to bind to a data set element, one coded concept to bind to a concept list element, and/or one value set to bind to a concept list.
A terminology association holds a @conceptId (pointing to a data set element, concept list or concept list element) and
- either a value set reference (@valueSet, @flexibility)
- or a coded concept (@code, @codeSystem)
A terminology association may have a validity time period indicated by a start date @effectiveDate and an end date @expirationDate.
@conceptId
The required id of the concept to which the terminology association is to be linked to, i.e. a concept list or a specific concept as part of a concept list of a coded data element.
@valueSet, @flexibility
Typically a @valueSet by name or by id may be used to be linked to a concept. The concept denoted in @conceptId is a concept list of a coded data element.
@flexibility is either "dynamic" to refer to the latest version of @valueSet or is a date (static reference) which means that the reference is made to a specific version of of @valueSet.
@code, @codeSystem, @displayName
A specific @code from a @codeSystem may be used to link to a concept. The concept denoted in @conceptId is typically a concept from a concept list of a coded data element. A displayName may be used to override the displayName as defined for the code in the codeSystem. This may be a localization or a synonym, but should in now way alter the semantics of the coded concept.
@effectiveDate, @expirationDate
These two attributes relate to the terminology association itself: they are used to denote start and end date of the validation period of the respective terminology association
<terminologyAssociation conceptId="1.2.3.4.0"
valueSet="CareProvider" flexibility="2011-09-04T00:00:00"/>
<terminologyAssociation conceptId="1.2.3.4.0.1"
code="SRG" codeSystem="2.16.840.1.113883.2.4.3.22.99.2.1"/>
@strength
Coding strength of a vocabulary binding to a value set
| Mnemonic | Nederlands | Deutsch | Description |
|---|---|---|---|
| required | verplicht | Erforderlich | Required (formerly known as CNE). Coded with no exceptions; this element SHALL be from the specified value set |
| extensible | uitbreidbaar | Erweiterbar | Extensible (formally known as CWE). Coded with Exceptions; this element SHALL be from the specified value set if any of the codes within the value set can apply to the concept being communicated. If the value set does not cover the concept (based on human review), alternate codings (or, data type allowing, text) may be included instead. |
| preferred | Voorkeur | Bevorzugt | Preferred. Instances are encouraged to draw from the specified codes for interoperability purposes but are not required to do so to be considered conformant. |
| example | voorbeeld | Beispiel | Example. Instances are not expected or even encouraged to draw from the specified value set. The value set merely provides examples of the types of concepts intended to be included. |
@equivalence
Details of how two concepts map to each other, the source is : relatedto | equivalent | equal | wider | subsumes | narrower | specializes | inexact | unmatched | disjoint; See also FHIR ConceptMapEquivalence http://hl7.org/fhir/concept-map-equivalence; Releationship with "ISO/TR 12300:2014 Health informatics, Principles of mapping between terminological systems" is also indicated
| Mnemonic | Nederlands | Deutsch | Description |
|---|---|---|---|
| relatedto | gerelateerd aan | verwandt mit | The concepts are related to each other, and have at least some overlap in meaning, but the exact relationship is not known |
| equivalent | equivalent | äquivalent | The definitions of the concepts mean the same thing (including when structural implications of meaning are considered) (i.e. extensionally identical). / ISO 12300: 2 = Equivalence of meaning, but with synonymy. For example, ureteric calculus and ureteric stone; gall stones and cholelithiasis. |
| equal | gelijk | gleich | The definitions of the concepts are exactly the same (i.e. only grammatical differences) and structural implications of meaning are identical or irrelevant (i.e. intentionally identical). / ISO 12300: 1 = Equivalence of meaning; lexical, as well as conceptual. For example, asthma and asthma; ovarian cyst and cyst of ovary. |
| wider | breder | breiter | The target mapping is wider in meaning than the source concept. / ISO 12300: 3 = Source concept is broader and has a less specific meaning than the target concept/term. For example, obesity and morbid obesity; diabetes and diabetes mellitus type II. |
| subsumes | omvat | umfasst | The target mapping subsumes the meaning of the source concept (e.g. the source is-a target). |
| narrower | nauwer | enger | The target mapping is narrower in meaning than the source concept. The sense in which the mapping is narrower SHALL be described in the comments in this case, and applications should be careful when attempting to use these mappings operationally. / ISO 12300: 4 = Source concept is narrower and has a more specific meaning than the target concept/term. For example, feels ugly and self-image finding; acute renal failure syndrome secondary to dehydration and acute renal failure syndrome. |
| specializes | specialiseert | spezialisiert | The target mapping specializes the meaning of the source concept (e.g. the target is-a source). |
| inexact | onnauwkeurig | ungenau | The target mapping overlaps with the source concept, but both source and target cover additional meaning, or the definitions are imprecise and it is uncertain whether they have the same boundaries to their meaning. The sense in which the mapping is narrower SHALL be described in the comments in this case, and applications should be careful when attempting to use these mappings operationally. |
| unmatched | onvergelijkbaar | unvergleichbar | There is no match for this concept in the destination concept system. / ISO 12300: 5 = No map is possible. No concept was found in the target with some degree of equivalence (as measured by any of the other four ratings). |
| disjoint | elkaar uitsluitend | sich auschließend | This is an explicit assertion that there is no mapping between the source and target concept. |
