- 1 Scope
- 2 Intended audience
- 3 the DECOR publication format
- 4 DECOR Introduction
- 5 DECOR HTML-representation and interactive representation
- 6 DECOR standard properties
- 7 DECOR publication tabs
- 8 Dataset versioning
- 9 Templates
- 10 Example
- 11 Example template fragment
This text contains extra information about the publication of a DECOR information standard. It also introduces the DECOR-methodology and contains a conceptual (non-technical) description of DECOR. Per DECOR-part there are links to the underlying XML-models.
The intended audience is product managers and software vendors looking for simpler ways to implement complex specifications.
the DECOR publication format
DECOR (Data Elements, Codes, OIDs and Rules) is a methodology to capture the data needs of caregivers in terms of datasets and scenarios and use it to generate various artefacts: documentation, value sets, XML instance validation, generation and processing support, and test tools etc.
DECOR allows to iteratively improve recorded data definitions and link together input from various experts with different background knowledge: caregivers, terminologist, modellers, analysts and interface/communication specialists.
Modelers, analysts and interface / communication specialists add the technical representations as e.g. HL7 CDA templates, HL7 FHIR or IHE profiles. During that design phase and also in the following implementation and production phases the tool allows comprehensive validation and testing.
The underlying DECOR data format is XML. The generation of HTML-, PDF- and Wiki-based documentation and XML-materials like validation and test environments is possible through a release and archive management function and transformations with stylesheets. The technical artefacts like templates and value sets can be used as input for test suites like IHE Gazelle ObjetcsChecker. Easy consistency checks across all artefacts can be achieved, CDA-based template definition can be verified to be standard conformant with the underlying CDA standard.
DECOR (Data Elements, Codes, OIDs and Rules) is a methodology and persistence layer for capturing the data requirements of healthcare professionals in data sets and scenarios, and uses that information as a source for documentation and all necessary technical artifacts.
DECOR answers questions like:
- What type of information is recorded by the parties involved?
- Where does their contribution end?
- Where are other parties involved and what is their involvement?
- How to maintain a consistent and meaningful representation of this information?
- How to record constraints on generic models?
- What type of support is needed by vendors to construct interfaces?
- How to generate documentation and supporting documents?
- How are constraints tested?
The experience that stems from DECOR is used as feedback on existing standards (that form the basis for DECOR) and as input for future international standardization initiatives (HL7, IHE).
DECOR HTML-representation and interactive representation
The information collection that is documented in DECOR can be accessed in two ways:
- as a HTML-representation. This is a static representation of the DECOR collection at a specific time and serves as a DECOR-publication. The HTML-representation is not interactive, this means that no changes can be made to this publication. It is however possible to access the DECOR-publication through multiple views.
- as an interactive representation. ART-DECOR:
ART (Advanced Requirement Tooling) is the DECOR user interface to create and adapt DECOR files, and to generate artefacts from DECOR files.
|ART is the backend, based on the eXist-db XML database.||ART is also the frontend, until ART-DECOR 2.x, XQuery and Orbeon XForms is used.||ART-DECOR 3.0 is completely replacing the former UI platform and uses Vue and Vuetify.|
DECOR standard properties
Dataset artefacts, value sets, scenarios and templates that are defined in DECOR support a fixed set of properties like: name, required identifier, version information per artefact and status information that defines whether an artefact is still under development, ready for use or deprecated, etc. Based on these properties is it possible to cross-reference between artefacts, for instance that a concept is in use in a message in a certain structure or that a template supports the communication of the information that is defined in a data set concept. DECOR also contains all value sets that supply the necessary codes and code systems. DECOR supports the recording of issues: the documentation of change requests or issues with DECOR artefacts.
DECOR publication tabs
DECOR has a fixed structure. The following tabs exist in a DECOR-publication:
This tab contains the generic project information:
- Principal name for the project
- version information such as the creation date (and time) for this publication:
- references to all organizations/persons that own copyright in some way
Information about the project. Project information consists of the following items:
- Description of the project
- Artifact-prefix: used as the name prefix of the DECOR XML-document. For example, the prefix "test-" is used for the DECOR document "test-decor.xml".
- Reference URI
- Default language
- Template Element namespace
- List of authors
- Version information per version or release
Information about datasets, that contain (groups of) concepts A dataset is a list of (hierarchical) concepts. A DECOR project contains one or more datasets. When there are multiple datasets, they are different versions of the same dataset. It is not recommended to create datasets for different healthcare projects in the same DECOR project.
A dataset consists of (healthcare) concepts. You can see a DECOR dataset as an hierarchical concept repository. Concepts should be well-defined and can be demonstrated with the following examples:
The following datatypes are available (items printed as bold are part of the current DECOR implementation).
|count||aantal||Zähler||Countable (non-monetary) quantities. Used for countable types such as:
|code||code||Code||A system of valid symbols/codes, that substitute for specified concepts e.g. alpha, numeric, symbols and/or combinations, usually defined by a formal reference to a terminology or ontology, but may also be defined by the provision of text. Typically a symbol/code is expressed with a value for code, an identifier for the terminology or ontology it belongs to and at least one textual representation (display name).|
|ordinal||ordinaal||Ordinal||Models rankings and scores, e.g. pain, Apgar values, etc, where there is a) implied ordering, b) no implication that the distance between each value is constant, and c) the total number of values is finite. Note that although the term ‘ordinal’ in mathematics means natural numbers only, here any integer is allowed, since negative and zero values are often used by medical professionals for values around a neutral point.|
Scores are commonly encountered in various clinical assessment scales. Assigning a value to a concept should generally be done in a formal code system that defines the value, or in an applicable value set for the concept, but some concepts do not have a formal definition (or are not even represented as a concept formally, especially in questionnaires. Scores may even be assigned arbitrarily during use (hence, on Coding). The value may be constrained to an integer in some contexts of use. Examples of sets of ordinal values:
|identifier||identificatie||Identifikation||Type for representing identifiers of real-world entities. Typical identifiers include drivers licence number, social security number, prescription id, order id, and so on.|
|string||string||Zeichenkette||Any text item, without visual formatting.|
|text||string met opmaak||Zeichenkette mit Formatierung||A text item, which may contain any amount of legal characters arranged as e.g. words, sentences etc. Visual formatting and hyperlinks may be included.|
|date||datum||Datum||Represents an absolute point in time, as measured on the Gregorian calendar, and specified only to the day. Semantics defined by ISO 8601. Used for recording dates in real world time. The partial form is used for approximate birth dates, dates of death, etc.|
|datetime||datum+tijd||Datum+Zeit||Represents an absolute point in time, specified to the second. Semantics defined by ISO 8601. Used for recording a precise point in real world time, e.g. the exact date and time of the birth of a baby, and for approximate time stamps, e.g. the origin of an history observation which is only partially known.|
|time||tijd||Zeit||Represents a time, specified to the second (hh:mm:ss). Semantics defined by ISO 8601. Used for recording a real world time, e.g. time of medication administration and starting/stopping a procedure, and for approximate times, e.g. the origin of an history observation which is only partially known.|
Per April 2020
|complex||samengestelde gegevens||Sammlung von Daten||Non-atomic datatypes which are not explictly further defined in the dataset itself. Example: 'address' or 'person name'. Usually complex types are assumed to be well-known enough not to warrant further decomposition in the dataset itself.|
|decimal||decimaal getal||Dezimalzahl||Decimal number (rarely used, in most cases a decimal number is actually a quantity).|
|quantity||hoeveelheid||Menge||Quantitified type representing "scientific" quantities, i.e. quantities expressed as a magnitude and units. If not further specified with fractionDigits, a decimal number with optional decimal point (i.e. '3.14159265359').
There are some "special" quantities (used in healthcare), explained later:
|duration||tijdsduur||Dauer||Is a quantity, represents a period of time with respect to a notional point in time, which is not specified. A sign may be used to indicate the duration is “backwards” in time rather than forwards.|
|boolean||boolean||Boolean||Items which are truly boolean data, such as true/false or yes/no answers.|
|blob||binair||Binär||Things that are typically stored as binary objects in the computer world and need to be rendered appropriately, e.g.
|ratio||ratio||Ratio||A ratio of two Quantity values - a numerator and a denominator|
The datatypes can be further restricted using the following datatype facets:
|unit||Unit for quantities||kg, mmol||quantity|
|minInclude||Range min include for quantities||1, 100||count, ordinal, quantity, currency|
|maxInclude||Range max include for quantities||1, 100||count, ordinal, quantity, currency|
|fractionDigits||Fraction digits for quantities"1" for at least 1 or "1!" for exactly 1||"1" for at least 1, "1!" for exactly 1||quantity|
|timeStampPrecision||Precisions for timing specs||date, datetime|
|default||Default value||all datatypes|
|fixed||Fixed value||all datatypes|
|minLength||Minimum length for strings||string|
|maxLength||Maximum length for strings||string|
Facet timeStampPrecision takes the following values
|Y||at least year (YYYY)|
|Y!||only year (YYYY)|
|YM||at least month (MM) and year (YYYY)|
|YM!||only month (MM) and year (YYYY)|
|YMD||at least day (DD), month (MM) and year (YYYY)|
|YMD!||only day (DD), month (MM) and year (YYYY)|
|YMDHM||at least day (DD), month (MM) and year (YYYY), hour (hh) and minute (mm)|
- New dataset versions get a new @id and a new @effectiveDate
- The concepts in the new dataset version keep their @id, but get a new @effectiveDate and inherit from the original concept. If a concept needs changes it may be disconnected (deinherit) from its source concept so editing is possible
- The name and other properties of a concept constitute its definition. This definition should be governed. This means that any property in any language is under governance. When project wants to reuse (inherit) these concepts they inherit this definition as-is, and only comments are allowed additions. These comment cannot in any way shape or form alter the semantics of the original concept
- Multi lingual setting: when a project wants to reuse concepts from a building block repository (BBR) that does not have defining properties in the same language as the project, then the project can do one of the following things:
- Accept the BBR concept as-is, potentially adding a comment
- Talk to the BBR governance group and work out an agreement whereby translations may be submitted
The recommended procedure for a BBR governance group for submitted translations is to create a new version of the dataset that adds the translations. The governance group could, but this is not recommended, decide to add the translation to the original dataset. ART will not support this as BBR datasets should be final, and final objects cannot be edited.
A representation of the processes and relevant concepts. Scenarios represent use cases, where one or multiple actors perform parts of a healthcare process based on transactions. Transactions are usually a form of (message based) communication, such as a HL7v3-interaction or an EDIFACT-interchange, but could also represent a static registration scenario. Transactions are usually related to a defined (choice of) response. Transactions are grouped into transaction groups.
Identifiers used in this project. This tab contains information on the OID's:
- referenced identifiers used in this project
- template identifiers used in this project
- value set identifiers used in this project
Terminology specifications (value sets and terminology associations) This tab shows the value sets in use in this project. Value sets contain a name, identifier, description and a version date. Templates support references to value sets to define which codes the template element can contain. Value sets are versionable objects.
Templates are for the creation and validation of XML-based messages or documents.
Templates support mapping of data set artifacts to HL7v3 artifacts. The template format is influenced by the Templates Registry Project (HL7 International) and is a simplified representation of the HL7 MIF (model interchange format). The primary purposes for the definition of templates in DECOR are:
- the construction of validation methods to support the implementation of interfaces. These methods are: schematron, and (in the future) simplified W3C schema for vendors who want to generate code based on schematron or schema
- the documentation of templates, referenced value sets and identifications, constraints, conditions and co-occurrences
- the documentation of template examples
This text documents an example template that contains:
- template metadata
- timestamp after which the template existed
- status of the template
- description of the intent and scope of the template
- example XML fragment
- elements with properties like:
- data type
- vocabulary bindings (value sets)
- property (range specified with minInclude and maxInclude)
- identifier that references the dataset concept
- attributes with fixed values (OBS, EVN)
Example template fragment
An example template (identifiers are fictional):
<template id="2.999.999.918.104.22.168.90.100001" name="Gravidity" effectiveDate="2011-01-28" statusCode="active"> <desc>Template example for gravidity</desc> <example> <observation classCode="OBS" moodCode="EVN"> <code code="Gravidity" codeSystem="2.16.840.1.113822.214.171.124.13"/> <value xsi:type="INT" value="2"/> </observation> </example> <element name="hl7:observation"> <attribute classCode="OBS" moodCode="EVN"/> <element name="hl7:code" minimumMultiplicity="1" maximumMultiplicity="1" isMandatory="true" datatype="CE"> <vocabulary code="Gravidity" codeSystem="2.16.840.1.1138126.96.36.199.13"/> </element> <element name="hl7:value" minimumMultiplicity="1" maximumMultiplicity="1" id="2.999.999.9188.8.131.52001.1" datatype="INT"> <property minInclude="0" maxInclude="75"/> </element> </element> </template>
Information about the publication compilation process. This tab shows possible compilation errors and warnings.
Contains legal information such as licenses.