DECOR publication format

DECOR Introduction

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.

Book-open-variant.svg Movie.svg

For caregivers, the tools mainly registers data elements and their collections as data sets with concepts, data types, allowable value ranges, identifications, codes, examples and business rules etc. In addition, use case specific Scenario's can be documented.


From the base requirements, the caregivers documented, terminologist can add the appropriate codes, associate caregiver concepts with coded concepts and create and maintain the value sets to be used. Typically also namespaces, identifiers, URIs and OIDs are assigned.


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.

Project leads

During development and production phases stakeholders and team members of the governance group are supported by an artefact-aware issue and reporting management that enables effective change management of the artefacts.

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.
 Existdb-logo.gif  Orbeon-logo.png Vue.png

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:

Front Page

This tab contains the generic project information:

  • Principal name for the project
  • version information such as the creation date (and time) for this publication:

Frontpage version info.png

  • references to all organizations/persons that own copyright in some way

Project Information

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
  • Disclaimer
  • 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:

  • Female
  • Body length
  • Diabetes
  • Monochorionic

The following datatypes are available (items printed as bold are part of the current DECOR implementation).

Datatype Nederlands Deutsch Description
count aantal Zähler Countable (non-monetary) quantities. Used for countable types such as:
  • pregnancies,
  • steps (taken by a physiotherapy patient),
  • number of cigarettes smoked in a day.
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:

  • -3, -2, -1, 0, 1, 2, 3 -- reflex response values;
  • 0, 1, 2 -- Apgar score values
  • 1, 2, 3, 4,... -- ASA classification
  • I, II, III, IV, ... -- Tanner scale
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:

  • for time durations duration shall be used
  • for monetary amounts currency shall be used
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.
  • images: like X-rays, computertomographic images;
  • graphic: diagrams, graphs, mathematical curves, or the like – usually a vector image;
  • icons: a sign or representation that stands for its object by virtue of a resemblance or analogy to it
  • pictures: A visual representation of a person, object, or scene – usually a raster image.
currency valuta Währung Monetary quantities
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:

Facet Description Example Applies to
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

timeStampPrecision value
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)

Dataset versioning

  • 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
    • identifier
    • name
    • timestamp after which the template existed
    • status of the template
    • description of the intent and scope of the template
    • context
  • 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.999." name="Gravidity" effectiveDate="2011-01-28" statusCode="active">
    <desc>Template example for gravidity</desc>
        <observation classCode="OBS" moodCode="EVN">
            <code code="Gravidity" codeSystem="2.16.840.1.113883."/>
            <value xsi:type="INT" value="2"/>
    <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.113883."/>
        <element name="hl7:value" minimumMultiplicity="1" maximumMultiplicity="1" id="2.999.999.999.77.9.100001.1" datatype="INT">
            <property minInclude="0" maxInclude="75"/>

Compile Time

Information about the publication compilation process. This tab shows possible compilation errors and warnings.


Contains legal information such as licenses.