Resource type: codesystem

Description

The CodeSystem resource is used to declare the existence of and describe a code system or code system supplement and its key properties, and optionally define a part or all of its content.

Elements

PathShortDefinitionComments
Declares the existence of and describes a code system or code system supplementThe CodeSystem resource is used to declare the existence of and describe a code system or code system supplement and its key properties, and optionally define a part or all of its content.
urlCanonical identifier for this code system, represented as a URI (globally unique) (Coding.system)An absolute URI that is used to identify this code system when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which at which an authoritative instance of this code system is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the code system is stored on different servers. This is used in [Coding](datatypes.html#Coding).system.Can be a urn:uuid: or a urn:oid: but real http: addresses are preferred. Multiple instances may share the same URL if they have a distinct version. The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in [Technical and Business Versions](resource.html#versions). In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the [meta.source](resource.html#meta) element to indicate where the current master source of the resource can be found.
identifierAdditional identifier for the code system (business identifier)A formal identifier that is used to identify this code system when it is represented in other formats, or referenced in a specification, model, design or an instance.Typically, this is used for identifiers that can go in an HL7 V3 II (instance identifier) data type, and can then identify this code system outside of FHIR, where it is not possible to use the logical URI. Note that HL7 defines at least three identifiers for many of its code systems - the FHIR canonical URL, the OID and the V2 Table 0396 mnemonic code.
versionBusiness version of the code system (Coding.version)The identifier that is used to identify this version of the code system when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the code system author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence. This is used in [Coding](datatypes.html#Coding).version.There may be different code system instances that have the same identifier but different versions. The version can be appended to the url in a reference to allow a reference to a particular business version of the code system with the format [url]|[version].
nameName for this code system (computer friendly)A natural language name identifying the code system. This name should be usable as an identifier for the module by machine processing applications such as code generation.The name is not expected to be globally unique. The name should be a simple alphanumeric type name to ensure that it is machine-processing friendly.
titleName for this code system (human friendly)A short, descriptive, user-friendly title for the code system.This name does not need to be machine-processing friendly and may contain punctuation, white-space, etc.
statusdraft | active | retired | unknownThe date (and optionally time) when the code system resource was created or revised.Allows filtering of code systems that are appropriate for use versus not.
experimentalFor testing purposes, not real usageA Boolean value to indicate that this code system is authored for testing purposes (or education/evaluation/marketing) and is not intended to be used for genuine usage.Allows filtering of code systems that are appropriate for use versus not.
dateDate last changedThe date (and optionally time) when the code system was published. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the code system changes.Note that this is not the same as the resource last-modified-date, since the resource may be a secondary representation of the code system. Additional specific dates may be added as extensions or be found by consulting Provenances associated with past versions of the resource.
publisherName of the publisher (organization or individual)The name of the organization or individual that published the code system.Usually an organization but may be an individual. The publisher (or steward) of the code system is the organization or individual primarily responsible for the maintenance and upkeep of the code system. This is not necessarily the same individual or organization that developed and initially authored the content. The publisher is the primary point of contact for questions or issues with the code system. This item SHOULD be populated unless the information is available from context.
contactContact details for the publisherContact details to assist a user in finding and communicating with the publisher.May be a web site, an email address, a telephone number, etc.
descriptionNatural language description of the code systemA free text natural language description of the code system from a consumer's perspective.This description can be used to capture details such as why the code system was built, comments about misuse, instructions for clinical use and interpretation, literature references, examples from the paper world, etc. It is not a rendering of the code system as conveyed in the 'text' field of the resource itself. This item SHOULD be populated unless the information is available from context (e.g. the language of the code system is presumed to be the predominant language in the place the code system was created).
useContextThe context that the content is intended to supportThe content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate code system instances.When multiple useContexts are specified, there is no expectation that all or any of the contexts apply.
jurisdictionIntended jurisdiction for code system (if applicable)A legal or geographic region in which the code system is intended to be used.It may be possible for the code system to be used in jurisdictions other than those for which it was originally designed or intended.
purposeWhy this code system is definedExplanation of why this code system is needed and why it has been designed as it has.This element does not describe the usage of the code system. Instead, it provides traceability of ''why'' the resource is either needed or ''why'' it is defined as it is. This may be used to point to source materials or specifications that drove the structure of this code system.
copyrightUse and/or publishing restrictionsA copyright statement relating to the code system and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the code system.... Sometimes, the copyright differs between the code system and the codes that are included. The copyright statement should clearly differentiate between these when required.
caseSensitiveIf code comparison is case sensitiveIf code comparison is case sensitive when codes within this system are compared to each other.If this value is missing, then it is not specified whether a code system is case sensitive or not. When the rule is not known, Postel's law should be followed: produce codes with the correct case, and accept codes in any case. This element is primarily provided to support validation software.
valueSetCanonical reference to the value set with entire code systemCanonical reference to the value set that contains the entire code system.The definition of the value set SHALL include all codes from this code system and only codes from this code system, and it SHALL be immutable.
hierarchyMeaninggrouped-by | is-a | part-of | classified-withThe meaning of the hierarchy of concepts as represnted in this resource.Note that other representations might have a different hierarchy or none at all, and represent the information using properties.
compositionalIf code system defines a compositional grammarThe code system defines a compositional (post-coordination) grammar.Note that the code system resource does not define what the compositional grammar is, only whether or not there is one.
versionNeededIf definitions are not stableThis flag is used to signify that the code system does not commit to concept permanence across versions. If true, a version must be specified when referencing this code system.Best practice is that code systems do not redefine concepts, or that if concepts are redefined, a new code system definition is created. But this is not always possible, so some code systems may be defined as 'versionNeeded'. Most code systems occasionally refine the displays defined for concepts between versions. Contexts in which the concept display values are validated may require that the version be specified for some code systems irrespective of the value of this property.
contentnot-present | example | fragment | complete | supplementThe extent of the content of the code system (the concepts and codes it defines) are represented in this resource instance.
supplementsCanonical URL of Code System this adds designations and properties toThe canonical URL of the code system that this code system supplement is adding designations and properties to.The most common use of a code system supplement is to add additional language support.
countTotal concepts in the code systemThe total number of concepts defined by the code system. Where the code system has a compositional grammar, the basis of this count is defined by the system steward.The count of concepts defined in this resource cannot be more than this value but may be less for several reasons - see the content element.
filterFilter that can be used in a value setA filter that can be used in a value set compose statement when selecting concepts using a filter.Note that filters defined in code systems usually require custom code on the part of any terminology engine that will make them available for use in value set filters. For this reason, they are generally only seen in high value published terminologies.
filter.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
filter.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
filter.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
filter.codeCode that identifies the filterThe code that identifies this filter when it is used as a filter in [ValueSet](valueset.html#).compose.include.filter.
filter.descriptionHow or why the filter is usedA description of how or why the filter is used.
filter.operatorOperators that can be used with filterA list of operators that can be used with the filter.
filter.valueWhat to use for the valueA description of what the value for the filter should be.
propertyAdditional information supplied about each conceptA property defines an additional slot through which additional information can be provided about a concept.
property.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
property.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
property.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
property.codeIdentifies the property on the concepts, and when referred to in operationsA code that is used to identify the property. The code is used internally (in CodeSystem.concept.property.code) and also externally, such as in property filters.
property.uriFormal identifier for the propertyReference to the formal meaning of the property. One possible source of meaning is the [Concept Properties](codesystem-concept-properties.html) code system.
property.descriptionWhy the property is defined, and/or what it conveysA description of the property- why it is defined, and how its value might be used.
property.typecode | Coding | string | integer | boolean | dateTime | decimalThe type of the property value. Properties of type "code" contain a code defined by the code system (e.g. a reference to another defined concept).
conceptConcepts in the code systemConcepts that are in the code system. The concept definitions are inherently hierarchical, but the definitions must be consulted to determine what the meaning of the hierarchical relationships are.If this is empty, it means that the code system resource does not represent the content of the code system.
concept.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
concept.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.codeCode that identifies conceptA code - a text symbol - that uniquely identifies the concept within the code system.
concept.displayText to display to the userA human readable string that is the recommended default way to present this concept to a user.
concept.definitionFormal definitionThe formal definition of the concept. The code system resource does not make formal definitions required, because of the prevalence of legacy systems. However, they are highly recommended, as without them there is no formal meaning associated with the concept.
concept.designationAdditional representations for the conceptAdditional representations for the concept - other languages, aliases, specialized purposes, used for particular purposes, etc.Concepts have both a ```display``` and an array of ```designation```. The display is equivalent to a special designation with an implied ```designation.use``` of "primary code" and a language equal to the [Resource Language](resource.html#language).
concept.designation.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
concept.designation.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.designation.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.designation.languageHuman language of the designationThe language this designation is defined for.In the absence of a language, the resource language applies.
concept.designation.useDetails how this designation would be usedA code that details how this designation would be used.If no use is provided, the designation can be assumed to be suitable for general display to a human user.
concept.designation.valueThe text value for this designationThe text value for this designation.
concept.propertyProperty value for the conceptA property value for this concept.
concept.property.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
concept.property.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.property.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.property.codeReference to CodeSystem.property.codeA code that is a reference to CodeSystem.property.code.
concept.property.value[x]Value of the property for this conceptThe value of this property.
concept.conceptChild Concepts (is-a/contains/categorizes)Defines children of a concept to produce a hierarchy of concepts. The nature of the relationships is variable (is-a/contains/categorizes) - see hierarchyMeaning.

Scope and Usage

The FHIR terminology specification is based on two key concepts, originally defined in HL7 v3 Core Principles:

Code systems define which codes (symbols and/or expressions) exist, and how they are understood. Value sets select a set of codes from one or more code systems to specify which codes can be used in a particular context.

The CodeSystem resource is used to declare the existence of a code system, and its key properties:

In addition, the CodeSystem resource may list some or all of the concepts in the code system, along with their basic properties (code, display, definition), designations, and additional properties. Code System resources may also be used to define supplements, that extend an existing code system with additional designations and properties.

The CodeSystem resource is not intended to support the process of maintaining code systems. Instead, the focus is on publishing the properties and optionally the content of a code system for use throughout the FHIR eco-system, such as to support value set expansion and validation. Note that the important existing (large) code systems (SNOMED CT, LOINC, RxNorm, ICD family, etc.) all have their own maintenance systems and distribution formats, and CodeSystem is generally not an efficient way to distribute their content, though it is used as one way of declaring the filters and properties associated with those code systems.

Boundaries and Relationships

The CodeSystem resource declares the existence of a code system and its key properties including its preferred identifier. The NamingSystem 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 - CodeSystem resources are managed by the owner or publisher of the code system, who can properly define the code system features and content. NamingSystem 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 NamingSystem resources for a code system, but ideally there would be only one authoritative CodeSystem resource (identified by its canonical URL) that is provided by the code system publisher, with multiple copies distributed on additional FHIR servers or elsewhere and used where needed.

Both Code System supplements and Concept Maps may be used to define relationships between concepts in different systems. ConceptMaps are assertions of the relationships between different concepts that are associated with particular contexts of use, while CodeSystem supplements are used to define inherent properties and semantics of the concepts in the code system

Background and Context

When using code systems and value sets, proper differentiation between a code system and a value set is important. This is one very common area where significant clinical safety risks occur in practice. Implementers should be familiar with the content in Using Codes in Resources.

CodeSystem Identification

A code system has three identifiers. The first two can be used to reference the code system in the FHIR context:

For example, the code systems published as part of the FHIR specification all have a location ("literal") URI which is the URL where they may be accessed in the FHIR specification itself. However, while a new version of the FHIR specification is being prepared, code systems that are published in the drafts will not be found in the current FHIR specification version.

Because it is common practice to copy (cache) code systems locally, most references to code systems can use either the canonical URL or the location ("literal") URL.

The third code system identifier is used typically for external references to the code system outside of FHIR:

For further information regarding resource identification, see Resource Identity.

This means that each code system has 2 different URIs that can be used to reference it - its canonical URL (the url element), and its local location from which it may be retrieved (which includes the id element). Because it is common practice to copy (cache) code systems locally, most references to code systems use the canonical URL.

Alternatively, the identifier and version elements may be used to reference this code system in a design, a profile, a CDA template or HL7 v3 message (in the CD data type codeSystem and codeSystemVersion properties). These different contexts may make additional restrictions on the possible values of these elements. The identifier is generally not needed when using code systems in a FHIR context, where the canonical URL is always the focus.

Versioning Code Systems

Most code systems evolve over time, due to corrections, clarifications, and changes to approach or underlying knowledge or reality. If these changes lead to the meanings of existing codes changing significantly, then the interpretation of the code system becomes version dependent. This significantly complicates implementation based on the code system, to the point where it is not clear that safety can be assured, so changing the meaning of an existing code SHOULD be avoided whenever possible. It is preferable to assign a new identifier to a code system when any concepts in it have a significant change in meaning (for example, the German diagnostic classification code system ICD10GM2009 has a different system to ICD10GM2008), but this also can have substantial impact on implementation, so is often not practical - for instance, SNOMED CT has a complex version release framework, which may lead to variations in meaning of concepts, but there is only one identifier for SNOMED CT.

For this reason, a code system MAY provide a version identifier which can be specified in CodeSystem.version. The version specific identifier SHOULD be provided whenever there are potentially significant changes in meaning across multiple releases of a code system. There is no particular format requirement for the version identifier, though HL7 recommends a date-based approach.

When the CodeSystem.versionNeeded is 'true', then the version identifier SHALL be used in Coding instances that refer to the code system.

Where the terminology does not clearly define what string should be used to identify code system versions, the recommendation is to use as the version string the date (expressed in FHIR date format) on which the version of the code system that is being used was officially published.

Multi-part Code Systems

The simple case for a code system is that the entire code system - all the concepts and their codes, designations and properties are distributed in a single CodeSystem resource. However, for a variety of reasons, code systems may be distributed by the code system authority in a set of fragments, and other authorities may issue additional designations and properties in supplements.

Code System Fragments

If the CodeSystem.content value is fragment, then the resource describes part of a code system.

Code Systems may be distributed in fragments for the following reasons:

The following rules apply to code system fragments:

Code System Supplements

If the CodeSystem.content value is supplement, then the resource describes a code system supplement. The following rules apply to code system supplements:

If a supplement needs to define new concepts/codes to use as property values, it can be paired with a new (possibly contained) Code System and use the Coding type for the property values.

The impact of Code System supplements on value set expansion - and therefore value set validation - is subject to ongoing experimentation and implementation testing, and further clarification and additional rules might be proposed in future versions of this specification.

Display, Definition and Designations

Concepts have both a display and a definition. The display is a short text that represents the meaning of the concept to human users, while the definition is a more formal statement of the meaning of the concept, which is often longer. All concepts SHOULD have a display and a definition, though it is not mandatory because there are many cases where no such properties are provided, in spite of their utility and importance for clear and safe communication.

In addition to the display and definition, a concept can have one or more designation elements. The display is equivalent to a special designation with an implied designation.use meaning "primary code/designation" and a language equal to the Resource Language. The designations can provide additional displays for other language, as well as designations for other purposes. When using concepts, applications use the display and designation unless the language or usage in context provide a reason to use one of the designations.

Properties

Each code system can define one or more concept properties. Each concept defined by the code system may have one or more values for each concept property defined by the code system. Typical uses for properties include:

Properties are identified by their master URI (CodeSystem.property.uri), and then, by their code (CodeSystem.property.code), which is used both internally within the code system resource (CodeSystem.concept.property.code) and also externally, in the following places:

Properties are defined using the following elements:

Name Details Description
code code Used to identify the property, in the places shown in the list immediately above this table
uri optional uri Reference to the formal meaning of the property. One possible source of meaning is the Concept Properties code system. This part of the definition is optional, but is recommended to provide an additional level of definitional consistency
description optional string A description of the property- why it is defined, and how its value might be used
type code | Coding | string | integer | boolean | dateTime The type of the property value. Properties of type "code" contain a code defined by the code system (e.g. a reference to another defined concept)

Note that properties provide a common view of concept relationships that is common across all code systems. Some code systems define properties with more sophistication, such as groups of properties, or subsumption relationships between properties (e.g. SNOMED CT). Servers providing support for these code systems will need to know full details about the underlying relationships in order to provide the correct information about concepts and their properties, but this information does not surface in the resources or operations defined by the FHIR specification.

Concept Status

Many Code Systems have a 'status' associated with the concept. This may categorize the concept as:

There is wide variation in the life cycles supported by the different code systems, the words they use to describe the various status values they use, and some code systems have additional status values. HL7 uses Active and Retired. In addition to these status codes, concepts may also be labeled as "Abstract' (not to be used in some circumstances), and have dates associated with their retirement or deprecation. All this information is represented as properties of the concepts. In order to assist with consistency between code systems, the following basic property URIs are defined:

http://hl7.org/fhir/concept-properties#status : codeA property that indicates the status of the concept. If the property is identified by this URL, then it SHALL use at least these status values (where appropriate):
  • active - the concept is for normal use
  • experimental - provided for trial, but may be removed in the future
  • deprecated - planned to be removed from use
  • retired - still present for historical reasons, but no longer allowed to be used
The HL7 defined code systems (whether defined by the FHIR project, the V3 framework, or the V2 standard) all use this property to define their status. HL7 uses "active" (and considers this the default status), and deprecated and retired (= inactive)
http://hl7.org/fhir/concept-properties#retirementDate : dateDate Concept was retired
http://hl7.org/fhir/concept-properties#deprecationDate : dateDate Concept was deprecated
http://hl7.org/fhir/concept-properties#parent : codeAn immediate parent of the concept in the hierarchy
http://hl7.org/fhir/concept-properties#child : codeAn immediate child of the concept in the hierarchy
http://hl7.org/fhir/concept-properties#notSelectable : booleanThis concept is a grouping concept and not intended to be used in the normal use of the code system (though may be used for filters etc.). This is also known as 'Abstract'

The parent and child properties are used when performing concept lookup (using the $lookup operation), and when using properties to indicate parent/child relationships (see below).

Concept Hierarchy

Code systems may be presented hierarchically, using nested concept elements, where the hierarchy has a defined meaning specified in hierarchyMeaning. The code system hierarchy is a single tree, where concepts have only one parent.

Some code systems define concepts that have multiple parents. If a code system has concepts like this (typically, concepts that are subsumed by more than one other concept), the code system SHOULD NOT be represented using the hierarchy structure in the Code System resource, and the relationships between resources should be defined using properties. If the hierarchy is used, implementers SHALL use a property to indicate additional parents that are not represented in the structural (nested concepts) hierarchy.

Operations based on the codeSystem resource SHALL have the same result whether or not the relationships are represented explicitly as properties or implicitly using the CodeSystem resource hierarchy.

Subsumption Testing

The words 'subsume', 'subsumes', 'subsumed' and 'subsumption' are defined in relation to the type of hierarchy (i.e. the value of CodeSystem.hierarchyMeaning) identified for the code system that is being represented by the CodeSystem resource. Concept A is considered to be subsumed by Concept B if it comes under Concept B in the hierarchy, or if a parent/child relationship is declared in the properties, and the hierarchyMeaning is "is-a").

Where a CodeSystem does not declare its hierarchy meaning directly, then the code system documentation must be consulted manually to determine how subsumption is determined. If there is no definition, none of the subsumption based features can be used with the code system.

Subsumption based logic arises explicitly or implicitly in the following places in the FHIR specification:

Filters

The following filters are defined for all code systems:

Property Name Operation Value Definition Notes
[property] = [string] Includes all codes that have a property value equal to the specified string, where [property] is the code for any defined property
[property] in [string,string...] Includes all codes that have a property value equal to one of the specified strings, where [property] is the code for any defined property The values cannot include ",", since it is being used as a delimiter

This draft section about the relationships between rich terminologies and structured content is still undergoing review.

Implicit Code Systems

Some other parts of the FHIR infrastructure define set of concepts that may also be treated as code systems. This is most useful when mapping between systems using Concept Maps, but might also be useful for other code system related functionality (e.g. subsetting use Value Sets). This table summarizes how to treat these items as a terminology:

StructureDefinition The StructureDefinition.url (canonical URL) is the system. Each .snapshot.element.id in the snapshot is a code in the code system
Questionnaire The Questionnaire.url (canonical URL) is the system. Each .item.linkId in the snapshot is a code in the code system. Items with no linkId cannot be addressed
Medication Medication resources are a bit different, since they don't have a canonical URL, and there are not multiple items in a resource. So to refer to a medication resource, the system is [base]/Medication, where base is the server address. The Logical Id of the resource is the code

The use of these implicit code systems is not yet well tested, so this section remains informative.

For medications, the relationship between the code system and the medication resource is complex. Many medication related code systems (e.g. RxNorm, DM+D, AMT, etc) represent more complex information than just code, display name and code system. These often contain information about the content of the medication A similar principle applies to observation definitions, which overlap significantly with LOINC and other related code systems, which contain a set of observation definitions, that contain methods, units, etc. Other similar arrangements exist for Location and many other kinds of resource.

In FHIR, these are handled by splitting the concept into two distinct parts - the Terminology, (Code System & ValueSet resources) is used to manage the codes, display names and relationships. A separate "detail" resource (e.g., Medication resource instances for RxNorm code details, ObservationDefinition instances for LOINC code details, or Location, etc.) is used to convey detailed information (dose form & strength, allowed data type or permitted values, address & hours of operation, etc.). One "detail" resource instance is created for each code.

This division accomplishes several things:

Note that this division in FHIR does not imply that a similar division is required in the internal representation used by systems exposing a FHIR interface. Similarly, some systems may choose to only expose or maintain one aspect of such information types (i.e. only the discrete resource instances or only the value set).

The linkage between the "detail" resource and the Terminology resources is accomplished via the code element (or equivalent) on the detail resource. As well, the "name" or "title" on the detail resource generally corresponds with the display name on the matching code. Most detail resources will also have an "identifier" element. This can be set to the same value and namespace as the code, but if the only identifier a resource has is its defining code, it may be better to omit the identifier entirely. .

Search Parameters

codeA code defined in the code systemCodeSystem.concept.code
content-modenot-present | example | fragment | complete | supplementCodeSystem.content
identifierMultiple Resources: * [CodeSystem](codesystem.html): External identifier for the code system * [ConceptMap](conceptmap.html): External identifier for the concept map * [MessageDefinition](messagedefinition.html): External identifier for the message definition * [StructureDefinition](structuredefinition.html): External identifier for the structure definition * [StructureMap](structuremap.html): External identifier for the structure map * [ValueSet](valueset.html): External identifier for the value set CodeSystem.identifier | ConceptMap.identifier | MessageDefinition.identifier | StructureDefinition.identifier | StructureMap.identifier | ValueSet.identifier
languageA language in which a designation is providedCodeSystem.concept.designation.language
supplementsFind code system supplements for the referenced code systemCodeSystem.supplements
systemThe system for any codes defined by this code system (same as 'url')CodeSystem.url

Extension Definitions

These are extension definitions for this resource defined by the spec

Profiles based on this resource

Shareable CodeSystem

Enforces the minimum information set for the value set metadata required by HL7 and other organizations that share and publish value sets

Elements

PathShortDefinitionComments
Declares the existence of and describes a code system or code system supplementThe CodeSystem resource is used to declare the existence of and describe a code system or code system supplement and its key properties, and optionally define a part or all of its content.
urlCanonical identifier for this code system, represented as a URI (globally unique) (Coding.system)An absolute URI that is used to identify this code system when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which at which an authoritative instance of this code system is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the code system is stored on different servers. This is used in [Coding](datatypes.html#Coding).system.Can be a urn:uuid: or a urn:oid: but real http: addresses are preferred. Multiple instances may share the same URL if they have a distinct version. The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in [Technical and Business Versions](resource.html#versions). In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the [meta.source](resource.html#meta) element to indicate where the current master source of the resource can be found.
identifierAdditional identifier for the code system (business identifier)A formal identifier that is used to identify this code system when it is represented in other formats, or referenced in a specification, model, design or an instance.Typically, this is used for identifiers that can go in an HL7 V3 II (instance identifier) data type, and can then identify this code system outside of FHIR, where it is not possible to use the logical URI. Note that HL7 defines at least three identifiers for many of its code systems - the FHIR canonical URL, the OID and the V2 Table 0396 mnemonic code.
versionBusiness version of the code system (Coding.version)The identifier that is used to identify this version of the code system when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the code system author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence. This is used in [Coding](datatypes.html#Coding).version.There may be different code system instances that have the same identifier but different versions. The version can be appended to the url in a reference to allow a reference to a particular business version of the code system with the format [url]|[version].
nameName for this code system (computer friendly)A natural language name identifying the code system. This name should be usable as an identifier for the module by machine processing applications such as code generation.The name is not expected to be globally unique. The name should be a simple alphanumeric type name to ensure that it is machine-processing friendly.
titleName for this code system (human friendly)A short, descriptive, user-friendly title for the code system.This name does not need to be machine-processing friendly and may contain punctuation, white-space, etc.
statusdraft | active | retired | unknownThe date (and optionally time) when the code system resource was created or revised.Allows filtering of code systems that are appropriate for use versus not.
experimentalFor testing purposes, not real usageA Boolean value to indicate that this code system is authored for testing purposes (or education/evaluation/marketing) and is not intended to be used for genuine usage.Allows filtering of code systems that are appropriate for use versus not.
dateDate last changedThe date (and optionally time) when the code system was published. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the code system changes.Note that this is not the same as the resource last-modified-date, since the resource may be a secondary representation of the code system. Additional specific dates may be added as extensions or be found by consulting Provenances associated with past versions of the resource.
publisherName of the publisher (organization or individual)The name of the organization or individual that published the code system.Usually an organization but may be an individual. The publisher (or steward) of the code system is the organization or individual primarily responsible for the maintenance and upkeep of the code system. This is not necessarily the same individual or organization that developed and initially authored the content. The publisher is the primary point of contact for questions or issues with the code system. This item SHOULD be populated unless the information is available from context.
contactContact details for the publisherContact details to assist a user in finding and communicating with the publisher.May be a web site, an email address, a telephone number, etc.
descriptionNatural language description of the code systemA free text natural language description of the code system from a consumer's perspective.This description can be used to capture details such as why the code system was built, comments about misuse, instructions for clinical use and interpretation, literature references, examples from the paper world, etc. It is not a rendering of the code system as conveyed in the 'text' field of the resource itself. This item SHOULD be populated unless the information is available from context (e.g. the language of the code system is presumed to be the predominant language in the place the code system was created).
useContextThe context that the content is intended to supportThe content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate code system instances.When multiple useContexts are specified, there is no expectation that all or any of the contexts apply.
jurisdictionIntended jurisdiction for code system (if applicable)A legal or geographic region in which the code system is intended to be used.It may be possible for the code system to be used in jurisdictions other than those for which it was originally designed or intended.
purposeWhy this code system is definedExplanation of why this code system is needed and why it has been designed as it has.This element does not describe the usage of the code system. Instead, it provides traceability of ''why'' the resource is either needed or ''why'' it is defined as it is. This may be used to point to source materials or specifications that drove the structure of this code system.
copyrightUse and/or publishing restrictionsA copyright statement relating to the code system and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the code system.... Sometimes, the copyright differs between the code system and the codes that are included. The copyright statement should clearly differentiate between these when required.
caseSensitiveIf code comparison is case sensitiveIf code comparison is case sensitive when codes within this system are compared to each other.If this value is missing, then it is not specified whether a code system is case sensitive or not. When the rule is not known, Postel's law should be followed: produce codes with the correct case, and accept codes in any case. This element is primarily provided to support validation software.
valueSetCanonical reference to the value set with entire code systemCanonical reference to the value set that contains the entire code system.The definition of the value set SHALL include all codes from this code system and only codes from this code system, and it SHALL be immutable.
hierarchyMeaninggrouped-by | is-a | part-of | classified-withThe meaning of the hierarchy of concepts as represnted in this resource.Note that other representations might have a different hierarchy or none at all, and represent the information using properties.
compositionalIf code system defines a compositional grammarThe code system defines a compositional (post-coordination) grammar.Note that the code system resource does not define what the compositional grammar is, only whether or not there is one.
versionNeededIf definitions are not stableThis flag is used to signify that the code system does not commit to concept permanence across versions. If true, a version must be specified when referencing this code system.Best practice is that code systems do not redefine concepts, or that if concepts are redefined, a new code system definition is created. But this is not always possible, so some code systems may be defined as 'versionNeeded'. Most code systems occasionally refine the displays defined for concepts between versions. Contexts in which the concept display values are validated may require that the version be specified for some code systems irrespective of the value of this property.
contentnot-present | example | fragment | complete | supplementThe extent of the content of the code system (the concepts and codes it defines) are represented in this resource instance.
supplementsCanonical URL of Code System this adds designations and properties toThe canonical URL of the code system that this code system supplement is adding designations and properties to.The most common use of a code system supplement is to add additional language support.
countTotal concepts in the code systemThe total number of concepts defined by the code system. Where the code system has a compositional grammar, the basis of this count is defined by the system steward.The count of concepts defined in this resource cannot be more than this value but may be less for several reasons - see the content element.
filterFilter that can be used in a value setA filter that can be used in a value set compose statement when selecting concepts using a filter.Note that filters defined in code systems usually require custom code on the part of any terminology engine that will make them available for use in value set filters. For this reason, they are generally only seen in high value published terminologies.
filter.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
filter.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
filter.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
filter.codeCode that identifies the filterThe code that identifies this filter when it is used as a filter in [ValueSet](valueset.html#).compose.include.filter.
filter.descriptionHow or why the filter is usedA description of how or why the filter is used.
filter.operatorOperators that can be used with filterA list of operators that can be used with the filter.
filter.valueWhat to use for the valueA description of what the value for the filter should be.
propertyAdditional information supplied about each conceptA property defines an additional slot through which additional information can be provided about a concept.
property.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
property.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
property.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
property.codeIdentifies the property on the concepts, and when referred to in operationsA code that is used to identify the property. The code is used internally (in CodeSystem.concept.property.code) and also externally, such as in property filters.
property.uriFormal identifier for the propertyReference to the formal meaning of the property. One possible source of meaning is the [Concept Properties](codesystem-concept-properties.html) code system.
property.descriptionWhy the property is defined, and/or what it conveysA description of the property- why it is defined, and how its value might be used.
property.typecode | Coding | string | integer | boolean | dateTime | decimalThe type of the property value. Properties of type "code" contain a code defined by the code system (e.g. a reference to another defined concept).
conceptConcepts in the code systemConcepts that are in the code system. The concept definitions are inherently hierarchical, but the definitions must be consulted to determine what the meaning of the hierarchical relationships are.If this is empty, it means that the code system resource does not represent the content of the code system.
concept.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
concept.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.codeCode that identifies conceptA code - a text symbol - that uniquely identifies the concept within the code system.
concept.displayText to display to the userA human readable string that is the recommended default way to present this concept to a user.
concept.definitionFormal definitionThe formal definition of the concept. The code system resource does not make formal definitions required, because of the prevalence of legacy systems. However, they are highly recommended, as without them there is no formal meaning associated with the concept.
concept.designationAdditional representations for the conceptAdditional representations for the concept - other languages, aliases, specialized purposes, used for particular purposes, etc.Concepts have both a ```display``` and an array of ```designation```. The display is equivalent to a special designation with an implied ```designation.use``` of "primary code" and a language equal to the [Resource Language](resource.html#language).
concept.designation.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
concept.designation.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.designation.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.designation.languageHuman language of the designationThe language this designation is defined for.In the absence of a language, the resource language applies.
concept.designation.useDetails how this designation would be usedA code that details how this designation would be used.If no use is provided, the designation can be assumed to be suitable for general display to a human user.
concept.designation.valueThe text value for this designationThe text value for this designation.
concept.propertyProperty value for the conceptA property value for this concept.
concept.property.idUnique id for inter-element referencingUnique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
concept.property.extensionAdditional content defined by implementationsMay be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.property.modifierExtensionExtensions that cannot be ignored even if unrecognizedMay be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.
concept.property.codeReference to CodeSystem.property.codeA code that is a reference to CodeSystem.property.code.
concept.property.value[x]Value of the property for this conceptThe value of this property.
concept.conceptChild Concepts (is-a/contains/categorizes)Defines children of a concept to produce a hierarchy of concepts. The nature of the relationships is variable (is-a/contains/categorizes) - see hierarchyMeaning.