v2+ Vocabulary - Local Development build (v0.1.0). See the Directory of published versions
Rules
This page is listing the set of rules - as identified and documented so far - when
converting the v2 tables into proper vocabulary.
Versioning
Versioning has to be independent from the base version of the standard.
Therefore, semantic versioning (semver.org) seams to be reasonable, but it requires detailed inspection of all tables.
Foundation
All tables may provide the following details:
- concept/vocabulary domain
- This is the minimum for defining vocabulary. It must be defined for all tables.
- It introduces the notion for what kind of codes are needed, i.e. which type of content should be coded.
- Some concept domains may contain some example values that help to explain. Typically, the set of listed values is too small for real use.
- value set
- for (v2) internal codesystems:
- typically the complete codesystem content is taken. Then the table also defines the codesystem.
- for references to external codesystems, eg. V3, FHIR, LOINC or Snomed CT, or other:
- it ocntains an explicit list of the codes which should be selected
- separation can be decided based on the associated OID for the value set
- must declared as “foreign value set”
- codesystem
- (reasable) list of codes
- versioned correctly
- associated codesystem may change for a specific data element over time in order to keep the codesystem complete and correct
- further identified as either classification (with other/unknown) or terminology (w/o other/unknown)
Furthermore, the following applies:
- all tables are ‘open’ per default, except specific HL7-defined tables for technical reasons (the latter requires inspection)
Therefore, a table is a combination of concept domains with perhaps value sets and codesystems.
General
Beside the aforementioned rules the following should be valid:
- all symbolic names must be unique - no re-use
- all OIDs are only used for a single entity
- must use correct OID for value set or codesystem if belonging to v2
- the table type cannot change across HL7 versions
- it must be agreed on the correct type
- probably taking the type from the latest HL7 v2 version, leading to backward changes
- the case-sensitive name of the table should not change over time
- upper case naming ocnvention preferred
- some tables may define properties for values
- determine whether all values (codes) must have a value for this property, or only some
- verify changes of properties across versions
- (property maintenance is currently a manual process and has to be repeated)
Values
- can only contain other or unknown if appropriate property is set
HL7-defined Tables
HL7-defined tables shall adhere to the following:
- They are needed so that the v2 framework will work.
- They have to improve the previous version:
- all previous values must be present
- values can be marked as ‘deprecated’
- possible binding strengths
- required - no extensions possible, e.g. for order control codes
- extensible, e.g. for events
- ID and CNE data types must use HL7-defined tables, but HL7-defined tables can also be used with IS and CWE.
User-defined Tables
- possible binding-strength
- suggested
- example
- preferred
- selected binding strength depends on quality of provided example values
- user-defined tables cannot be used with ID or CNE data elements
Binding Strength (original from v2.x)
| Seq |
strength |
mapping to new |
explanation |
| 1 |
example |
example |
|
| 2 |
universal |
required? |
|
| 3 |
US realm |
|
for use in US only, unlcear how to represent that |
| 4 |
representative |
suggested, recommended |
|
Binding Strength (according to FHIR)
| Seq |
strength |
usage |
explanation |
| 1 |
example |
user-defined |
|
| 2 |
suggested |
user-defined |
|
| 3 |
recommended |
user-defined |
|
| 4 |
extensible |
HL7-defined |
|
| 5 |
required |
HL7-defined |
|
Openness
| Seq |
openness |
explanation |
| 1 |
open |
all tables are open |
| 2 |
closed |
except HL7-tables for specific use, eg. order control codes |
Concept Domains
All tables have a concept domain.
Concept Domains cannot have values; if so, then it must be a concept domain with exampe values.
If the table is user-defined and the amount of values is too small then the table will be handled as ‘concept domain with example values’.
The table values will then be rendered as a bullet list into the description.
A separate codesystem for concept domains will be established and populated with all tables.
A separate concept domain codesystem is generated from all tables.
Codesystems
Must have values.
A subsequent version must contain all previous values/codes. Outdated values may be marked as deprecated.
Each codesystem has two value sets:
- the complete one
- one with current active values
Value Sets
If values are present, then it must have codesystem or reference an imported value set, eg. from V3 or FHIR, or other external codesystems.
Foreign Value Sets
Foreign value sets are imported or otherwise reference foreign vocabulary:
- foreign value sets reference codesystems outside v2, ie. have other OID roots
Properties to Codesystems
- v2 version created
- version history (not yet generated/populated)
- table number
Properties to codesystems must be added as extensions because the CodeSystem resource does not provide a means for general properties beside specific extensions.
Properties to Codes
- HL7 version introduced
- HL7 version deprecated
- status
- comment
- usage
- date modified