PLEASE NOTE THAT EVERYTHING IN TERMINOLOGY.HL7.ORG (THO) IS CASE SENSITIVE. FAILURE TO USE PROPER CASE WILL LEAD TO ERRORS IN THE BUILD.

This process uses the IG Publisher, so all details that apply to publishing a FHIR IG apply here (and more). We understand that this is a detailed process and we try to surface as few of those idiosyncratic details as possible to the Submitter community. Future development priorities include automation to continue to hide some of those tedious details from Submitters. 

Code Systems

Code Systems are managed collections of concepts.

Concept is a unitary mental representation of a real or abstract thing – an atomic unit of thought. It should be unique in a given Code System. A concept may have synonyms in terms of representation and it may be a singleton, or may be constructed of other concepts (i.e. post-coordinated concepts).

Concepts, as abstract, language- and context-independent representations of meaning, are important for the design and interpretation of the HL7 vocabulary model. They constitute the smallest semantic entities on which HL7 vocabulary models are built. The authors and the readers of a model use concepts and their relationships to build and understand the models; these are what matter to the human user of HL7 Vocabulary models. The rest of the vocabulary machinery exists to permit software manipulation of these units of thought.

There are two special types of Code Systems: V2 Tables and Concept Domains

V2 Code Systems hold the Concept Codes that are published in the V2 standards as table content. Additionally, V2 Code Systems are only created in UTG in the context of a new V2 table. See the Version 2 Tables section for more information. The current state of the V2 Tables can be viewed at https://build.fhir.org/ig/HL7/UTG/CodeSystem-v2-tables.html.

Concept Domains are named categories of like concepts (semantic types) that will be bound to one or more attributes in a static model or properties in datatypes where the data types of those attributes or properties are coded or potentially coded. See the Concept Domains section for more information about Concept Domains. The current state of the UTG Concept Domains can be viewed at https://build.fhir.org/ig/HL7/UTG/CodeSystem-conceptdomains.html.

External Code Systems (Code Systems not owned or published by HL7) are also a special case as each external Code System requires a corresponding Naming System. If you are creating/editing an external Code System, please also see the section on Naming Systems.

Representation of Code Systems in THO

There exist Code Systems in the world (a Code System is defined as being a managed collection of coded concepts). These may conveniently be thought of as nested subsets that we address in various ways in HL7. These subsets can be identified as:

  1. A subset of these are used in Healthcare IT (not necessarily exclusively)
    1. A subset of these are used in HL7 Standards and their implementation
      1. A subset of these are represented in THO
        1. A subset of these are created and maintained by HL7 (Case #1)
          1. Example: http://terminology.hl7.org/CodeSystem/adverse-event-category
        2. A subset of these are created and maintained by organizations outside of HL7, but published by HL7 through agreements (Case #2)
          1. Example: https://terminology.hl7.org/CodeSystem-v3-ada-snodent.html
        3. A subset of these are created, maintained, and published by organizations outside of HL7, but have documentation assisting the community in their use published in THO (Case #3 - often called a 'stub')
          1. Example: https://terminology.hl7.org/CodeSystem-naics.html

Element structures and naming conventions will be different depending on the type of Code System listed above. Please see https://www.hl7.org/fhir/codesystem.html for more information about the element structure. 

Changes to an Existing Code System

To edit an existing Code System

  1. Open the Code System in GitLab by navigating to the file in the folder using the Web IDE.
  2. From the input → sourceOfTruth folder, select the product family, the resource type, and the Code System to be modified to locate the correct file.
    1. For example, the file for a V3 Code System will be located the folder with a path like input\sourceOfTruth\v3\codeSystems

An additional Confluence page was created help locate a resource element by its file name based on the canonical URL, Name, or Title of the resource. Please see Cross Reference of Resource Elements and Filenames.

When making ANY changes to a Code System, the Version must be incremented according to the UTG Versioning Policy. Please review the policy to determine the type of version update required (major, minor, or technical correction) and update the 'Version' element in the 'Metadata' tab to the correct version.

Additionally, the 'Date' metadata element can be updated to the date the Code System was modified. This is optional.

Please see the Code System Metadata section for assistance on editing the Version and Date metadata elements.

VERY IMPORTANT: When modifying a Code System, you need to ensure that no Value Sets that reference the Code System will be affected by this change. If the modifications to the Code System require modifications to associated Value Sets, those changes must be made as part of your change proposal as well. 

Updating Code System Metadata

All Code System metadata elements can be modified with the exception of URL, Name, and Identifier. Updating URL, Name, or Identifier would constitute a new Code System.

For guidance on editing metadata elements, please see the Code System Metadata section. An example of an existing Code System's metadata is shown below.

Adding Concept Code(s)

New concepts can be added to a Code System in the 'Concepts' tab. Please see the Code System Concepts section for guidance on creating new codes. An example of an existing Code System's Concepts is shown below.

Modifying the Concept Hierarchy

The Concept Hierarchy can be modified in the 'Concepts' tab. Please see the Code System Concepts section for guidance on modifying the Concept Hierarchy.
There are three types of hierarchy modifications that can be made:

  • Move Concept Code in its hierarchy
  • Add Concept Code to additional hierarchy 
  • Remove Concept code from hierarchy (move to top level)

An example of an existing Code System's Concepts with a hierarchy using XML nesting is shown below. Ensure that properly placed closure tags are used. 

An example of an existing Code System's Concepts with a hierarchy using the "subsumedBy" property is shown below.

Changing a Concept's Definition, Display, or Concept Designations

A Concept's Definition, Display, or Designation can me modified within the Concept. Additional concept designations (additional print names for different languages) may also be added here. Please see the Code System Concepts section for guidance on modifying these elements and adding additional Designations. An example of an existing Code System's Concept with these elements is shown below.

Adding or Modifying Concept Code Properties

Property types must be defined before they are used for Concepts. Please see the Code System Properties for more information about adding a Property Type and the Code System Concepts section for adding Property values to existing Concepts.

Note that changing the status of a Concept is done using the 'status' property. An example of a UTG Concept Property Type (top) and FHIR Concept Property Type (bottom) is below.

An example of both Concept Properties is below.

To edit an existing Property value, modify the <valueCode> text of the value to be modified.

Determining if Value Set Changes are Needed

If the Code System being modified is referenced in the content logical definition of any Value Sets, you need to ensure that the content logical definitions of the reference Value Sets do not need to be modified as well. You can locate the referenced Value Sets by viewing the Code System in the current build and clicking on the link. If you do need to make Value Set modifications, please see Changes to an Existing Value Set.

Creating a New Code System

To create a new Code System, create a new XML file. It may be helpful to copy and paste an existing Code System resource to serve as a template for the creation of your Code System. Please see https://www.hl7.org/fhir/codesystem.html for more information about the element structure. 

Note that for V2 and FHIR Code Systems, an implicit Value Set of all codes must be created as well. Need to determine if the user will be making the implicit Value set.

New Code Systems must be added to the appropriate manifest to appear in the correct location in THO. Once creation of the new Code System is complete, please see Manifest-Driven List of Artifacts.

Code System Metadata

Code Systems have a number of required and optional metadata elements. Additional information about Code System metadata can be found at hl7.org/fhir/codesystem-definitions.html, with specific elements linked directly in the table below. The following is an example of Code System metadata.

The table below provides guidance for populating the Code System metadata elements for the creation of a new Code System. Note that elements with an asterisk (star) are required. Please see https://www.hl7.org/fhir/codesystem.html for more information about the element structure. 

Code System Metadata Elements:

Element Name

Element SpecificationData Type

Guidance (if additional is needed)

id*

https://www.hl7.org/fhir/codesystem.html#ident

https://www.hl7.org/fhir/resource.html#id


Must be unique across all Code Systems in THO (and in your FHIR IG, if applicable). It cannot have spaces, but can have hyphens and underscores. (Verify underscore and any other special characters). The id is what the THO control structures use to refer to the THO resource.

Case #1:

The id should follow the conventions we've adopted in THO which follow general good practices from the Vocab WG for Code Systems maintained and published through THO:

  • 'v3-' followed by the name in upper camel case
  • 'v2-' followed by the table number with leading zeroes (four digit table number)
  • FHIR – camel case with no prefix
  • Unified – lower camel case with no prefix

Case #2 and #3:

The id must only be unique and the string must not contain spaces, but is otherwise unconstrained. It is good practice to make sure that the id can be used as a substring in a url. The recommended convention for the id is that all characters in the string are also legal characters in a DNS URL address clause (in between the slashes). It is highly recommended to use a short name as the id so that it may be easily comprehensible. 

In THO, for those Code System resources that were imported into THO during the migration from V2 and V3, the id was prefixed with 'v2-' or 'v3-', respectively.

url*

https://www.hl7.org/fhir/resource.html#canonical

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.url


uri

Case #1

  • Enter http://terminology.hl7.org/CodeSystem/ 
  • Append the same string used in the id above after the slash
  • Nothing else can be in the url

Case #2 and #3

  • The url is any legal DNS HTTP address (does not need to match the id)
  • In some cases, the Code System content (concepts, properties, hierarchy, etc.) is maintained and published outside of HL7 by the responsible organization for the Code System but the Defining Url may be rooted in http://terminology.hl7.org. If rooting in http://terminology.hl7.org, follow the instructions for Case #1 above.

For more info on the precise requirements for the string for name, see

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.url

identifier*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.identifierIdentifier

An OID must be generated on the OID Generation page before it is entered.
System: urn:ietf:rfc:3986
Value: Enter the generated OID

version*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.versionstring

Enter '1.0.0' for new Code Systems. 

name*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.namestring

Enter the Name of the Code System.

The name must be a legal, computer processable string and should be entered with no spaces or hyphens (underscores are permitted). By convention, for ease of readability, multiple word names have the words concatenated using UpperCamelCase. In most of the THO pages, the name is what is displayed in the subtab that lists all Code Systems of that kind.

For more info on the precise requirements for the string for name, see https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.name

title*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.titlestring

Human readable name of the Code System. May include spaces, punctuation and special characters.

status*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.statuscode

Codes are always 'active'

date

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.datedateTime

If desired, enter the creation date of the Code System

publisher*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.publisherstring

Enter 'HL7 International'

contacthttps://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.contactContactDetail

Must use standard HL7 contact details: 

<contact>
    <telecom>
      <system value="url"/>
      <value value="http://hl7.org"/>
    </telecom>
<telecom> <system value="email"/> <value value="hq@HL7.org"/> </telecom>
</contact>

description*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.descriptionmarkdown

Enter the description of what the Code System is intended for. The content of the Code System can also be described here.

useContexthttps://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.useContextUsageContext

jurisdiction

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.jurisdictionCodeableConcept

Should only be populated for realm-specific vocabulary (select realm in dropdown)
Otherwise it is assumed to be universal realm

purpose

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.purposemarkdown

Enter if additional clarity is needed

copyright

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.copyrightmarkdown

Must use standard value: "This material derives from the HL7 Terminology (THO). THO is copyright ©1989+ Health Level Seven International and is made available under the CC0 designation. For more licensing information see: https://terminology.hl7.org/license"

caseSensitive*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.caseSensitiveboolean

This element is required in THO, otherwise a warning is generated. 

valueSet

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.valueSetcanonical(ValueSet)

If this Code System is intended to have an implicit value set, enter http://terminology.hl7.org/ValueSet followed with the same ID used for the Code System in the URL above

hierarchyMeaning

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.hierarchyMeaningcode

Use 'is-a' for hierarchy except for the rare cases where another option is needed

compositional

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.compositionalboolean


versionNeeded

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.versionNeededboolean


content*https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.contentcodeFor HL7 internal code systems, the concept is always 'complete'

supplements

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.supplementscanonical(CodeSystem)

Not Currently Supported

count

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.countunsignedInt

This field is not widely used

Code System Concepts

Add Concepts to the Code System, ensuring that their defined hierarchy is also correct. It is best practice to add Concepts in alphabetical order so they appear that way when rendered on THO. 

Code System Concept Elements:

Element Name

Element SpecificationData Type

Guidance

hierarchy

https://www.hl7.org/fhir/codesystem.html#hierarchyN/A

The nesting of codes will determine the location in the hierarchy. If the code system defined concepts that have multiple parents, it SHOULD NOT be represented using the hierarchy structure and should be defined using the "subsumedBy" property. Examples of both representation can be found in 

Please see https://www.hl7.org/fhir/codesystem.html#hierarchy.

code*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.codecode

Codes are string values with no spaces that must be unique in the Code System. Follow the conventions for the product family that this Code System will primarily be used:

  • V2 and V3 – uppercase letters
  • FHIR – lowercase words

display*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.displaystring

Enter the display name, or print name of the Concept. It should be a succinct and useful print name.

definition*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.definitionstring

Enter the description/definition of the concept. Note that strings SHALL NOT exceed 1MB (1024*1024 characters) in size. Strings SHOULD not contain Unicode character points below 32, except for u0009 (horizontal tab), u0010 (carriage return) and u0013 (line feed). Leading and Trailing whitespace is allowed, but SHOULD be removed when using the XML format. Note: This means that a string that consists only of whitespace could be trimmed to nothing, which would be treated as an invalid element value. Therefore strings SHOULD always contain non-whitespace content.

designation https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.designationBackboneElementFor example designations in THO, please see http://build.fhir.org/ig/HL7/UTG/CodeSystem-v2-0007.xml.html
     designation.languagehttps://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.designation.languagecode
     designation.usehttps://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.designation.useCoding
     designation.valuehttps://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.designation.valuestring

status



Not required for FHIR. Required for V2 and V3.

  • Status – bug we need to fix. We have a property concept properties of status which is only for v2 table status and only used in table concepts in v2 tables. In FHIR
    • active (A), experimental, deprecated (D), retired (R), and new (N) and backwards-compatible (B)
      • experimental only used in fhir
      • new and B using only in v2 current
      • need to discuss which values to use for which product
  • DeprecatedRequired? only when changing active to deprecated or backward compatible to deprecated
    • Date that concept was deprecated
    • Date/time

property

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.propertyBackboneElement

See section on Code System Concept Properties below for guidance. 

     codehttps://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.property.codecodeEnter the code of the Property Type.
     valuehttps://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.property.value_x_code, Coding, string, integer, boolean, dateTime, decimalUse the FHIR reference link to determine the element needed to represent the value based on the data type. For example, <valueCode> is needed to represent values with datay type of code.

Code System Concept Properties

Property types must be defined before they are used for Concepts. Please see the Code System Concepts section for adding Property values to existing Concepts.

There are two types of properties that may be used: The FHIR standard properties and the UTG properties.

The FHIR Standard properties are listed at http://build.fhir.org/codesystem-concept-properties.html

The UTG properties are listed at https://build.fhir.org/ig/HL7/UTG/CodeSystem-utg-concept-properties.html

The descriptions of each property can be viewed in the webpages linked above.

Once the Properties have been defined, they can be added to Concepts in the section below. Note that changing the status of a Concept is done using the 'status' property. 

An example of a UTG Concept Property Type (top) and FHIR Concept Property Type (bottom) is below.

An example of both Concept Properties is below.

Code System Concept Property Type Elements:

Element Name

Guidance

code*

Enter the code of the property

uri*

For UTG properties, enter http://terminology.hl7.org/CodeSystem/utg-concept-properties# followed by the code of the property being defined. For FHIR properties enter http://hl7.org/fhir/concept-properties followed by the code of the property being defined.

description

Entering a description will overwrite the default description provided by UTG concept properties Code System

type*

Enter the data type associated with the property using the Property Data Types table below.


Code System Property Elements:

Element Name

Guidance

code*

Enter the code of the defined Property Type (must be defined to be used)

valueCode*

Enter the property value


Property Data Types:

Note that there is a collection of RIM-specific properties used only in the V3 structural Code Systems. More information will be made available later.

Property Code

Type

Applies to

status

code

Code System Concepts

inactivate

code

Code System Concepts

deprecated

Code

V2 Code System Concepts

effectiveDate

dateTime

Code System Concepts

notSelectable

boolean

Code System Concepts

parent

code

Code System Concepts

child

code

Code System Concepts

partOf

code

Code System Concepts

synonym

code

Code System Concepts

comment

string

Code System Concepts

internalId

code

Code System Concepts

***For now, copy a nearby code and prepend a '1' to the number (so that it is an order of magnitude larger and will not collide with codes in other code systems. It is not currently used and will likely be removed in the future.

deprecationDate

dateTime

Code System Concepts

V2-concComment

string

V2 Code System Concepts

V2-concCommentAsPub

string

V2 Code System Concepts

ConceptualSpaceForClassCode

Coding

Concept Domains

HL7usageNotes

string

Concept Domains, Code System Concepts

subsumedBy

code

Concept Domains

contextBindingC1-effectiveDate

dateTime

Concept Domains

contextBindingC1-strength

code

Concept Domains

contextBindingC1-valueSet

string

Concept Domains

contextBindingR1-effectiveDate

dateTime

Concept Domains

contextBindingR1-strength

code

Concept Domains

contextBindingR1-valueSet

string

Concept Domains

contextBindingUS-effectiveDate

dateTime

Concept Domains

contextBindingUS-strength

code

Concept Domains

contextBindingUS-valueSet

string

Concept Domains

contextBindingUV-effectiveDate

dateTime

Concept Domains

contextBindingUV-strength

code

Concept Domains

contextBindingUV-valueSet

string

Concept Domains

contextBindingX1-effectiveDate

dateTime

Concept Domains

contextBindingX1-strength

code

Concept Domains

contextBindingX1-valueSet

string

Concept Domains

deprecationInfo

string

Concept Domains

openIssue

string

Concept Domains

source

code

Concept Domains

synonymCode

code

Concept Domains

v2-table-oid

string

V2 Tables

v2-cs-oid

string

V2 Tables

v2-cs-uri

string

V2 Tables

v2-vs-oid

string

V2 Tables

v2-vs-uri

string

V2 Tables

v2-table-type

code

V2 Tables

v2-cs-version

integer

V2 Tables

steward

code

V2 Tables

v2-where-used

string

V2 Tables

v2-binding

string

V2 Tables

v2-version-tbl-introduced

string

V2 Tables

v2-csvs-introduced

string

V2 Tables

v2-cld

string

V2 Tables

vocab-domain

string

V2 Tables

v2-codes-table-comment

string

V2 Tables

Finalizing a New Code System

New Code Systems must be added to the appropriate manifest so that they appear in the correct location in THO. Once creation of the new Code System is complete, please see Manifest-Driven List of Artifacts.

Removing a Code System

Under HL7 policy, Code Systems are never removed, but are retired. Retiring is done by moving the artifact to the retired folder,  adding it to the retired manifest and setting the status to retired. See Manifest-Driven List of Artifacts for information on moving the artifact to the retired tab.

Value Sets

This section applies to Value Sets from the V2, V3, FHIR, or Unified product families. Value Sets are managed collections of concepts drawn from one or more Code Systems. Please see https://www.hl7.org/fhir/valueset.html for more information on the Value Set element structure.

Changes to an Existing Value Set

To edit an existing Value Set, open the Value Set in the an XML editor by selecting 'File' -> 'Open' and navigating to the file in the folder that was downloaded in the 'Draft a Proposal' section. From the sourceOfTruth folder, select the product family, the resource type, and the Value Set to be modified to locate the correct file.

For example, the file for a V3 Value Set will be located the folder with a path like C:\Users\username\Documents\UP-123\input\sourceOfTruth\v3\valueSets.

An additional Confluence page was created help locate a resource element by its file name based on the canonical URL, Name, or Title of the resource. Please see Cross Reference of Resource Elements and Filenames.

When making ANY changes to a Value Set, the Version must be incremented according to the UTG Versioning Policy. Please review the policy to determine the type of version update required (major, minor, or technical correction) and update the 'Version' element in the 'Metadata' tab to the correct version.

Additionally, the 'Date' metadata element can be updated to the date the Value Set was modified. This is optional.

Please see the Value Set Metadata section for assistance on editing the Version and Date metadata elements.

Updating Value Set Metadata

All Value Set metadata elements can be modified with the exception of URL, Name, and Identifiers. Updating URL, Name, or Identifiers would constitute a new Value Set.

For guidance on editing metadata elements, please see the Value Set Metadata section. An example of an existing Value Set's metadata is shown below.

Updating the Value Set Content Logical Definition (CLD)

New rules may be added, and existing rules may be modified. For more information on defining the rules, see the Value Set Content Logical Definitions section. An example of an existing Value Set's CLD is shown below.

Creating a New Value Set

To create a new Value Set, create a new XML file. It may be helpful to copy and paste an existing Value Set resource to serve as a template for the creation of your Value Set. 

New Value Sets must be added to the appropriate manifest so that they appear in the correct location in THO. Once creation of the new Value Set is complete, please see Manifest-Driven List of Artifacts.

Value Set Metadata

Value Sets have a number of required and optional metadata elements. An example of Value Set metadata elements is below.

The table below provides guidance for populating the Value Set metadata elements for the creation of a new Value Set. Note that elements with an asterisk (star) are required. Please see https://www.hl7.org/fhir/valueset.html for more information on the Value Set element structure.

Value Set Metadata Elements:

Element Name

Element SpecificationData Type

Guidance

id*

https://www.hl7.org/fhir/valueset.html#ident

https://www.hl7.org/fhir/resource.html#id


Must be unique across all Value Sets in THO (and in your FHIR IG, if applicable). It cannot have spaces, but can have hyphens and underscores. (Verify underscore and any other special characters). The id is what the THO control structures use to refer to the THO resource.

Case #1:

The id should follow the conventions we've adopted in THO which follow general good practices from the Vocab WG for Code Systems maintained and published through THO:

  • 'v3-' followed by the name in upper camel case
  • 'v2-' followed by the table number with leading zeroes (four digit table number)
  • FHIR – camel case with no prefix
  • Unified – lower camel case with no prefix

Case #2 and #3:

The id must only be unique and the string must not contain spaces, but is otherwise unconstrained. It is good practice to make sure that the id can be used as a substring in a url. The recommended convention for the id is that all characters in the string are also legal characters in a DNS URL address clause (in between the slashes). It is highly recommended to use a short name as the id so that it may be easily comprehensible. 

In THO, for those Value Set resources that were imported into THO during the migration from V2 and V3, the id was prefixed with 'v2-' or 'v3-', respectively.

url*

http://build.fhir.org/valueset-definitions.html#ValueSet.urluri

Enter the URL of the Value Set. The URL should start with http://terminology.hl7.org/ValueSet/ followed by the information specific to the product family of the Value Set below

  • 'v3-' followed by the name in upper camel case
  • 'v2-' followed by the table number with leading zeroes (four digit table number)
  • FHIR – camel case with no prefix
  • Unified – lower camel case with no prefix

For Value Sets that includes all codes from the underlying Code System, use base http://terminology.hl7.org/ValueSet/ followed by the <id> of the Code System appended with '-all-codes'.

For example, a Value Set that includes all codes from LOINC where the LOINC Code System metadata record has <id value="v3-loinc"/>, use url  http://terminology.hl7.org/ValueSet/v3-loinc-all-codes. 

Note that product family references (e.g., 'v3-') may be cleaned up later.

identifier*

http://build.fhir.org/valueset-definitions.html#ValueSet.identifierIdentifier

An OID must be generated on the OID Generation page before it is entered.
System: urn:ietf:rfc:3986
Value: Enter the generated OID

version*

http://build.fhir.org/valueset-definitions.html#ValueSet.versionstring

Enter '1.0.0' for new Value Sets. When updating a Value Set, determine how to update the value from the UTG Versioning Policy page.

name*

http://build.fhir.org/valueset-definitions.html#ValueSet.namestring

Enter the Name of the Value Set. The name should be entered in UpperCamelCase with no spaces or hyphens (underscores are permitted)

title*

http://build.fhir.org/valueset-definitions.html#ValueSet.titlestring

Human readable name of the Code System. May include spaces, punctuation and special characters.

status*

http://build.fhir.org/valueset-definitions.html#ValueSet.statuscode

Enter 'active'

date

http://build.fhir.org/valueset-definitions.html#ValueSet.datedateTime

If desired, enter the creation date of the Value Set

publisher*

http://build.fhir.org/valueset-definitions.html#ValueSet.publisherstring

Must use "Health Level Seven International"

contacthttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.contactContactDetail

Must use standard HL7 contact details: 

<contact>
    <telecom>
      <system value="url"/>
      <value value="http://hl7.org"/>
    </telecom>
<telecom> <system value="email"/> <value value="hq@HL7.org"/> </telecom>
</contact>

description*

http://build.fhir.org/valueset-definitions.html#ValueSet.descriptionmarkdown

Enter the description of what the Value Set is intended for. The content of the Value Set can also be described here.

immutable

http://build.fhir.org/valueset-definitions.html#ValueSet.immutableboolean

As specified in the HL7 normative standard core principles of version 3 models: At the time a Value Set is defined, the business Use Case or information model design may require that the definition of the Value Set never change. In order to support this, a Value Set has a property called "immutability" which is a Boolean and refers to the Value Set Definition. If TRUE, the Value Set Definition may not be changed in the future. A new Value Set must be created. (There can be no new versions of the Value Set). If FALSE, the Value Set may be changed, and the versioning mechanism will permit traceability of such changes. Note that an immutable intensional definition may still result in an expansion that changes over time if the definition does not explicitly identify the versions of the code systems that it references, thus an isImmutable property set to TRUE will not necessarily make a Value Set expansion unchangeable over time. Therefore, to completely freeze a Value Set expansion, it must have the isImmutable property set to TRUE and the definition must either be Extensional or Intensional where reference is only to specific versions of the underlying code systems.

jurisdiction

http://build.fhir.org/valueset-definitions.html#ValueSet.jurisdictionCodeableConcept

Should only be populated for realm-specific vocabulary. Otherwise it is assumed to be universal realm.

purpose

http://build.fhir.org/valueset-definitions.html#ValueSet.purposemarkdown

Enter if additional clarity is needed

copyright

http://build.fhir.org/valueset-definitions.html#ValueSet.copyrightmarkdown

Must use standard value: "This material derives from the HL7 Terminology (THO). THO is copyright ©1989+ Health Level Seven International and is made available under the CC0 designation. For more licensing information see: https://terminology.hl7.org/license"

Value Set Content Logical Definitions 

The Value Set Content Logical Definition (CLD) is where the inclusion and exclusion criteria are specified for determining which Concept codes should be in the Value Set.

An example of an existing Value Set's CLD is shown below.
 

Value Set Content Definitions:

Element Name

Element SpecificationData Type

Guidance

lockedDate

https://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.lockedDatedate

If the Value Set is locked, enter the locked date

inactivehttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.inactivebooleanEnter 'true' if inactive codes are in the Value Set

include*

https://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.includeBackboneElement

Note that each rule only operates on one system content. See the table below for additional guidance on Includes. 

excludehttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.excludeBackboneElementNote that each rule only operates on one system content. See the table below for additional guidance on Excludes. 

Value Set Include/Exclude Rules:

Note that EITHER System or Value Sets must be used.

Element Name

Element SpecificationData Type

Guidance

system


uri

Enter the URL of the Code System. Can be used to include/exclude all Concepts from the System

version


string

Enter version of the specified System

concept


BackboneElement

Enter Concepts to be included/excluded one-by-one. Code and Display (with optional comment) should be added for each Concept. Additional Concept Designations may be added as well.

   code*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.codecode

Codes are string values with no spaces that must be unique in the Code System. Follow the conventions for the product family that this Code System will primarily be used:

  • V2 and V3 – uppercase letters
  • FHIR – lowercase words

   display*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.displaystring

Enter the display name, or print name of the Concept. It should be a succinct and useful print name.

   definition*

https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.definitionstring

Enter the description/definition of the concept. Note that strings SHALL NOT exceed 1MB (1024*1024 characters) in size. Strings SHOULD not contain Unicode character points below 32, except for u0009 (horizontal tab), u0010 (carriage return) and u0013 (line feed). Leading and Trailing whitespace is allowed, but SHOULD be removed when using the XML format. Note: This means that a string that consists only of whitespace could be trimmed to nothing, which would be treated as an invalid element value. Therefore strings SHOULD always contain non-whitespace content.

   designation https://www.hl7.org/fhir/codesystem-definitions.html#CodeSystem.concept.designationBackboneElementUse designation to add additional representation for this concept
     designation.languagehttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.include.concept.designation.languagecode
     designation.usehttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.include.concept.designation.useCoding
     designation.valuehttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.include.concept.designation.valuestring
filterhttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.include.filterBackboneElementProperty, Operation, and Value must be specified. The most common Operation is 'is-a', which can be used to include/exclude the descendants of a selected concept. Other options include =, descendant-of, is-not-a, regex, in, not-in, generalizes, exists. These are complex and require further documentation.
   propertyhttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.include.filter.propertycode
   ophttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.include.filter.opcode
   valuehttps://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.include.filter.valuestring

valueSet

https://www.hl7.org/fhir/valueset-definitions.html#ValueSet.compose.include.valueSetcanonical(ValueSet)

Use this element to use a base Value Set to build another Value Set 

Value Set CLD Examples

An example of an Enumerated Value Set is shown below:

An example of using all Concepts in a Code System is shown below:


An example of using the Filter 'is-a' operation to define Concepts in the Value Set is shown below:

Finalizing a New Value Set

New Value Set must be added to the appropriate manifest so that they appear in the correct location in THO. Once creation of the new Value Set  is complete, please see Manifest-Driven List of Artifacts.

Removing a Value Set

Under HL7 policy, Value Sets are never removed, but are retired. Retiring is done by moving the artifact to the retired folder,  adding it to the retired manifest and setting the status to retired. 

See Manifest-Driven List of Artifacts for information on moving the artifact to the retired tab.

Naming System

An HL7 Naming System is curated namespace that issues unique symbols within that namespace for the identification of concepts, people, devices, etc. and represents a "System" used within the Identifier and Coding data types. Naming Systems defined a specific code system or identifier system, so that it can be noted in a registry for other systems to find and understand an identifier.

The Code System resource defines the content of a code system, and also its preferred identifier. The Naming System resource identifies the existence of a code or identifier system, and its possible and preferred identifiers. The key difference between the resources is who creates and manages them - Code System resources are managed by the owner of the code system resource, who can properly define the features and content of the code system. Naming System resources, on the other hand, are frequently defined by 3rd parties that encounter the code system in use, and need to describe the use, but do not have the authority to define the features and content. Additionally, there may be multiple authoritative Naming System resources for a code system, but there should only be one Code System resource.

Please see https://www.hl7.org/fhir/namingsystem.html for more information on the Naming System element structure. 

Creating a New Naming System

To create a new Naming System, create a new XML file. It may be helpful to copy and paste an existing Naming System resource to serve as a template for the creation of your Naming System. 

IMPORTANT: All 'external' Code Systems require a corresponding Naming System resource.

Naming System Elements

Naming Systems have a number of required and optional metadata elements. Please see https://www.hl7.org/fhir/namingsystem.html for more information on the Naming System element structure. 


Naming System Elements:

Element Name

Element SpecificationData Type

Guidance

title*
extension

Must currently be populated as an extension, formatted like: 

<extension url="http://hl7.org/fhir/tools/StructureDefinition/extension-title">

<valueString value="NCPDP Brand Generic Indicator"/>

</extension>

url*
extension

Must currently be populated as an extension, formatted like (root of Uri must always be http://terminology.hl7.org/NamingSystem/ followed by the Name of the Naming System):

<extension url="http://hl7.org/fhir/5.0/StructureDefinition/extension-NamingSystem.url">

<valueUri value="http://terminology.hl7.org/NamingSystem/NCPDPBrandGenericIndicator"/>

</extension>

version*
extension

Must currently be populated as an extension, formatted like: 

<extension url="http://terminology.hl7.org/StructureDefinition/ext-namingsystem-version">

<valueString value="1.0.0"/>

</extension>

name*https://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.namestringEnter the Name of the Naming System. The name should be entered in Upper Camel Case with no spaces or hyphens (underscores are permitted)
status*https://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.statuscodeWhat is allowed in UTG?
kind*https://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.kindcodeUse 'codesystem' for Code Systems or 'identifier' for Identifier Systems
date*https://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.datedateTimeEnter the modified date of the Naming System
publisherhttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.publisherstringMust use "Health Level Seven International"
contacthttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.contactContactDetail

Must use standard HL7 contact details: 

<contact>
    <telecom>
      <system value="url"/>
      <value value="http://hl7.org"/>
    </telecom>
<telecom> <system value="email"/> <value value="hq@HL7.org"/> </telecom>
</contact>
responsiblehttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.responsiblestringEnter the maintainer 
typehttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.typeCodeableConceptEnter the type, if applicable, from https://www.hl7.org/fhir/valueset-identifier-type.html
descriptionhttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.descriptionmarkdownEnter the description of the Naming System
jurisdictionhttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.jurisdictionCodeableConceptEnter the type, if applicable, from https://www.hl7.org/fhir/valueset-jurisdiction.html
usagehttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.usagestring

Enter guidance on the use of the namespace, including the handling of formatting characters, use of upper vs. lower case, etc

uniqueId*https://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.uniqueIdBackboneElement

Represent all known unique identifiers for this system.

   type*https://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.uniqueId.typecodeEnter the identifier type. Options are oid, uuid, uri or other.
   value*https://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.uniqueId.valuestringEnter the string of the identifier in the format of the selected type
   preferredhttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.uniqueId.preferredbooleanEnter as "true" if identifier is the preferred identifier of this type, otherwise enter as "false"
   commenthttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.uniqueId.commentstringEnter the period over which this identifier is considered appropriate to refer to the naming system. Empty end dates can be used to convey that there is no current end date.
   periodhttps://www.hl7.org/fhir/namingsystem-definitions.html#NamingSystem.uniqueId.periodperiodEnter any notes about the past or intended use of this identifier to refer to the naming system.


When creating or modifying external Naming System and Code System entries, a few additional steps need to occur as compared to Code System/ Value Set editing. 

  1. Add new Code Systems and Naming Systems under the appropriate folder via ....\UP-XXX\input\sourceOfTruth\external\hta
  2. The following three extensions are required for the 'title', 'URL', and 'Version'. They must be used to declare these values:
    <extension url="http://hl7.org/fhir/tools/StructureDefinition/extension-title">
    <valueString value="NCPDP Brand Generic Indicator"/>
    </extension>
    <extension url="http://hl7.org/fhir/5.0/StructureDefinition/extension-NamingSystem.url">
    <valueUri value="http://terminology.hl7.org/NamingSystem/NCPDPBrandGenericIndicator"/>
    </extension>
    <extension url="http://terminology.hl7.org/StructureDefinition/ext-namingsystem-version">
    <valueString value="1.0.0"/>
    </extension>
    1. Note that Naming System URLs must always be rooted in http://terminology.hl7.org/NamingSystem/
  3. You may wish to add 'effective dates' to display when each uri's start/end effective dates to Naming Systems, see the example below:
  4. Ensure newly added external code systems are added to the external-Rendering.xml file in ...\UP-XXX\input\sourceOfTruth\control-manifests
    1. See Adding a Vocabulary Artifact to a List (Manifest)
  5. Check ALL other manifests (except those with FHIR in the name) if the identifier has been changed, and correct the identifiers
    1. Manifests are located in ...\UP-XXX\input\sourceOfTruth\control-manifests
  6. Declare the new/modified code system as a 'special-url' in the utg.xml file in ...\UP-XXX\input. 

    1. This is important to add or it will throw errors

Changes to an Existing Naming System

To edit an existing Naming System, open the Naming System in and XML Editor by selecting 'File' -> 'Open' and navigating to the file in the folder that was downloaded in the 'Draft a Proposal' section. From the sourceOfTruth folder, select the product family, the resource type, and the Naming System to be modified to locate the correct file.

For example, the file for a V3 Naming System will be located the folder with a path like C:\Users\username\Documents\UP-123\input\sourceOfTruth\v3\namingSystems.

When making ANY changes to a Naming System, the Version must be incremented according to the UTG Versioning Policy. Please review the policy to determine the type of version update required (major, minor, or technical correction) and update the 'Version' element in the 'Metadata' tab to the correct version.

Additionally, the 'Date' metadata element can be updated to the date the Naming System was modified. This is optional.

Please ensure you go through the list of extra steps above to ensure that the changes build properly as there are some additional steps required when editing Naming Systems. 

Updating a Naming System 

All Naming System elements can be modified with the exception of OID and Name. Updating the OID or Name would constitute a new Naming System.

To edit a Naming System, replace the text in any of the fields.  Naming System identifiers should never be Deleted, but can be retired by setting Preferred to "false". See the Naming System Elements section for guidance on editing Naming Systems. 

Concept Domains

An HL7 Concept Domain is a named category of like concepts (a semantic type) that is specified in the Vocabulary Declaration of an attribute in an information model or property in a data type, whose data types are coded or potentially coded, and may be used in a Context Binding. Concept Domains exist to constrain the intent of the coded element while deferring the binding of the element to a specific set of codes until later in the specification development process. Thus, Concept Domains are independent of any specific vocabulary or Code System. Concept Domains are hierarchical in nature, and each hierarchy represents a constraint path from a broader to a narrower semantic category. In HL7's base models – the RIM and the Abstract Data Types specification – all coded elements are tied to these abstract definitions of the allowed types of concepts.

The deferral of the association between a coded element and its allowed coded values is useful because it may not be possible to achieve consensus on the Value Set to be used within a model at the level at which the model is being developed. For example, it may be possible to gain international consensus on messages for submitting insurance claims for health care services. However, gaining international consensus on a single set of billing codes is unlikely any time soon.

Concept Domains are universal in nature (independent of any Binding Realm), so the name for a Concept Domain should never contain any reference to a specific Binding Realm. Concept Domains are also present to permit binding to more than one specific terminology (in general), so the names also should not contain a reference to a specific coding system. Concept Domains are registered with HL7 International: they are proposed as part of the HL7 standards development process and are approved by the RIM harmonization process. Both processes are described in the HL7 Development Framework (HDF).

A Concept Domain is documented by specifying a name and a narrative definition. In addition, at least three concept examples that represent possible values for the attribute or data type property are required to illustrate the semantic space. The examples should represent concepts that characterize the intent and purpose of the Concept Domain. This can be accomplished in one of the following ways:

  1. Including three example concepts as part of the narrative definition;
  2. Context Binding the Concept Domain to a Value Set that contains at least three example concepts in the context of the Example Binding Realm; or
  3. Context Binding the Concept Domain with a Value Set that contains a set of concepts which completely cover the intended meaning of the domain, using either the Universal or Representative Binding Realm as a context.

Concept Domains may be bound to one of five binding realms: UV (universal), X1 (example), R1 (representative), US (United States specific), and C1 (unclassified).

For definitions for each binding, please see Core Principles.

Each binding is represented with a triplet of properties: valueSet bound in that realm, effective date of the binding, and binding strength of that value set binding in that realm. Need to enter all three if a binding exists. Only one binding per realm.

If binding to a non-existing Value Set, you will need to create the Value Set. Additionally, if the Value Set is based on a non-existing Code System, you will need to create the Code System. See the Creating a New Code System and Creating a New Value Set sections for more information.

Creating a New Concept Domain

Adding a Concept Domain (which is represented as a Code System in UTG) follows the same approach for modifying an existing Code System. See the Adding Concept Code(s) section for more information.

Concept Domains are located here: http://build.fhir.org/ig/HL7/UTG/CodeSystem-conceptdomains.html

New Concept Domains are added as Codes in the Concept Domains Code System. To open the Code System, use an XML editor to navigate to UP-123\input\sourceOfTruth\unified\codeSystems and open conceptdomains.xml.

Populate a new Concept code using the guidance below to add the Concept Domain.

Element Name (or property name)

Guidance

Depth*

The depth indicates the hierarchy of the Concept Domain

Code*

The Code should be a descriptive name in upper camel case.

Display*

The Display should match the Code for Concept Domains

Definition*

Enter the description/definition of the concept. Note that strings SHALL NOT exceed 1MB (1024*1024 characters) in size. Strings SHOULD not contain Unicode character points below 32, except for u0009 (horizontal tab), u0010 (carriage return) and u0013 (line feed). Leading and Trailing whitespace is allowed but SHOULD be removed when using the XML format. Note: This means that a string that consists only of whitespace could be trimmed to nothing, which would be treated as an invalid element value. Therefore strings SHOULD always contain non-whitespace content.

ConceptualSpaceForClassCode

Enter if needed. Valid only when concept domain is used in V3 and only when it is used to indicate information about the use of a code in a RIM class where the class name is specific. The only classes that are affected are EntityCode/EntityClass, ActCode/ActClass, and RoleCode/RoleClass

HL7usageNotes

Enter any comments on how the Concept Domain is used (if needed)

subsumedBy

Enter the Code which subsumes the Concept Domain if applicable

contextBindingC1-effectiveDate

Effective Date of the specified Value Set bound to this Concept Domain in the Unclassified Realm.

contextBindingC1-strength

Coding strength for the Example binding; either CWE or CNE.

contextBindingC1-valueSet

Identifies the Value Set bound to this Concept Domain in the Example Realm.

contextBindingR1-effectiveDate

Effective Date of the specified Value Set bound to this Concept Domain in the Representative Realm.

contextBindingR1-strength

Coding strength for the Representative binding; either CWE or CNE.

contextBindingR1-valueSet

Identifies the Value Set bound to this Concept Domain in the Representative Realm.

contextBindingUS-effectiveDate

Effective Date of the specified Value Set bound to this Concept Domain in the US Realm.

contextBindingUS-strength

Coding strength for the US Realm binding; either CWE or CNE.

contextBindingUS-valueSet

Identifies the Value Set bound to this Concept Domain in the US (United States of America) Realm.

contextBindingUV-effectiveDate

Effective Date of the specified Value Set bound to this Concept Domain in the Universal Realm.

contextBindingUV-strength

Coding strength for the Universal Realm binding; either CWE or CNE.

contextBindingUV-valueSet

Identifies the Value Set bound to this Concept Domain in the Universal Realm.

contextBindingX1-effectiveDate

Effective Date of the specified Value Set bound to this Concept Domain in the Example Realm.

contextBindingX1-strength

Coding strength for the Example binding; either CWE or CNE.

contextBindingX1-valueSet

Identifies the Value Set bound to this Concept Domain in the Example Realm.

deprecationInfo

Enter commentary and release IDs when they were deprecated, and possibly replacement information

openIssue

Do not use

source*

Indicates the etiology of this domain, i.e. which HL7 product family or other area that the domain originally was needed for and triggered its creation. Current values are v2, v3, cda. Note the ones for CDA have been added manually.

synonymCode

Enter the code of the synonym if needed.

Version 2 Tables

Version 2 Tables are held in the single Code System, V2 Tables, which can be viewed at https://build.fhir.org/ig/HL7/UTG/CodeSystem-v2-tables.html. Each concept code in V2 tables holds all of the associated reference information to Code Systems, Value Sets, Concept Domains, and other things associated with the table. There are a very large number of extended UTG concept properties to support this reference information for the V2 Table concept codes. Adding a new V2 Table requires and underlying Value Set to also be added if the table has concept codes that are to be listed in the V2 standards. If HL7 defines and maintains these concept codes, then a HL7/UTG Code System defining these Concept codes must also be created (See Code Systems above).

The URLs and the OIDs for any such created Value Sets or Code Systems must be captured in the properties of the newly created Table entry, which is made by adding a new Concept code to the V2 Tales Codes System.

The table below provides guidance for the creation of a new V2 Table code with associated reference information.

Scenario

Guidance

Table has no Content or associated Concept Domain

Only a Table Number and Description need to be added to the V2 Tables Code System.

Table has no Content but has associated Concept Domain

The Table needs to be associated with an existing Concept Domain or a new Concept Domain must be created.

Table has Content Informed by a Value Set Build on existing Code System content

The Table needs to be associated with the Value Set and Code System that the Value Set references. If the Value Set includes all codes from a Code System (it is implicit) then the table can be associated with the implicit Value Set. If the Value Set does not include all codes from a Code System, then a new Value Set must be created. A new Value Set must also be created if it is based on a non-HL7 (or external) Code System.

Table has defining underlying HL7 Code System, a Value Set that informs Table content, and an associated Concept Domain

The Table needs to be associated with the Value Set and Code System that the Value Set references. The Code System must be created if it does not already exist. If the Value Set includes all codes from a Code System (it is implicit) then the table can be associated with the implicit Value Set. If the Value Set does not include all codes from a Code System, then a new Value Set must be created. A new Value Set must also be created if it is based on a non-HL7 (or external) Code System. Lastly, the Concept Domain must be created.


Based on the guidance in the table above, the following sections may be applicable:

Code System Concepts – for adding code to V2 Tables

Creating a New Code System

Creating a New Value Set

Creating a New Concept Domain

V2 Tables Codes and Properties

In addition to following the guidance above for creating a new V2 Table entry, there are a number of required and optional properties that are specific to V2 Tables.

Adding a code and its properties to V2 Tables (which is represented as a Code System in UTG) follows the same approach for modifying an existing Code System. See the Code System Concepts section for more information.

New V2 Tables are added as Codes in the V2 Tables Code System. To open the Code System, use an XML editor to navigate to UP-123\input\sourceOfTruth\v2 and open v2-tables.xml.

Populate a new Concept code using the guidance below to add the V2 Table.

Element Name (or property name)

Guidance

depth

V2 Table Codes should always have a depth of 0

code

Enter the Table number. New Table numbers have to come from the V2 Management Group. Request a new Table number from the V2 editorial staff. The code is a four digit table number with leading zeros.

display

Enter the Display name of table in Title Case (can be multiple words separated with spaces, each word capitalized)

definition

Enter the description/definition of the concept. Note that strings SHALL NOT exceed 1MB (1024*1024 characters) in size. Strings SHOULD not contain Unicode character points below 32, except for u0009 (horizontal tab), u0010 (carriage return) and u0013 (line feed). Leading and Trailing whitespace is allowed but SHOULD be removed when using the XML format. Note: This means that a string that consists only of whitespace could be trimmed to nothing, which would be treated as an invalid element value. Therefore strings SHOULD always contain non-whitespace content.

v2-table-oid

Enter the OID value for the table object. The Table OID value will be 2.16.840.1.113883.12.'newtablenumber' (no leading zeroes).

v2-cs-oid

Enter the OID of the code system associated with the table

v2-cs-uri

Enter the URI of the code system associated with the table

v2-vs-oid

Enter the OID of the value set informing the content of the table

v2-vs-uri

Enter the URI of the value set informing the content of the table

v2-table-type

Enter the Type of V2 table. Options are HL7, user, or external.

v2-cs-version

Enter the version of the code system informing the table

steward

Enter the steward workgroup for the table

v2-where-used

Enter the string holding the segment and field where the table is bound in the international standard.

v2-binding

Enter the coded value identifying the binding realm for those tables that have a binding to a value set. 0=no binding or binding N/A; 1=Example; 2=Representative; 3=Universal; 4=US Realm.

v2-version-tbl-introduced

Enter the HL7 V2 version when the V2 Table was introduced

v2-version-csvs-introduced

Enter the HL7 V2 version when the code system and value set were introduced. This is either the creation date of the V2 code system or value set objects, or the date when the FHIR or V3 or External code system and/or value set were associated to the table.

v2-cld

Enter the integer that correctly describes the CLD. Categorization of Content Logical Definition for the V2 value set informing the table, as printed in the V2 ballot. 0=no expansion, 1=all codes, 2=enumerated, 3=V3 value set definition, 4=unique intensional definition, 5=non-HL7 value set definition, 6=FHIR value set definition

vocab-domain

Enter the associated Concept Domain for the table

v2-codes-table-comment

Enter comment if needed

Manifest-Driven List of Artifacts

Manifest files are used to organize vocabulary artifacts based on their product family and resource type on the HL7 Terminology pages. The terminology pages reference these manifests when they are built to organize all vocabulary artifacts into tabs and subtabs. Tabs are used to separate artifacts into resource types, while subtabs are used to separate artifacts based on their product family within the appropriate resource type tab. 

Tabs and Their Manifests

The manifest files are all located within the input/sourceOfTruth/control-manifests folder within your cloned content (i.e. C:\Users\username\Documents\UP-159\input\sourceOfTruth\control-manifests). All manifests with 'rendering' in the name are used to organize the artifacts into tabs and subtabs. These files include:

File NameDescription
cda-Rendering.xmlOrganizes CDA-owned vocabulary artifacts.
extallcontent-Rendering.xmlOrganizes externally-owned vocabulary artifacts that contain content that is believed to be complete. These artifacts are not owned or managed by HL7.
extcsmetadatarecords-Rendering.xmlOrganizes externally-owned vocabulary artifacts whose metadata and identifiers have been endorsed by the HTA. These artifacts are not owned or managed by HL7.
external-Rendering.xmlOrganizes externally-owned vocabulary artifacts whose metadata and identifiers have NOT been endorsed by the HTA. These artifacts are not owned or managed by HL7.
extwcontent-Rendering.xmlOrganizes externally-owned vocabulary artifacts that contain content that is known to be incomplete. These artifacts are not owned or managed by HL7.
fhir-Rendering.xmlOrganizes FHIR-owned vocabulary artifacts.
identifiers-Rendering.xmlOrganizes Identifier Systems. These are represented as Naming Systems.
pendingCS-Rendering.xmlOrganizes metadata and tracking information for code systems that are intended to be published in the HL7 Terminology pages in the near future.
retiredExt-Rendering.xmlOrganizes externally-owned vocabulary artifacts that have been retired.
retired-Rendering.xmlOrganizes artifacts from any product family that have been retired.
techidsOther-RenderingOrganizes externally-owned vocabulary artifact identifiers that have NOT been endorsed by the HTA. These are also referred to as Naming Systems.
techids-RenderingOrganizes externally-owned vocabulary artifact identifiers that have been endorsed by the HTA. These are also referred to as Naming Systems.
unified-Rendering.xmlOrganizes artifacts that span across all product families.
v2-Rendering.xmlOrganizes V2-owned vocabulary artifacts.
v3-Rendering.xmlOrganizes V3-owned vocabulary artifacts.

To add, remove, or move artifacts between subtabs, please see the sections below. 

Special Purpose Manifests

Several other special purpose manifest files are located in the same input/sourceOfTruth/control-manifests. These manifests define what gets published for each of the product families and are under the discretion of the management groups. There are also a handful of other manifests to be implemented in the future for various groupings, such as collecting information from other organizations. These should not be edited for proposals at this time.

File Name
fhir-Normative.xml
v2-Publishing.xml
v3-Publishing.xml

Adding a Vocabulary Artifact to a List (Manifest)

For the newly added vocabulary artifact to render on the UTG build pages, you must add an entry for the Code System or Value Set to the appropriate rendering file. Rendering files are all located in the 'control-manifests' folder from input → sourceOfTruth.

Open the rendering xml file that aligns with the product family of the artifact that you are adding. For example, if you are adding a V2 Code System, you would open 'v2-Rendering.xml'.

Artifacts are added to the rendered pages through entries. Simply copy an existing entry and paste it to create a new entry. Then modify it so that the reference matches the <id> element of the artifact you are adding. Also make sure that the type in the 'reference' and 'type' field matches the artifact type. Please keep entries in numerical or alphabetical order depending on the product family representation.

Once the entry has been added, you can save the file and move on to the commit process documented below.

Removing a Vocabulary Artifact from a List (Manifest)

Some change proposals could require removing an artifact from the rendered pages by removing it from the list (or manifest). To remove artifacts to prevent them from rendering on the UTG build pages, you must remove the entry for the Code System or Value Set from the appropriate rendering file. Rendering files are all located in the 'control-manifests' folder from input → sourceOfTruth.


Open the rendering xml file that aligns with the product family of the artifact that you are removing. For example, if you are removing a V2 Code System, you would open 'v2-Rendering.xml'.

Artifacts are added to the rendered pages through entries. Simply highlight the entry to be removed and delete it.


Once the entry has been removed, you can save the file and move on to the commit process documented below.

Moving a Vocabulary Artifact Between Lists (Manifests)

It is possible that you may need to move a vocabulary artifact from one list to another (i.e. one subtab to another). For example, if a V3 code system is unified, the entry should be removed from the v3-Rendering.xml file and added to the unified-Rendering.xml file using the techniques discussed in the sections above. 

Special Cases

This section documents resource changes that require specific guidance not specific to any section above. 

Deprecation

If deprecating an aggregate (Code System, Value Set, Naming System, etc.) or an individual (Code System concept, identifier, etc.) please refer to the Vocab Work Group's Policy on Deprecation of Vocabulary Objects in THO for guidance on the process to deprecate. 


  • No labels