This page is part of the FHIR Specification (v1.8.0: STU 3 Draft). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3
Vocabulary Work Group | Maturity Level: 0 | Compartments: Not linked to any defined compartments |
A code system resource specifies a set of codes drawn from one or more code systems.
The FHIR terminology specification is based 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 it's 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.
The CodeSystem resource is not intended to support the process of maintaining a code system. 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 distribution formats, and there is no intent that the CodeSystem resource be used for distributing these kind of terminologies. Instead, it is intended to be used for distributing the smaller ad-hoc code systems that are ubiqutiously encountered through out the healthcare process.
The CodeSystem
resource defines the content of a code system, and also it's 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 of the code system resource, who can properly define the features and content of the code system.
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 systemn, but there
should only be one CodeSystem
resource.
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.
Each code system has 2 different URLs that can be used to reference it - its logical identifier, and its location.
The location of the code system is a URL by which it may be retrieved, usually from a FHIR server, and may be a relative reference to a code system on the same server. The logical identifier is in the code system itself, in CodeSystem.url. This is the logical identity (sometimes called the canonical URL) that refers to this code system across all systems. Ideally, the URL should also be the location of the master version of the code system, though this is not always possible.
For example, the code systems published as part of FHIR all have a logical URL which is also a location by which 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.
Because it is common practice to copy (cache) code systems locally, most references to code systems can be either a logical or a literal URL.
A code system has 3 identifiers:
CodeSystem.id
: the logical id on the system that holds the code system - this changes as it moves from server to server (this id, with the server address prepended, is called the 'literal identity' of the resource)CodeSystem.url
: the canonical url that never changes for this code system - it is the same in every copy. Ideally, the URL should also be the location of the master version of the code system, though this is not always possibleCodeSystem.identifier
: A system/value pair that is used to identify the code system in other contexts (such as an OID in an HL7 v3 specification)For further information regarding resource identification, see Resource Identity.
This means that each code system has 2 different URLs that can be used to reference it -
its canonical url
, and its local location from which it may be retrieved.
Because it is common practice to copy (cache) code systems locally, most references to
code systems use the canonical URL.
For example, the code systems published as part of FHIR all have a canonical URL which is also a location by which they may be accessed in the FHIR specification itself. Note, though, that 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 published FHIR specification at their 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.
Structure
Name | Flags | Card. | Type | Description & Constraints |
---|---|---|---|---|
CodeSystem | I | DomainResource | A set of codes drawn from one or more code systems Within a code system definition, all the codes SHALL be unique | |
url | Σ | 0..1 | uri | Logical uri to reference this code system (globally unique) (Coding.system) |
identifier | Σ | 0..1 | Identifier | Additional identifier for the code system |
version | Σ | 0..1 | string | Business version of the code system (Coding.version) |
name | Σ | 0..1 | string | Name for this code system (Computer friendly) |
title | Σ | 0..1 | string | Name for this code system (Human friendly) |
status | ?!Σ | 1..1 | code | draft | active | retired PublicationStatus (Required) |
experimental | ?!Σ | 0..1 | boolean | If for testing purposes, not real usage |
publisher | Σ | 0..1 | string | Name of the publisher (Organization or individual) |
contact | Σ | 0..* | ContactDetail | Contact details for the publisher |
date | Σ | 0..1 | dateTime | Date this was last changed |
description | 0..1 | markdown | Natural language description of the code system | |
useContext | Σ | 0..* | UsageContext | Content intends to support these contexts |
jurisdiction | Σ | 0..* | CodeableConcept | Intended jurisdiction for code system (if applicable) Jurisdiction ValueSet (Extensible) |
purpose | 0..1 | markdown | Why this code system is defined | |
copyright | 0..1 | markdown | Use and/or publishing restrictions | |
caseSensitive | Σ | 0..1 | boolean | If code comparison is case sensitive |
valueSet | Σ | 0..1 | uri | Canonical URL for value set with entire code system |
hierarchyMeaning | Σ | 0..1 | code | grouped-by | is-a | part-of | classified-with CodeSystemHierarchyMeaning (Required) |
compositional | Σ | 0..1 | boolean | If code system defines a post-composition grammar |
versionNeeded | Σ | 0..1 | boolean | If definitions are not stable |
content | Σ | 1..1 | code | not-present | examplar | fragment | complete CodeSystemContentMode (Required) |
count | Σ | 0..1 | unsignedInt | Total concepts in the code system |
filter | Σ | 0..* | BackboneElement | Filter that can be used in a value set |
code | Σ | 1..1 | code | Code that identifies the filter |
description | Σ | 0..1 | string | How or why the filter is used |
operator | Σ | 1..* | code | Operators that can be used with filter FilterOperator (Required) |
value | Σ | 1..1 | string | What to use for the value |
property | Σ | 0..* | BackboneElement | Additional information supplied about each concept |
code | Σ | 1..1 | code | Identifies the property on the concepts, and when referred to in operations |
uri | Σ | 0..1 | uri | Formal identifier for the property |
description | Σ | 0..1 | string | Why the property is defined, and/or what it conveys |
type | Σ | 1..1 | code | code | Coding | string | integer | boolean | dateTime PropertyType (Required) |
concept | 0..* | BackboneElement | Concepts in the code system | |
code | 1..1 | code | Code that identifies concept | |
display | 0..1 | string | Text to display to the user | |
definition | 0..1 | string | Formal definition | |
designation | 0..* | BackboneElement | Additional representations for the concept | |
language | 0..1 | code | Human language of the designation Common Languages (Extensible but limited to All Languages) | |
use | 0..1 | Coding | Details how this designation would be used Designation Use (Extensible) | |
value | 1..1 | string | The text value for this designation | |
property | 0..* | BackboneElement | Property value for the concept | |
code | 1..1 | code | Reference to CodeSystem.property.code | |
value[x] | 1..1 | Value of the property for this concept | ||
valueCode | code | |||
valueCoding | Coding | |||
valueString | string | |||
valueInteger | integer | |||
valueBoolean | boolean | |||
valueDateTime | dateTime | |||
concept | 0..* | see concept | Child Concepts (is-a/contains/categorizes) | |
Documentation for this format |
UML Diagram (Legend)
XML Template
<CodeSystem xmlns="http://hl7.org/fhir"> <!-- from Resource: id, meta, implicitRules, and language --> <!-- from DomainResource: text, contained, extension, and modifierExtension --> <url value="[uri]"/><!-- 0..1 Logical uri to reference this code system (globally unique) (Coding.system) --> <identifier><!-- 0..1 Identifier Additional identifier for the code system --></identifier> <version value="[string]"/><!-- 0..1 Business version of the code system (Coding.version) --> <name value="[string]"/><!-- 0..1 Name for this code system (Computer friendly) --> <title value="[string]"/><!-- 0..1 Name for this code system (Human friendly) --> <status value="[code]"/><!-- 1..1 draft | active | retired --> <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage --> <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) --> <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact> <date value="[dateTime]"/><!-- 0..1 Date this was last changed --> <description value="[markdown]"/><!-- 0..1 Natural language description of the code system --> <useContext><!-- 0..* UsageContext Content intends to support these contexts --></useContext> <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for code system (if applicable) --></jurisdiction> <purpose value="[markdown]"/><!-- 0..1 Why this code system is defined --> <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions --> <caseSensitive value="[boolean]"/><!-- 0..1 If code comparison is case sensitive --> <valueSet value="[uri]"/><!-- 0..1 Canonical URL for value set with entire code system --> <hierarchyMeaning value="[code]"/><!-- 0..1 grouped-by | is-a | part-of | classified-with --> <compositional value="[boolean]"/><!-- 0..1 If code system defines a post-composition grammar --> <versionNeeded value="[boolean]"/><!-- 0..1 If definitions are not stable --> <content value="[code]"/><!-- 1..1 not-present | examplar | fragment | complete --> <count value="[unsignedInt]"/><!-- 0..1 Total concepts in the code system --> <filter> <!-- 0..* Filter that can be used in a value set --> <code value="[code]"/><!-- 1..1 Code that identifies the filter --> <description value="[string]"/><!-- 0..1 How or why the filter is used --> <operator value="[code]"/><!-- 1..* Operators that can be used with filter --> <value value="[string]"/><!-- 1..1 What to use for the value --> </filter> <property> <!-- 0..* Additional information supplied about each concept --> <code value="[code]"/><!-- 1..1 Identifies the property on the concepts, and when referred to in operations --> <uri value="[uri]"/><!-- 0..1 Formal identifier for the property --> <description value="[string]"/><!-- 0..1 Why the property is defined, and/or what it conveys --> <type value="[code]"/><!-- 1..1 code | Coding | string | integer | boolean | dateTime --> </property> <concept> <!-- 0..* Concepts in the code system --> <code value="[code]"/><!-- 1..1 Code that identifies concept --> <display value="[string]"/><!-- 0..1 Text to display to the user --> <definition value="[string]"/><!-- 0..1 Formal definition --> <designation> <!-- 0..* Additional representations for the concept --> <language value="[code]"/><!-- 0..1 Human language of the designation --> <use><!-- 0..1 Coding Details how this designation would be used --></use> <value value="[string]"/><!-- 1..1 The text value for this designation --> </designation> <property> <!-- 0..* Property value for the concept --> <code value="[code]"/><!-- 1..1 Reference to CodeSystem.property.code --> <value[x]><!-- 1..1 code|Coding|string|integer|boolean|dateTime Value of the property for this concept --></value[x]> </property> <concept><!-- 0..* Content as for CodeSystem.concept Child Concepts (is-a/contains/categorizes) --></concept> </concept> </CodeSystem>
JSON Template
{ "resourceType" : "CodeSystem", // from Resource: id, meta, implicitRules, and language // from DomainResource: text, contained, extension, and modifierExtension "url" : "<uri>", // Logical uri to reference this code system (globally unique) (Coding.system) "identifier" : { Identifier }, // Additional identifier for the code system "version" : "<string>", // Business version of the code system (Coding.version) "name" : "<string>", // Name for this code system (Computer friendly) "title" : "<string>", // Name for this code system (Human friendly) "status" : "<code>", // R! draft | active | retired "experimental" : <boolean>, // If for testing purposes, not real usage "publisher" : "<string>", // Name of the publisher (Organization or individual) "contact" : [{ ContactDetail }], // Contact details for the publisher "date" : "<dateTime>", // Date this was last changed "description" : "<markdown>", // Natural language description of the code system "useContext" : [{ UsageContext }], // Content intends to support these contexts "jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for code system (if applicable) "purpose" : "<markdown>", // Why this code system is defined "copyright" : "<markdown>", // Use and/or publishing restrictions "caseSensitive" : <boolean>, // If code comparison is case sensitive "valueSet" : "<uri>", // Canonical URL for value set with entire code system "hierarchyMeaning" : "<code>", // grouped-by | is-a | part-of | classified-with "compositional" : <boolean>, // If code system defines a post-composition grammar "versionNeeded" : <boolean>, // If definitions are not stable "content" : "<code>", // R! not-present | examplar | fragment | complete "count" : "<unsignedInt>", // Total concepts in the code system "filter" : [{ // Filter that can be used in a value set "code" : "<code>", // R! Code that identifies the filter "description" : "<string>", // How or why the filter is used "operator" : ["<code>"], // R! Operators that can be used with filter "value" : "<string>" // R! What to use for the value }], "property" : [{ // Additional information supplied about each concept "code" : "<code>", // R! Identifies the property on the concepts, and when referred to in operations "uri" : "<uri>", // Formal identifier for the property "description" : "<string>", // Why the property is defined, and/or what it conveys "type" : "<code>" // R! code | Coding | string | integer | boolean | dateTime }], "concept" : [{ // Concepts in the code system "code" : "<code>", // R! Code that identifies concept "display" : "<string>", // Text to display to the user "definition" : "<string>", // Formal definition "designation" : [{ // Additional representations for the concept "language" : "<code>", // Human language of the designation "use" : { Coding }, // Details how this designation would be used "value" : "<string>" // R! The text value for this designation }], "property" : [{ // Property value for the concept "code" : "<code>", // R! Reference to CodeSystem.property.code // value[x]: Value of the property for this concept. One of these 6: "valueCode" : "<code>" "valueCoding" : { Coding } "valueString" : "<string>" "valueInteger" : <integer> "valueBoolean" : <boolean> "valueDateTime" : "<dateTime>" }], "concept" : [{ Content as for CodeSystem.concept }] // Child Concepts (is-a/contains/categorizes) }] }
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ a fhir:CodeSystem; fhir:nodeRole fhir:treeRoot; # if this is the parser root # from Resource: .id, .meta, .implicitRules, and .language # from DomainResource: .text, .contained, .extension, and .modifierExtension fhir:CodeSystem.url [ uri ]; # 0..1 Logical uri to reference this code system (globally unique) (Coding.system) fhir:CodeSystem.identifier [ Identifier ]; # 0..1 Additional identifier for the code system fhir:CodeSystem.version [ string ]; # 0..1 Business version of the code system (Coding.version) fhir:CodeSystem.name [ string ]; # 0..1 Name for this code system (Computer friendly) fhir:CodeSystem.title [ string ]; # 0..1 Name for this code system (Human friendly) fhir:CodeSystem.status [ code ]; # 1..1 draft | active | retired fhir:CodeSystem.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage fhir:CodeSystem.publisher [ string ]; # 0..1 Name of the publisher (Organization or individual) fhir:CodeSystem.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher fhir:CodeSystem.date [ dateTime ]; # 0..1 Date this was last changed fhir:CodeSystem.description [ markdown ]; # 0..1 Natural language description of the code system fhir:CodeSystem.useContext [ UsageContext ], ... ; # 0..* Content intends to support these contexts fhir:CodeSystem.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for code system (if applicable) fhir:CodeSystem.purpose [ markdown ]; # 0..1 Why this code system is defined fhir:CodeSystem.copyright [ markdown ]; # 0..1 Use and/or publishing restrictions fhir:CodeSystem.caseSensitive [ boolean ]; # 0..1 If code comparison is case sensitive fhir:CodeSystem.valueSet [ uri ]; # 0..1 Canonical URL for value set with entire code system fhir:CodeSystem.hierarchyMeaning [ code ]; # 0..1 grouped-by | is-a | part-of | classified-with fhir:CodeSystem.compositional [ boolean ]; # 0..1 If code system defines a post-composition grammar fhir:CodeSystem.versionNeeded [ boolean ]; # 0..1 If definitions are not stable fhir:CodeSystem.content [ code ]; # 1..1 not-present | examplar | fragment | complete fhir:CodeSystem.count [ unsignedInt ]; # 0..1 Total concepts in the code system fhir:CodeSystem.filter [ # 0..* Filter that can be used in a value set fhir:CodeSystem.filter.code [ code ]; # 1..1 Code that identifies the filter fhir:CodeSystem.filter.description [ string ]; # 0..1 How or why the filter is used fhir:CodeSystem.filter.operator [ code ], ... ; # 1..* Operators that can be used with filter fhir:CodeSystem.filter.value [ string ]; # 1..1 What to use for the value ], ...; fhir:CodeSystem.property [ # 0..* Additional information supplied about each concept fhir:CodeSystem.property.code [ code ]; # 1..1 Identifies the property on the concepts, and when referred to in operations fhir:CodeSystem.property.uri [ uri ]; # 0..1 Formal identifier for the property fhir:CodeSystem.property.description [ string ]; # 0..1 Why the property is defined, and/or what it conveys fhir:CodeSystem.property.type [ code ]; # 1..1 code | Coding | string | integer | boolean | dateTime ], ...; fhir:CodeSystem.concept [ # 0..* Concepts in the code system fhir:CodeSystem.concept.code [ code ]; # 1..1 Code that identifies concept fhir:CodeSystem.concept.display [ string ]; # 0..1 Text to display to the user fhir:CodeSystem.concept.definition [ string ]; # 0..1 Formal definition fhir:CodeSystem.concept.designation [ # 0..* Additional representations for the concept fhir:CodeSystem.concept.designation.language [ code ]; # 0..1 Human language of the designation fhir:CodeSystem.concept.designation.use [ Coding ]; # 0..1 Details how this designation would be used fhir:CodeSystem.concept.designation.value [ string ]; # 1..1 The text value for this designation ], ...; fhir:CodeSystem.concept.property [ # 0..* Property value for the concept fhir:CodeSystem.concept.property.code [ code ]; # 1..1 Reference to CodeSystem.property.code # CodeSystem.concept.property.value[x] : 1..1 Value of the property for this concept. One of these 6 fhir:CodeSystem.concept.property.valueCode [ code ] fhir:CodeSystem.concept.property.valueCoding [ Coding ] fhir:CodeSystem.concept.property.valueString [ string ] fhir:CodeSystem.concept.property.valueInteger [ integer ] fhir:CodeSystem.concept.property.valueBoolean [ boolean ] fhir:CodeSystem.concept.property.valueDateTime [ dateTime ] ], ...; fhir:CodeSystem.concept.concept [ See CodeSystem.concept ], ... ; # 0..* Child Concepts (is-a/contains/categorizes) ], ...; ]
Changes since DSTU2
This resource did not exist in Release 2
Structure
Name | Flags | Card. | Type | Description & Constraints |
---|---|---|---|---|
CodeSystem | I | DomainResource | A set of codes drawn from one or more code systems Within a code system definition, all the codes SHALL be unique | |
url | Σ | 0..1 | uri | Logical uri to reference this code system (globally unique) (Coding.system) |
identifier | Σ | 0..1 | Identifier | Additional identifier for the code system |
version | Σ | 0..1 | string | Business version of the code system (Coding.version) |
name | Σ | 0..1 | string | Name for this code system (Computer friendly) |
title | Σ | 0..1 | string | Name for this code system (Human friendly) |
status | ?!Σ | 1..1 | code | draft | active | retired PublicationStatus (Required) |
experimental | ?!Σ | 0..1 | boolean | If for testing purposes, not real usage |
publisher | Σ | 0..1 | string | Name of the publisher (Organization or individual) |
contact | Σ | 0..* | ContactDetail | Contact details for the publisher |
date | Σ | 0..1 | dateTime | Date this was last changed |
description | 0..1 | markdown | Natural language description of the code system | |
useContext | Σ | 0..* | UsageContext | Content intends to support these contexts |
jurisdiction | Σ | 0..* | CodeableConcept | Intended jurisdiction for code system (if applicable) Jurisdiction ValueSet (Extensible) |
purpose | 0..1 | markdown | Why this code system is defined | |
copyright | 0..1 | markdown | Use and/or publishing restrictions | |
caseSensitive | Σ | 0..1 | boolean | If code comparison is case sensitive |
valueSet | Σ | 0..1 | uri | Canonical URL for value set with entire code system |
hierarchyMeaning | Σ | 0..1 | code | grouped-by | is-a | part-of | classified-with CodeSystemHierarchyMeaning (Required) |
compositional | Σ | 0..1 | boolean | If code system defines a post-composition grammar |
versionNeeded | Σ | 0..1 | boolean | If definitions are not stable |
content | Σ | 1..1 | code | not-present | examplar | fragment | complete CodeSystemContentMode (Required) |
count | Σ | 0..1 | unsignedInt | Total concepts in the code system |
filter | Σ | 0..* | BackboneElement | Filter that can be used in a value set |
code | Σ | 1..1 | code | Code that identifies the filter |
description | Σ | 0..1 | string | How or why the filter is used |
operator | Σ | 1..* | code | Operators that can be used with filter FilterOperator (Required) |
value | Σ | 1..1 | string | What to use for the value |
property | Σ | 0..* | BackboneElement | Additional information supplied about each concept |
code | Σ | 1..1 | code | Identifies the property on the concepts, and when referred to in operations |
uri | Σ | 0..1 | uri | Formal identifier for the property |
description | Σ | 0..1 | string | Why the property is defined, and/or what it conveys |
type | Σ | 1..1 | code | code | Coding | string | integer | boolean | dateTime PropertyType (Required) |
concept | 0..* | BackboneElement | Concepts in the code system | |
code | 1..1 | code | Code that identifies concept | |
display | 0..1 | string | Text to display to the user | |
definition | 0..1 | string | Formal definition | |
designation | 0..* | BackboneElement | Additional representations for the concept | |
language | 0..1 | code | Human language of the designation Common Languages (Extensible but limited to All Languages) | |
use | 0..1 | Coding | Details how this designation would be used Designation Use (Extensible) | |
value | 1..1 | string | The text value for this designation | |
property | 0..* | BackboneElement | Property value for the concept | |
code | 1..1 | code | Reference to CodeSystem.property.code | |
value[x] | 1..1 | Value of the property for this concept | ||
valueCode | code | |||
valueCoding | Coding | |||
valueString | string | |||
valueInteger | integer | |||
valueBoolean | boolean | |||
valueDateTime | dateTime | |||
concept | 0..* | see concept | Child Concepts (is-a/contains/categorizes) | |
Documentation for this format |
XML Template
<CodeSystem xmlns="http://hl7.org/fhir"> <!-- from Resource: id, meta, implicitRules, and language --> <!-- from DomainResource: text, contained, extension, and modifierExtension --> <url value="[uri]"/><!-- 0..1 Logical uri to reference this code system (globally unique) (Coding.system) --> <identifier><!-- 0..1 Identifier Additional identifier for the code system --></identifier> <version value="[string]"/><!-- 0..1 Business version of the code system (Coding.version) --> <name value="[string]"/><!-- 0..1 Name for this code system (Computer friendly) --> <title value="[string]"/><!-- 0..1 Name for this code system (Human friendly) --> <status value="[code]"/><!-- 1..1 draft | active | retired --> <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage --> <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) --> <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact> <date value="[dateTime]"/><!-- 0..1 Date this was last changed --> <description value="[markdown]"/><!-- 0..1 Natural language description of the code system --> <useContext><!-- 0..* UsageContext Content intends to support these contexts --></useContext> <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for code system (if applicable) --></jurisdiction> <purpose value="[markdown]"/><!-- 0..1 Why this code system is defined --> <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions --> <caseSensitive value="[boolean]"/><!-- 0..1 If code comparison is case sensitive --> <valueSet value="[uri]"/><!-- 0..1 Canonical URL for value set with entire code system --> <hierarchyMeaning value="[code]"/><!-- 0..1 grouped-by | is-a | part-of | classified-with --> <compositional value="[boolean]"/><!-- 0..1 If code system defines a post-composition grammar --> <versionNeeded value="[boolean]"/><!-- 0..1 If definitions are not stable --> <content value="[code]"/><!-- 1..1 not-present | examplar | fragment | complete --> <count value="[unsignedInt]"/><!-- 0..1 Total concepts in the code system --> <filter> <!-- 0..* Filter that can be used in a value set --> <code value="[code]"/><!-- 1..1 Code that identifies the filter --> <description value="[string]"/><!-- 0..1 How or why the filter is used --> <operator value="[code]"/><!-- 1..* Operators that can be used with filter --> <value value="[string]"/><!-- 1..1 What to use for the value --> </filter> <property> <!-- 0..* Additional information supplied about each concept --> <code value="[code]"/><!-- 1..1 Identifies the property on the concepts, and when referred to in operations --> <uri value="[uri]"/><!-- 0..1 Formal identifier for the property --> <description value="[string]"/><!-- 0..1 Why the property is defined, and/or what it conveys --> <type value="[code]"/><!-- 1..1 code | Coding | string | integer | boolean | dateTime --> </property> <concept> <!-- 0..* Concepts in the code system --> <code value="[code]"/><!-- 1..1 Code that identifies concept --> <display value="[string]"/><!-- 0..1 Text to display to the user --> <definition value="[string]"/><!-- 0..1 Formal definition --> <designation> <!-- 0..* Additional representations for the concept --> <language value="[code]"/><!-- 0..1 Human language of the designation --> <use><!-- 0..1 Coding Details how this designation would be used --></use> <value value="[string]"/><!-- 1..1 The text value for this designation --> </designation> <property> <!-- 0..* Property value for the concept --> <code value="[code]"/><!-- 1..1 Reference to CodeSystem.property.code --> <value[x]><!-- 1..1 code|Coding|string|integer|boolean|dateTime Value of the property for this concept --></value[x]> </property> <concept><!-- 0..* Content as for CodeSystem.concept Child Concepts (is-a/contains/categorizes) --></concept> </concept> </CodeSystem>
JSON Template
{ "resourceType" : "CodeSystem", // from Resource: id, meta, implicitRules, and language // from DomainResource: text, contained, extension, and modifierExtension "url" : "<uri>", // Logical uri to reference this code system (globally unique) (Coding.system) "identifier" : { Identifier }, // Additional identifier for the code system "version" : "<string>", // Business version of the code system (Coding.version) "name" : "<string>", // Name for this code system (Computer friendly) "title" : "<string>", // Name for this code system (Human friendly) "status" : "<code>", // R! draft | active | retired "experimental" : <boolean>, // If for testing purposes, not real usage "publisher" : "<string>", // Name of the publisher (Organization or individual) "contact" : [{ ContactDetail }], // Contact details for the publisher "date" : "<dateTime>", // Date this was last changed "description" : "<markdown>", // Natural language description of the code system "useContext" : [{ UsageContext }], // Content intends to support these contexts "jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for code system (if applicable) "purpose" : "<markdown>", // Why this code system is defined "copyright" : "<markdown>", // Use and/or publishing restrictions "caseSensitive" : <boolean>, // If code comparison is case sensitive "valueSet" : "<uri>", // Canonical URL for value set with entire code system "hierarchyMeaning" : "<code>", // grouped-by | is-a | part-of | classified-with "compositional" : <boolean>, // If code system defines a post-composition grammar "versionNeeded" : <boolean>, // If definitions are not stable "content" : "<code>", // R! not-present | examplar | fragment | complete "count" : "<unsignedInt>", // Total concepts in the code system "filter" : [{ // Filter that can be used in a value set "code" : "<code>", // R! Code that identifies the filter "description" : "<string>", // How or why the filter is used "operator" : ["<code>"], // R! Operators that can be used with filter "value" : "<string>" // R! What to use for the value }], "property" : [{ // Additional information supplied about each concept "code" : "<code>", // R! Identifies the property on the concepts, and when referred to in operations "uri" : "<uri>", // Formal identifier for the property "description" : "<string>", // Why the property is defined, and/or what it conveys "type" : "<code>" // R! code | Coding | string | integer | boolean | dateTime }], "concept" : [{ // Concepts in the code system "code" : "<code>", // R! Code that identifies concept "display" : "<string>", // Text to display to the user "definition" : "<string>", // Formal definition "designation" : [{ // Additional representations for the concept "language" : "<code>", // Human language of the designation "use" : { Coding }, // Details how this designation would be used "value" : "<string>" // R! The text value for this designation }], "property" : [{ // Property value for the concept "code" : "<code>", // R! Reference to CodeSystem.property.code // value[x]: Value of the property for this concept. One of these 6: "valueCode" : "<code>" "valueCoding" : { Coding } "valueString" : "<string>" "valueInteger" : <integer> "valueBoolean" : <boolean> "valueDateTime" : "<dateTime>" }], "concept" : [{ Content as for CodeSystem.concept }] // Child Concepts (is-a/contains/categorizes) }] }
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ a fhir:CodeSystem; fhir:nodeRole fhir:treeRoot; # if this is the parser root # from Resource: .id, .meta, .implicitRules, and .language # from DomainResource: .text, .contained, .extension, and .modifierExtension fhir:CodeSystem.url [ uri ]; # 0..1 Logical uri to reference this code system (globally unique) (Coding.system) fhir:CodeSystem.identifier [ Identifier ]; # 0..1 Additional identifier for the code system fhir:CodeSystem.version [ string ]; # 0..1 Business version of the code system (Coding.version) fhir:CodeSystem.name [ string ]; # 0..1 Name for this code system (Computer friendly) fhir:CodeSystem.title [ string ]; # 0..1 Name for this code system (Human friendly) fhir:CodeSystem.status [ code ]; # 1..1 draft | active | retired fhir:CodeSystem.experimental [ boolean ]; # 0..1 If for testing purposes, not real usage fhir:CodeSystem.publisher [ string ]; # 0..1 Name of the publisher (Organization or individual) fhir:CodeSystem.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher fhir:CodeSystem.date [ dateTime ]; # 0..1 Date this was last changed fhir:CodeSystem.description [ markdown ]; # 0..1 Natural language description of the code system fhir:CodeSystem.useContext [ UsageContext ], ... ; # 0..* Content intends to support these contexts fhir:CodeSystem.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for code system (if applicable) fhir:CodeSystem.purpose [ markdown ]; # 0..1 Why this code system is defined fhir:CodeSystem.copyright [ markdown ]; # 0..1 Use and/or publishing restrictions fhir:CodeSystem.caseSensitive [ boolean ]; # 0..1 If code comparison is case sensitive fhir:CodeSystem.valueSet [ uri ]; # 0..1 Canonical URL for value set with entire code system fhir:CodeSystem.hierarchyMeaning [ code ]; # 0..1 grouped-by | is-a | part-of | classified-with fhir:CodeSystem.compositional [ boolean ]; # 0..1 If code system defines a post-composition grammar fhir:CodeSystem.versionNeeded [ boolean ]; # 0..1 If definitions are not stable fhir:CodeSystem.content [ code ]; # 1..1 not-present | examplar | fragment | complete fhir:CodeSystem.count [ unsignedInt ]; # 0..1 Total concepts in the code system fhir:CodeSystem.filter [ # 0..* Filter that can be used in a value set fhir:CodeSystem.filter.code [ code ]; # 1..1 Code that identifies the filter fhir:CodeSystem.filter.description [ string ]; # 0..1 How or why the filter is used fhir:CodeSystem.filter.operator [ code ], ... ; # 1..* Operators that can be used with filter fhir:CodeSystem.filter.value [ string ]; # 1..1 What to use for the value ], ...; fhir:CodeSystem.property [ # 0..* Additional information supplied about each concept fhir:CodeSystem.property.code [ code ]; # 1..1 Identifies the property on the concepts, and when referred to in operations fhir:CodeSystem.property.uri [ uri ]; # 0..1 Formal identifier for the property fhir:CodeSystem.property.description [ string ]; # 0..1 Why the property is defined, and/or what it conveys fhir:CodeSystem.property.type [ code ]; # 1..1 code | Coding | string | integer | boolean | dateTime ], ...; fhir:CodeSystem.concept [ # 0..* Concepts in the code system fhir:CodeSystem.concept.code [ code ]; # 1..1 Code that identifies concept fhir:CodeSystem.concept.display [ string ]; # 0..1 Text to display to the user fhir:CodeSystem.concept.definition [ string ]; # 0..1 Formal definition fhir:CodeSystem.concept.designation [ # 0..* Additional representations for the concept fhir:CodeSystem.concept.designation.language [ code ]; # 0..1 Human language of the designation fhir:CodeSystem.concept.designation.use [ Coding ]; # 0..1 Details how this designation would be used fhir:CodeSystem.concept.designation.value [ string ]; # 1..1 The text value for this designation ], ...; fhir:CodeSystem.concept.property [ # 0..* Property value for the concept fhir:CodeSystem.concept.property.code [ code ]; # 1..1 Reference to CodeSystem.property.code # CodeSystem.concept.property.value[x] : 1..1 Value of the property for this concept. One of these 6 fhir:CodeSystem.concept.property.valueCode [ code ] fhir:CodeSystem.concept.property.valueCoding [ Coding ] fhir:CodeSystem.concept.property.valueString [ string ] fhir:CodeSystem.concept.property.valueInteger [ integer ] fhir:CodeSystem.concept.property.valueBoolean [ boolean ] fhir:CodeSystem.concept.property.valueDateTime [ dateTime ] ], ...; fhir:CodeSystem.concept.concept [ See CodeSystem.concept ], ... ; # 0..* Child Concepts (is-a/contains/categorizes) ], ...; ]
Changes since DSTU2
This resource did not exist in Release 2
Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron (for ) + JSON Schema, ShEx (for Turtle), JSON-LD (for RDF as JSON-LD),
Path | Definition | Type | Reference |
---|---|---|---|
CodeSystem.status | The lifecycle status of a Value Set or Concept Map. | Required | PublicationStatus |
CodeSystem.jurisdiction | Countries and regions within which this artifact is targeted for use | Extensible | Jurisdiction ValueSet |
CodeSystem.hierarchyMeaning | The meaning of the hierarchy of concepts in a code system | Required | CodeSystemHierarchyMeaning |
CodeSystem.content | How much of the content of the code system - the concepts and codes it defines - are represented in a code system resource | Required | CodeSystemContentMode |
CodeSystem.filter.operator | The kind of operation to perform as a part of a property based filter. | Required | FilterOperator |
CodeSystem.property.type | The type of a property value | Required | PropertyType |
CodeSystem.concept.designation.language | A human language. | Extensible, but limited to All Languages | Common Languages |
CodeSystem.concept.designation.use | Details of how a designation would be used. | Extensible | Designation Use |
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.
Each code system can have one or more properties. Each concept defined by the code system may have one more values for each 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:
ConceptMap.element.target.dependsOn.property
and ConceptMap.element.target.product.property
ValueSet.compose.include.filter.property
can refer to any defined code system propertyParameters.parameter.name
when returning information about a codeParameters.parameter.part.name
for dependencies and productsParameters.parameter.name
when providing codes, and in Parameters.parameter.name
when asking for codesProperties are defined using the following elements:
Name | Details | Description |
code | code | Used to identify the property, as enumerated above |
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 it's 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 anotherr 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.
Many Code Systems have a 'status' associated with the concept. This may categorise 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 be also be labelled 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 | 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):
|
http://hl7.org/fhir/concept-properties#retirementDate | Date Concept was retired |
http://hl7.org/fhir/concept-properties#deprecationDate | Date Concept was deprecated |
http://hl7.org/fhir/concept-properties#parent | An immediate parent of the concept in the heirarchy |
http://hl7.org/fhir/concept-properties#child | An immediate child of the concept in the heirarchy |
http://hl7.org/fhir/concept-properties#notSelectable | This concept is a grouping concept and not intended to be used in the normal use of the code system (though my be used for filters etc). This is also known as 'Abstract' |
Typically, Code systems are presented hierachically, where the hierachy has a defined meaning.
For this reason, the parent and child properties are mostly only used when performing concept lookup.
Note that in some code systems, concepts may have multiple parents, so the parent property may repeat.
These code systems are not usually presented in a hierachical fashion in a CodeSystem
if they are represented in a CodeSystem at all. If they are,
then the subsumes extension must be used.
The words 'subsume', 'subsumes', 'subsumed' and 'subsumption' are defined in terms of the CodeSystem hierarchy (i.e. CodeSystem.hierarchyMeaning). Concept A is considered to be subsumed by Concept B if it comes under Concept B in the heirarchy, or if subsumption is declared explicitly using the subsumes extension).
Where a CodeSystem does not declare it's hierarchy meaning directly, then the code system documentation must be consulted manually to determinw 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:
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 delimited |
Sometimes code systems may be used to represent more complex information than just code, display name and code system. For example, a code system of drug information which contains information about the content of the medication (e.g., RxNorm), or a set of observation types, that contain methods, units, etc. (e.g., LOINC). In FHIR, these are handled by splitting the concept into two distinct parts - the ValueSet resource is used to manage the codes, display names and relationships. A separate "detail" resource (e.g., Medication for drugs, DataElement for observation types, Location for 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 ValueSet 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. For further
information, see Implicit Code Systems.
Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.
Name | Type | Description | Paths | In Common |
code | token | A code defined in the code system | CodeSystem.concept.code | |
content | token | not-present | examplar | fragment | complete | CodeSystem.content | |
date | date | The code system publication date | CodeSystem.date | |
description | string | Text search against the description of the code system | CodeSystem.description | |
identifier | token | External identifiers for the code system | CodeSystem.identifier | |
jurisdiction | token | Intended jurisdiction for code system | CodeSystem.jurisdiction | |
language | token | A language in which a designation is provided | CodeSystem.concept.designation.language | |
name | string | Name of the code system | CodeSystem.name | |
publisher | string | Name of the publisher of the code system | CodeSystem.publisher | |
status | token | The current status of the code system | CodeSystem.status | |
system | uri | The system for any codes defined by this code system (same as 'url') | CodeSystem.url | |
title | string | Text search against the title of the code system | CodeSystem.title | |
url | uri | The uri that identifies the code system | CodeSystem.url | |
version | token | The version identifier of the code system | CodeSystem.version |