--- type: "codesystem" title: "CodeSystem: notes" codesystem: "notes" --- # CodeSystem: notes ## Narrative ## 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](http://snomed.org) 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 which can be specified in `CodeSystem.version`. The version 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, though HL7 recommends a date-based approach, or [sem-ver](https://semver.org). When the `CodeSystem.versionNeeded` is 'true', then the CodeSystem.version value SHALL be used in [Coding](datatypes#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: - Different IP distribution rules for different parts of the code system - Special purpose modules for specific purposes - Distribution of proposed content for evaluation The following rules apply to code system fragments: - All fragments SHALL have the same CodeSystem.url - Fragments can only be published by the code system authority, or according to a process defined by the authority, if they have defined one - Fragments cannot contain any codes, concepts or properties that would not be found in a complete representation of the code system, if one exists. Implementers should note that a "complete representation" of the code system might not exist in a single authoritative publication (e.g., SNOMED International with all modules/extensions) - Publishing a code system in multiple fragments can create confusion for terminology servers and terminology service consumers. - The intent, bounds and consequences of the fragmentation are clearly defined in the fragment or the code system documentation. ## 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: - The `CodeSystem.supplements` element SHALL have a value, which is the URL of the code system being supplemented - The `CodeSystem.url` for a supplement SHALL never appear in a [Coding.system](datatypes#Coding) - The `CodeSystem.url` for a supplement must be under the control of the authority creating or publishing the supplement (e.g. not in the same space as the code system being supplemented, unless the supplement is being issued by the same authority as the original code system - A codesystem supplement cannot define any new CodeSystem.concept.code. i.e.: all CodeSystem.concept.code in the supplement must be a code from the "supplemented" code system. Some code systems reserve code space for local use without explicitly declaring codes; these codes may be referenced in a supplement 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. ## 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](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 provides a reason to use one of the designations. ## Concept 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: - Tracking administrative status (inactive, deprecation date) - Providing additional statements about the meaning of the concept - Defining structured relationships with other concepts in the code system - Assigning scoring values to the concepts 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: - [ConceptMap](conceptmap-definitions#ConceptMap.group.element.target.dependsOn.property): `ConceptMap.element.target.dependsOn.property` and `ConceptMap.element.target.product.property` - [ValueSet](valueset-definitions#ValueSet.compose.include.filter.property): `ValueSet.compose.include.filter.property` can refer to any defined code system property - [$lookup operation](codesystem-operations#lookup): In `Parameters.parameter.name` when returning information about a code - [$translate operation](conceptmap-operations#translate): In `Parameters.parameter.part.name` for dependencies and products Properties are defined using the following elements: | **Name** | **Details** | **Description** | | --- | --- | --- | | code | [code](datatypes#code) | Used to identify the property, in the places shown in the list immediately above this table | | uri | optional [uri](datatypes#code) | Reference to the formal meaning of the property. One possible source of meaning is the [Concept Properties](codesystem-concept-properties) code system. This part of the definition is optional, but is recommended to provide an additional level of definitional consistency. See further comments below | | description | optional [string](datatypes#code) | A description of the property- why it is defined, and how its value might be used | | type | code | Coding | string | integer | boolean | dateTime | decimal | The type of the property value. The values for properties of type "code" (CodeSystem.concept.property.valueCode) are drawn from the codes defined in the CodeSystem instance. | Properties do not have to have a `uri` the formally defines them, but they SHOULD have a `uri`, and this is particularly important when using properties across multiple code systems. The following guidelines apply: - By convention, property URIs SHOULD have the form {canonical}#{code} where {canonical} is the CodeSystem URI, and {code} is the code for the property - The convention {canonical}#{code} is also used in some contexts to refer directly to a concept defined by the CodeSystem, so if there is a concept defined with the same code as the property, it is treated as a 'backing' concept, to allow reasoning and use in value sets - Properties are explicitly defined, not implied by the existence of a concept with the same code, and the definitions and properties of the concept to not contribute to the definition of the property - CodeSystems MAY (and should!) use properties defined in other code system. The [Concept Properties](codesystem-concept-properties) Code System exists for this purpose, and the properties defined there SHOULD always be used where applicable - When using a property defined in another code system, a code system SHOULD provide a full definition - `code`, `uri`, `description`, `type`, and [valueSet](https://hl7.org/fhir/extensions/StructureDefinition-codesystem-property-valueset.html) where applicable - In such cases, the definition of the property must be consistent with the source CodeSystem. CodeSystems MAY contain additional descriptive text around the use of the property, and MAY narrow the applicable value set if there is one - If any of these features are not redeclared, applications SHOULD assume that the source CodeSystem definitions apply 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. ## Defined Concept Properties In order to assist with consistency between code systems, the following basic property URIs are defined in the [Concept Properties](codesystem-concept-properties) code system: Note: all the properties in the table below are prefixed by `http://hl7.org/fhir/concept-properties#` such that the url that identifies the `status` property is actually `http://hl7.org/fhir/concept-properties#status`. The prefix is omitted from the table to improve it's presentation. table.fixedfirst td:first-child { white-space: nowrap; } | URL Tail | Type | Description | | --- | --- | --- | | ...status![btn](icon_clipboard.png) | code | A 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 - the concept is outdated and planned to be withdrawn from use - retired - still present for historical reasons, but no longer allowed to be used | | ...inactive![btn](icon_clipboard.png) | boolean | True if the concept is not considered active - e.g. not a valid concept any more. Property type is boolean, default value is false | | ...effectiveDate![btn](icon_clipboard.png) | date | The date at which the concept status was last changed | | ...deprecationDate![btn](icon_clipboard.png) | date | Date Concept was deprecated | | ...retirementDate![btn](icon_clipboard.png) | date | Date Concept was retired | | ...notSelectable![btn](icon_clipboard.png) | boolean | This 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' | | ...parent![btn](icon_clipboard.png) | code | An immediate parent of the concept in the hierarchy | | ...child![btn](icon_clipboard.png) | code | An immediate child of the concept in the hierarchy | | ...partOf![btn](icon_clipboard.png) | code | The concept identified in this property (by its code) contains this concept as a component | | ...synonym![btn](icon_clipboard.png) | code | This property contains an alternative code that may be used to identify this concept instead of the primary code (deprecated: use `alternateCode`, and see the [discussion below](#synonyms)) | | ...alternateCode![btn](icon_clipboard.png) | code | This property contains the code for another representation of this concept, with the same real-world meaning, in this code system | | ...comment![btn](icon_clipboard.png) | string | A string that provides additional detail pertinent to the use or understanding of the concept | | ...itemWeight![btn](icon_clipboard.png) | decimal | A numeric value that allows the comparison (less than, greater than) or other numerical manipulation of a concept (e.g. Adding up components of a score). Scores are usually a whole number, but occasionally decimals are encountered in scores | | ...order![btn](icon_clipboard.png) | decimal | A property that indicates the order of the concept amongst its siblings in the code system e.g. severity. The code system specific purpose of the ordering is defined elsewhere | | ...definition![btn](icon_clipboard.png) | string | The definition of the concept. This corresponds to CodeSystem.concept.definition and is not used in the definition of CodeSystems but is used when clients request the definition property be included in an expansion | | ...lastVersionActive![btn](icon_clipboard.png) | string | If the code is not active (properties inActive or based on status), then this property conveys in what code system version it was last an active code | | ...replacedBy\[X\] | string | These two properties identify a concept that is considered to replace the use of this concept. These properties are generally only used on deprecated, withdrawn or inactive concepts. Variant #1: ...replacedByCode![btn](icon_clipboard.png): Identifies another concept in the same code system Variant #2: ...replacedByCoding![btn](icon_clipboard.png): Identifies another concept in a different code system Use cases: - replacing a with a new code/concept that corrects an error in a now retired concept - replacement of a temporary local code by something that's been added to LOINC or SNOMED CT and should be used instead | Code System representations SHOULD use these properties where possible and these codes for these properties. Code System representations SHOULD regard the codes for these properties (e.g. status, inactive, notSelectable, etc.) as reserved values in CodeSystem.property.code values and that when used they SHOULD refer to the properties defined in the concept properties code system. In the absence of CodeSystem.property data elements being provided, when properties with these code values are added to a concept (in CodeSystem.concept.property.code) the intended property SHOULD be assumed to refer to the defined concept properties in the [http://hl7.org/fhir/concept-properties](codesystem-concept-properties) code system. The parent and child properties are used when performing concept lookup (using the [$lookup](codesystem-operations#lookup) operation), and when using properties to indicate parent/child relationships (see below). ### Concept Status Many Code Systems have a 'status' associated with the concept. This may categorize the concept as: - Experimental - provided for trial, but may be removed in the future - Active - in normal use - Deprecated - planned to be removed from use - Retired - still present for historical reasons, but no longer allowed to be used There is wide variation in the life cycles supported by the different code systems and the words they use to describe the various status values they use, and some code systems have additional status values. HL7 uses Active, Deprecated and Retired. These ideas overlap with setting the concept to 'inactive'. In addition, concepts have dates associated with their retirement or deprecation and some code systems imply the status by providing dates. In addition to these status codes, concepts may also be labeled 'notSelectable' (aka 'Abstract'), which means "not to be used in some circumstances", though the exact circumstances need to be clarified somewhere. This is sometimes also considered a status, though it's usually dependent on the context of use (e.g. set in a ValueSet). The status value overlaps with other properties, in particular, the inactive property. In general, the following rules apply: - If concept status is some kind of active, inactive must be set to false if present, and the concept is treated as not inactive. - If concept status is some kind of inactive, inactive must be set to true if present, and the concept is treated as inactive. - If concept status is some kind of retired, inactive must be set to true if present, and the concept is treated as inactive. - If concept status indicates that the concept is experimental or deprecated, the determination of inactive is code system specific - If neither concept properties are present default behavior for the CodeSystem applies. The status also relates to properties such as deprecation and retirement date. The status of the concept SHOULD always be consistent with these other properties. ### Synonyms and Alternate Codes Many code systems define multiple codes for the same real world concept. Some code systems do this as a matter of policy (e.g. case-sensitive vs case insensitive) while others arise over time as the editorial process unfolds. Some established code systems treat these as synonym codes for the same concept, while others treat them as synonym concepts - duplicated concepts with the same real world meaning, though the definition sometimes differ. Another reason for duplicated concepts is to deal with implied poly-heirarchical concepts in systems that do not support formal poly-heirarchies. Whatever the reason, in FHIR code systems, all kinds of synonyms are represented the same way: as duplicate concepts with a declared relationship between them. The relationship is declared using the 'alternateCode' property, which identities another concept with the same real-world meaning that the code system defines. In most cases (but not necessarily all), the concepts related with the alternateCode property will have the same: - property values (with the exception of alternateCode, and administrative properties) - designations The alternateCode property allows CodeSystem resource instances to represent multiple codes for a concept defined in a code system. The correct way to use the alternateCode property for an instance of CodeSystem.concept (A): - the alternateCode value must be the code associated with a different CodeSystem.concept (B) in the same CodeSystem; and - B SHALL contain an instance of the alternateCode property with the value of the code for A. I.e. reflexivity is required (see csd-6 above) - All relationships shall be explicit - relationships (including transitivity and parent/child) must not be assumed. > **Note to Balloters:** This section is newly introduced in R6 after extensive consideration in committee, and comments are sought. ## Concept Hierarchy Code systems may be presented hierarchically using either nested concept elements or properties. When exclusively using nested concept elements the code system hierarchy is a single tree, and concepts have only one parent. When using properties, polyhierarchies are allowed (e.g. concepts may have more than one parent). If a code system hierarchy is represented using properties (typically, concepts that are subsumed by more than one other concept), nested concepts SHOULD NOT be used to represent any parts of the hierarchy structure in the Code System resource; the relationships between concepts should be defined using [properties](#properties). 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](codesystem-definitions#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: - [CodeSystem $subsumes operation](codesystem-operations#subsumes) - [CodeSystem $lookup operation](codesystem-operations#lookup) - [Search by subsumption](search#subsumption) - [ValueSet $expand operation](valueset-operations#expand) - [ValueSet $validate-code operation](valueset-operations#validate-code) ## Filters The following filters are defined for all code systems: | Property Name | Operation | Value | Definition | Notes | | --- | --- | --- | --- | --- | | code | regex | \[string\] | Matches any concept with the code matching the supplied string | The regex flavor is determined by the server | | \[property\] | \= | \[string\] | Includes all codes that have a property value equal to the specified string, where \[property\] is the code for any [defined property](#properties). Where the type of the property is on of `integer`, `dateTime` or `decimal`, the FHIR search prefixes and semantics apply (see below) | | | \[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](#properties) | The values cannot include ",", since it is being used as a delimiter | | \[property\] | regex | \[string\] | Includes all codes that have a property value matching the specified regex | | | \[property\] | exists | true or false | When value is "true", includes all codes that have the specified property. When value is "false", includes all codes that lack the specified property | | | designation | \= | \[string\] | Matches any concept with a designation equal to the supplied string | Designations considered include the concept.display, which counts as a designation | | designation | regex | \[string\] | Matches any concept with a designation matching the supplied string | Designations considered include the concept.display, which counts as a designation | The following filters are defined for all code systems that support "is-a" relationships between concepts. (The filters can be used regardless of whether the "is-a" relationships are conveyed as concept properties or as concept nesting): | Property Name | Operation | Value | Definition | Notes | | --- | --- | --- | --- | --- | | concept | is-a | \[string\] concept code | Includes all concept ids that have a transitive is-a relationship with the concept Id provided as the value, including the provided concept itself (include descendant codes and self). | | | concept | descendent-of | \[string\] concept code | Includes all concept ids that have a transitive is-a relationship with the concept Id provided as the value, excluding the provided concept itself (i.e. include descendant codes only). | | | concept | in | not-in | \[string\] a comma separated list of codes, or a value set uri | Concepts in the list, or concepts in the value set expansion. | | | concept | is-not-a | \[string\] concept code | The specified property of the code does not have an is-a relationship with the provided value. | | | concept | generalizes | \[string\] concept code | Includes all concept ids that have a transitive is-a relationship from the concept Id provided as the value, including the provided concept itself (i.e. include ancestor codes and self). | | | concept | child-of | \[string\] concept code | Only concepts with a direct hierarchical relationship to the index code and no other concepts. This does not include the index code in the output. | | | concept | descendent-leaf | \[string\] concept code | Includes concept ids that have a transitive is-a relationship with the concept Id provided as the value, but which do not have any concept ids with transitive is-a relationships with themselves. | | ### FHIR Search Semantics If the `=` filter is used with a property that is defined on the CodeSystem, and if the property has a type of `integer`, `dateTime` or `decimal`, then the FHIR search rules apply. This means that the following prefixes may be used in the value of the filter: - **eq**: the code has a value for the property on the code and it is equal to the provided value - **ne**: the code has a value for the property on the code and it is not equal to the provided value - **gt**: the code has a value for the property on the code and it is greater than the provided value - **lt**: the code has a value for the property on the code and it is less than the provided value - **ge**: the code has a value for the property on the code and it is greater or equal to the provided value - **le**: the code has a value for the property on the code and it is less or equal to the provided value - **sa**: the code has a value for the property on the code and it is starts after the provided value - **eb**: the code has a value for the property on the code and it is ends before the provided value - **ap**: the code has a value for the property on the code and it is approximately the same to the provided value The semantics of prefixes are as explained on the search page with regard to precision and range considerations, particularly on dates and decimals. Note that `eq` is not redundant - in it's absence, the semantics are for a direct string match, not a smart match as defined by the search semantics. Some Examples: { "property": "retiredDate", "operator": "=", "value": "lt2021-01-01" } Any code that was retired before 2021. Regarding precision: { "property": "retiredDate", "operator": "=", "value": "eq2022" } would match a concept with a retiredDate of 2022-09-12. However: { "property": "retiredDate", "operator": "=", "value": "2022" } would not match a concept with a retiredDate of 2022-09-12. ## 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](conceptmap "[%resdesc ConceptMap%]"), but might also be useful for other code system related functionality (e.g. subsetting using [Value Sets](valueset "[%resdesc ValueSet%]")). The table below summarizes how to treat these items as a code system: | **[StructureDefinition](structuredefinition "[%resdesc StructureDefinition%]")** | **URL** (CodeSystem.url) | `[StructureDefinition.url](structuredefinition-definitions#StructureDefinition.url)` | | --- | --- | --- | | **Concept** (CodeSystem.concept) | Each `[StructureDefinition.snapshot.element](structuredefinition-definitions#StructureDefinition.snapshot.element)` element corresponds to a code system concept. | | **Code** (CodeSystem.concept.code) | `[StructureDefinition.snapshot.element.id](types-definitions#Element.id)` | | **Display** (CodeSystem.concept.display) | `[StructureDefinition.snapshot.element.label](elementdefinition-definitions#ElementDefinition.label)` if one exists, otherwise `[StructureDefinition.snapshot.element.short](elementdefinition-definitions#ElementDefinition.short)` | | **Definition** (CodeSystem.concept.definition) | `[StructureDefinition.snapshot.element.definition](elementdefinition-definitions#ElementDefinition.definition)` | | **[Questionnaire](questionnaire "[%resdesc Questionnaire%]")** | **URL** (CodeSystem.url) | `[Questionnaire.url](questionnaire-definitions#Questionnaire.url)` | | **Concept** (CodeSystem.concept) | Each `[Questionnaire.item](questionnaire-definitions#Questionnaire.item)` element corresponds to a code system concept. | | **Code** (CodeSystem.concept.code) | `[Questionnaire.item.linkId](questionnaire-definitions#Questionnaire.item.linkId)`. Note: `Questionnaire.item` elements without a linkId cannot be addressed. | | **Display** (CodeSystem.concept.display) | `[Questionnaire.item.text](questionnaire-definitions#Questionnaire.item.text)` | | **Definition** (CodeSystem.concept.definition) | Questionnaire-based implicit code system concepts do not have a definition. | | **[Requirements](requirements "[%resdesc Requirements%]")** | **URL** (CodeSystem.url) | `[Requirements.url](requirements-definitions#Requirements.url)` | | **Concept** (CodeSystem.concept) | Each `[Requirements.statement](requirements-definitions#Requirements.statement)` element corresponds to a code system concept. | | **Code** (CodeSystem.concept.code) | `[Requirements.statement.key](requirements-definitions#Requirements.statement.key)` | | **Display** (CodeSystem.concept.display) | `[Requirements.statement.label](requirements-definitions#Requirements.statement.label)` if one exists, otherwise `[Requirements.statement.key](requirements-definitions#Requirements.statement.key)`. | | **Definition** (CodeSystem.concept.definition) | `[Requirements.statement.requirement](requirements-definitions#Requirements.statement.requirement)` | | **[Measure](measure "[%resdesc Measure%]")** | **URL** (CodeSystem.url) | `[Measure.url](measure-definitions#Measure.url)` | | **Concept** (CodeSystem.concept) | Each Measure element with a `linkId` element corresponds to a code system concept. Specifically, - `[Measure.group](measure-definitions#Measure.group)` - `[Measure.group.population](measure-definitions#Measure.group.population)` - `[Measure.group.stratifier](measure-definitions#Measure.group.stratifier)` - `[Measure.group.stratifier.component](measure-definitions#Measure.group.stratifier.component)` - `[Measure.supplementalData](measure-definitions#Measure.supplementalData)` | | **Code** (CodeSystem.concept.code) | - `[Measure.group.linkId](measure-definitions#Measure.group.linkId)` for Measure.group concepts. - `[Measure.group.population.linkId](measure-definitions#Measure.group.population.linkId)` for Measure.group.population concepts. - `[Measure.group.stratifier.linkId](measure-definitions#Measure.group.stratifier.linkId)` for Measure.group.stratifier concepts. - `[Measure.group.stratifier.component.linkId](measure-definitions#Measure.group.stratifier.component.linkId)` for Measure.group.stratifier.component concepts. - `[Measure.supplementalData.linkId](measure-definitions#Measure.supplementalData.linkId)` for Measure.supplementalData concepts. | | **Display** (CodeSystem.concept.display) | - `[Measure.group.title](measure-definitions#Measure.group.title)` for Measure.group concepts. - `[Measure.group.population.title](measure-definitions#Measure.group.population.title)` for Measure.group.population concepts. - `[Measure.group.stratifier.title](measure-definitions#Measure.group.stratifier.title)` for Measure.group.stratifier concepts. - `[Measure.group.stratifier.component.code](measure-definitions#Measure.group.stratifier.component.code)` for Measure.group.stratifier.component concepts. - `[Measure.supplementalData.description](measure-definitions#Measure.supplementalData.description)` for Measure.supplementalData concepts. | | **Definition** (CodeSystem.concept.definition) | - `[Measure.group.description](measure-definitions#Measure.group.description)` for Measure.group concepts. - `[Measure.group.population.description](measure-definitions#Measure.group.population.description)` for Measure.group.population concepts. - `[Measure.group.stratifier.description](measure-definitions#Measure.group.stratifier.description)` for Measure.group.stratifier concepts. - `[Measure.group.stratifier.component.description](measure-definitions#Measure.group.stratifier.component.description)` for Measure.group.stratifier.component concepts. - `[Measure.supplementalData.description](measure-definitions#Measure.supplementalData.description)` for Measure.supplementalData concepts. | The above resource instances continue to use their `url` value as they normally would. However, whenever that URL appears as a value in the following fixed number of elements or parameters it SHALL be interpreted to be the implicit code system: - `[Coding.system](datatypes-definitions#Coding.system)` - `[ValueSet.compose.include.system](valueset-definitions#ValueSet.compose.include.system)` - `[ValueSet.compose.exclude.system](valueset-definitions#ValueSet.compose.exclude)` - `[ConceptMap.group.source](conceptmap-definitions#ConceptMap.group.source)` - `[ConceptMap.group.target](conceptmap-definitions#ConceptMap.group.target)` - `[TerminologyCapabilities.codeSystem.uri](terminologycapabilities-definitions#TerminologyCapabilities.codeSystem.uri)` - `exclude-system`, `system-version`, `check-system-version`, and `force-system-version` input parameters to `[$expand on ValueSet](valueset-operation-expand)` operation. - `system-version`, `check-system-version` and `force-system-version` input parameters to `[$validate-code on ValueSet](valueset-operation-validate-code)` operation. - `url` input parameter to `[$validate-code on CodeSystem](codesystem-operation-validate-code)` operation. > **Note to Balloters:** > > - The list may be expanded in future, but these are cases already in use by the implementer community. > - Code system properties are not defined at this time, but ballot feedback on this is welcome. ## CodeSystem XML ```xml

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 which can be specified in CodeSystem.version. The version 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, though HL7 recommends a date-based approach, or sem-ver.

When the CodeSystem.versionNeeded is 'true', then the CodeSystem.version value 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.

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 provides a reason to use one of the designations.

Concept 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. See further comments below
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 | decimal The type of the property value. The values for properties of type "code" (CodeSystem.concept.property.valueCode) are drawn from the codes defined in the CodeSystem instance.

Properties do not have to have a uri the formally defines them, but they SHOULD have a uri, and this is particularly important when using properties across multiple code systems. The following guidelines apply:

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.

Defined Concept Properties

In order to assist with consistency between code systems, the following basic property URIs are defined in the Concept Properties code system:

Note: all the properties in the table below are prefixed by http://hl7.org/fhir/concept-properties# such that the url that identifies the status property is actually http://hl7.org/fhir/concept-properties#status. The prefix is omitted from the table to improve it's presentation.

URL Tail Type Description
...statusbtn code A 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 - the concept is outdated and planned to be withdrawn from use
  • retired - still present for historical reasons, but no longer allowed to be used
...inactivebtn boolean True if the concept is not considered active - e.g. not a valid concept any more. Property type is boolean, default value is false
...effectiveDatebtn date The date at which the concept status was last changed
...deprecationDatebtn date Date Concept was deprecated
...retirementDatebtn date Date Concept was retired
...notSelectablebtn boolean This 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'
...parentbtn code An immediate parent of the concept in the hierarchy
...childbtn code An immediate child of the concept in the hierarchy
...partOfbtn code The concept identified in this property (by its code) contains this concept as a component
...synonymbtn code This property contains an alternative code that may be used to identify this concept instead of the primary code (deprecated: use alternateCode, and see the discussion below)
...alternateCodebtn code This property contains the code for another representation of this concept, with the same real-world meaning, in this code system
...commentbtn string A string that provides additional detail pertinent to the use or understanding of the concept
...itemWeightbtn decimal A numeric value that allows the comparison (less than, greater than) or other numerical manipulation of a concept (e.g. Adding up components of a score). Scores are usually a whole number, but occasionally decimals are encountered in scores
...orderbtn decimal A property that indicates the order of the concept amongst its siblings in the code system e.g. severity. The code system specific purpose of the ordering is defined elsewhere
...definitionbtn string The definition of the concept. This corresponds to CodeSystem.concept.definition and is not used in the definition of CodeSystems but is used when clients request the definition property be included in an expansion
...lastVersionActivebtn string If the code is not active (properties inActive or based on status), then this property conveys in what code system version it was last an active code
...replacedBy[X] string These two properties identify a concept that is considered to replace the use of this concept. These properties are generally only used on deprecated, withdrawn or inactive concepts.
Variant #1: ...replacedByCodebtn: Identifies another concept in the same code system
Variant #2: ...replacedByCodingbtn: Identifies another concept in a different code system

Use cases:
  • replacing a with a new code/concept that corrects an error in a now retired concept
  • replacement of a temporary local code by something that's been added to LOINC or SNOMED CT and should be used instead

Code System representations SHOULD use these properties where possible and these codes for these properties. Code System representations SHOULD regard the codes for these properties (e.g. status, inactive, notSelectable, etc.) as reserved values in CodeSystem.property.code values and that when used they SHOULD refer to the properties defined in the concept properties code system.

In the absence of CodeSystem.property data elements being provided, when properties with these code values are added to a concept (in CodeSystem.concept.property.code) the intended property SHOULD be assumed to refer to the defined concept properties in the http://hl7.org/fhir/concept-properties code system.

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 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 and the words they use to describe the various status values they use, and some code systems have additional status values. HL7 uses Active, Deprecated and Retired. These ideas overlap with setting the concept to 'inactive'. In addition, concepts have dates associated with their retirement or deprecation and some code systems imply the status by providing dates.

In addition to these status codes, concepts may also be labeled 'notSelectable' (aka 'Abstract'), which means "not to be used in some circumstances", though the exact circumstances need to be clarified somewhere. This is sometimes also considered a status, though it's usually dependent on the context of use (e.g. set in a ValueSet).

The status value overlaps with other properties, in particular, the inactive property. In general, the following rules apply:

The status also relates to properties such as deprecation and retirement date. The status of the concept SHOULD always be consistent with these other properties.

Synonyms and Alternate Codes

Many code systems define multiple codes for the same real world concept. Some code systems do this as a matter of policy (e.g. case-sensitive vs case insensitive) while others arise over time as the editorial process unfolds. Some established code systems treat these as synonym codes for the same concept, while others treat them as synonym concepts - duplicated concepts with the same real world meaning, though the definition sometimes differ. Another reason for duplicated concepts is to deal with implied poly-heirarchical concepts in systems that do not support formal poly-heirarchies.

Whatever the reason, in FHIR code systems, all kinds of synonyms are represented the same way: as duplicate concepts with a declared relationship between them. The relationship is declared using the 'alternateCode' property, which identities another concept with the same real-world meaning that the code system defines.

In most cases (but not necessarily all), the concepts related with the alternateCode property will have the same:

The alternateCode property allows CodeSystem resource instances to represent multiple codes for a concept defined in a code system. The correct way to use the alternateCode property for an instance of CodeSystem.concept (A):

Note to Balloters: This section is newly introduced in R6 after extensive consideration in committee, and comments are sought.

Concept Hierarchy

Code systems may be presented hierarchically using either nested concept elements or properties. When exclusively using nested concept elements the code system hierarchy is a single tree, and concepts have only one parent. When using properties, polyhierarchies are allowed (e.g. concepts may have more than one parent).

If a code system hierarchy is represented using properties (typically, concepts that are subsumed by more than one other concept), nested concepts SHOULD NOT be used to represent any parts of the hierarchy structure in the Code System resource; the relationships between concepts should be defined using properties.

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
code regex [string] Matches any concept with the code matching the supplied string The regex flavor is determined by the server
[property] = [string] Includes all codes that have a property value equal to the specified string, where [property] is the code for any defined property. Where the type of the property is on of integer, dateTime or decimal, the FHIR search prefixes and semantics apply (see below)
[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
[property] regex [string] Includes all codes that have a property value matching the specified regex
[property] exists true or false When value is "true", includes all codes that have the specified property. When value is "false", includes all codes that lack the specified property
designation = [string] Matches any concept with a designation equal to the supplied string Designations considered include the concept.display, which counts as a designation
designation regex [string] Matches any concept with a designation matching the supplied string Designations considered include the concept.display, which counts as a designation

The following filters are defined for all code systems that support "is-a" relationships between concepts. (The filters can be used regardless of whether the "is-a" relationships are conveyed as concept properties or as concept nesting):

Property Name Operation Value Definition Notes
concept is-a [string] concept code Includes all concept ids that have a transitive is-a relationship with the concept Id provided as the value, including the provided concept itself (include descendant codes and self).
concept descendent-of [string] concept code Includes all concept ids that have a transitive is-a relationship with the concept Id provided as the value, excluding the provided concept itself (i.e. include descendant codes only).
concept in | not-in [string] a comma separated list of codes, or a value set uri Concepts in the list, or concepts in the value set expansion.
concept is-not-a [string] concept code The specified property of the code does not have an is-a relationship with the provided value.
concept generalizes [string] concept code Includes all concept ids that have a transitive is-a relationship from the concept Id provided as the value, including the provided concept itself (i.e. include ancestor codes and self).
concept child-of [string] concept code Only concepts with a direct hierarchical relationship to the index code and no other concepts. This does not include the index code in the output.
concept descendent-leaf [string] concept code Includes concept ids that have a transitive is-a relationship with the concept Id provided as the value, but which do not have any concept ids with transitive is-a relationships with themselves.

FHIR Search Semantics

If the = filter is used with a property that is defined on the CodeSystem, and if the property has a type of integer, dateTime or decimal, then the FHIR search rules apply. This means that the following prefixes may be used in the value of the filter:

The semantics of prefixes are as explained on the search page with regard to precision and range considerations, particularly on dates and decimals. Note that eq is not redundant - in it's absence, the semantics are for a direct string match, not a smart match as defined by the search semantics.

Some Examples: 

{ "property": "retiredDate", "operator": "=", "value": "lt2021-01-01" }

Any code that was retired before 2021. Regarding precision: 

{ "property": "retiredDate", "operator": "=", "value": "eq2022" }

would match a concept with a retiredDate of 2022-09-12. However: 

{ "property": "retiredDate", "operator": "=", "value": "2022" }

would not match a concept with a retiredDate of 2022-09-12.

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 using Value Sets). The table below summarizes how to treat these items as a code system:

StructureDefinition URL (CodeSystem.url) StructureDefinition.url
Concept (CodeSystem.concept) Each StructureDefinition.snapshot.element element corresponds to a code system concept.
Code (CodeSystem.concept.code) StructureDefinition.snapshot.element.id
Display (CodeSystem.concept.display) StructureDefinition.snapshot.element.label if one exists, otherwise StructureDefinition.snapshot.element.short
Definition (CodeSystem.concept.definition) StructureDefinition.snapshot.element.definition
Questionnaire URL (CodeSystem.url) Questionnaire.url
Concept (CodeSystem.concept) Each Questionnaire.item element corresponds to a code system concept.
Code (CodeSystem.concept.code) Questionnaire.item.linkId. Note: Questionnaire.item elements without a linkId cannot be addressed.
Display (CodeSystem.concept.display) Questionnaire.item.text
Definition (CodeSystem.concept.definition) Questionnaire-based implicit code system concepts do not have a definition.
Requirements URL (CodeSystem.url) Requirements.url
Concept (CodeSystem.concept) Each Requirements.statement element corresponds to a code system concept.
Code (CodeSystem.concept.code) Requirements.statement.key
Display (CodeSystem.concept.display) Requirements.statement.label if one exists, otherwise Requirements.statement.key.
Definition (CodeSystem.concept.definition) Requirements.statement.requirement
Measure URL (CodeSystem.url) Measure.url
Concept (CodeSystem.concept) Each Measure element with a linkId element corresponds to a code system concept. Specifically,
Code (CodeSystem.concept.code)
Display (CodeSystem.concept.display)
Definition (CodeSystem.concept.definition)

The above resource instances continue to use their url value as they normally would. However, whenever that URL appears as a value in the following fixed number of elements or parameters it SHALL be interpreted to be the implicit code system:

Note to Balloters:

```