FHIR Release 3 (STU)

This page is part of the FHIR Specification (v3.0.2: STU 3). 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

4.7 Resource CodeSystem - Content

Vocabulary Work GroupMaturity Level: 5 Trial UseCompartments: Not linked to any defined compartments

A code system resource specifies a set of codes drawn from one or more code systems.

4.7.1 Scope and Usage

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

  • code system - defines a set of codes with meanings (also known as enumeration, terminology, classification, and/or ontology)
  • value set - selects a set of codes from those defined by one or more code systems

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

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

  • Identifying URL and version
  • Description, Copyright, publication date, and other metadata
  • Some key properties of the code system itself - whether it's case sensitive, version safe, and whether it defines a compositional grammar
  • What filters can be used in value sets that use the code system in a ValueSet.compose element
  • What properties the concepts defined by the code system

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.

4.7.2 Boundaries and Relationships

  • Code systems are used in ValueSet resources
  • The Coding data type refers to CodeSystem resources by their canonical URL
  • The CodeSystem resource design is based on the functionality described in the OMG CTS 2 specification. CodeSystem resources can be converted to CTS2 code system resources.

The CodeSystem resource defines the content of a code system, and also its preferred identifier. The NamingSystem resource identifies the existence of a code or identifier system, and its possible and preferred identifiers. The key difference between the resources is who creates and manages them - CodeSystem resources are managed by the owner 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.

4.7.3 Background and Context

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

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.

4.7.3.1 CodeSystem Identification

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 possible
  • CodeSystem.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.

4.7.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CodeSystem IDomainResourceA set of codes drawn from one or more code systems
+ Within a code system definition, all the codes SHALL be unique
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... url Σ0..1uriLogical URI to reference this code system (globally unique) (Coding.system)
... identifier Σ0..1IdentifierAdditional identifier for the code system
... version Σ0..1stringBusiness version of the code system (Coding.version)
... name Σ0..1stringName for this code system (computer friendly)
... title Σ0..1stringName for this code system (human friendly)
... status ?!Σ1..1codedraft | active | retired | unknown
PublicationStatus (Required)
... experimental ?!Σ0..1booleanFor testing purposes, not real usage
... date Σ0..1dateTimeDate this was last changed
... publisher Σ0..1stringName of the publisher (organization or individual)
... contact Σ0..*ContactDetailContact details for the publisher
... description 0..1markdownNatural language description of the code system
... useContext Σ0..*UsageContextContext the content is intended to support
... jurisdiction Σ0..*CodeableConceptIntended jurisdiction for code system (if applicable)
Jurisdiction ValueSet (Extensible)
... purpose 0..1markdownWhy this code system is defined
... copyright 0..1markdownUse and/or publishing restrictions
... caseSensitive Σ0..1booleanIf code comparison is case sensitive
... valueSet Σ0..1uriCanonical URL for value set with entire code system
... hierarchyMeaning Σ0..1codegrouped-by | is-a | part-of | classified-with
CodeSystemHierarchyMeaning (Required)
... compositional Σ0..1booleanIf code system defines a post-composition grammar
... versionNeeded Σ0..1booleanIf definitions are not stable
... content Σ1..1codenot-present | example | fragment | complete
CodeSystemContentMode (Required)
... count Σ0..1unsignedIntTotal concepts in the code system
... filter Σ0..*BackboneElementFilter that can be used in a value set
.... code Σ1..1codeCode that identifies the filter
.... description Σ0..1stringHow or why the filter is used
.... operator Σ1..*codeOperators that can be used with filter
FilterOperator (Required)
.... value Σ1..1stringWhat to use for the value
... property Σ0..*BackboneElementAdditional information supplied about each concept
.... code Σ1..1codeIdentifies the property on the concepts, and when referred to in operations
.... uri Σ0..1uriFormal identifier for the property
.... description Σ0..1stringWhy the property is defined, and/or what it conveys
.... type Σ1..1codecode | Coding | string | integer | boolean | dateTime
PropertyType (Required)
... concept 0..*BackboneElementConcepts in the code system
.... code 1..1codeCode that identifies concept
.... display 0..1stringText to display to the user
.... definition 0..1stringFormal definition
.... designation 0..*BackboneElementAdditional representations for the concept
..... language 0..1codeHuman language of the designation
Common Languages (Extensible but limited to All Languages)
..... use 0..1CodingDetails how this designation would be used
Designation Use (Extensible)
..... value 1..1stringThe text value for this designation
.... property 0..*BackboneElementProperty value for the concept
..... code 1..1codeReference to CodeSystem.property.code
..... value[x] 1..1Value of the property for this concept
...... valueCodecode
...... valueCodingCoding
...... valueStringstring
...... valueIntegerinteger
...... valueBooleanboolean
...... valueDateTimedateTime
.... concept 0..*see conceptChild Concepts (is-a/contains/categorizes)

doco Documentation for this format

UML Diagram (Legend)

CodeSystem (DomainResource)An absolute URI that is used to identify this code system when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this code system is (or will be) published. The URL SHOULD include the major version of the code system. For more information see [Technical and Business Versions](resource.html#versions). This is used in [Coding]{datatypes.html#Coding}.systemurl : uri [0..1]A formal identifier that is used to identify this code system when it is represented in other formats, or referenced in a specification, model, design or an instanceidentifier : Identifier [0..1]The identifier that is used to identify this version of the code system when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the code system author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence. This is used in [Coding]{datatypes.html#Coding}.versionversion : string [0..1]A natural language name identifying the code system. This name should be usable as an identifier for the module by machine processing applications such as code generationname : string [0..1]A short, descriptive, user-friendly title for the code systemtitle : string [0..1]The status of this code system. Enables tracking the life-cycle of the content (this element modifies the meaning of other elements)status : code [1..1] The lifecycle status of a Value Set or Concept Map. (Strength=Required)PublicationStatus! A boolean value to indicate that this code system is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage (this element modifies the meaning of other elements)experimental : boolean [0..1]The date (and optionally time) when the code system was published. The date must change if and when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the code system changesdate : dateTime [0..1]The name of the individual or organization that published the code systempublisher : string [0..1]Contact details to assist a user in finding and communicating with the publishercontact : ContactDetail [0..*]A free text natural language description of the code system from a consumer's perspectivedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching for appropriate code system instancesuseContext : UsageContext [0..*]A legal or geographic region in which the code system is intended to be usedjurisdiction : CodeableConcept [0..*] Countries and regions within which this artifact is targeted for use (Strength=Extensible)Jurisdiction ValueSet+ Explaination of why this code system is needed and why it has been designed as it haspurpose : markdown [0..1]A copyright statement relating to the code system and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the code systemcopyright : markdown [0..1]If code comparison is case sensitive when codes within this system are compared to each othercaseSensitive : boolean [0..1]Canonical URL of value set that contains the entire code systemvalueSet : uri [0..1]The meaning of the hierarchy of conceptshierarchyMeaning : code [0..1] The meaning of the hierarchy of concepts in a code system (Strength=Required)CodeSystemHierarchyMeaning! True If code system defines a post-composition grammarcompositional : boolean [0..1]This flag is used to signify that the code system has not (or does not) maintain the definitions, and a version must be specified when referencing this code systemversionNeeded : boolean [0..1]How much of the content of the code system - the concepts and codes it defines - are represented in this resourcecontent : code [1..1] How much of the content of the code system - the concepts and codes it defines - are represented in a code system resource (Strength=Required)CodeSystemContentMode! The total number of concepts defined by the code system. Where the code system has a compositional grammar, the count refers to the number of base (primitive) conceptscount : unsignedInt [0..1]FilterThe code that identifies this filter when it is used in the instancecode : code [1..1]A description of how or why the filter is useddescription : string [0..1]A list of operators that can be used with the filteroperator : code [1..*] The kind of operation to perform as a part of a property based filter. (Strength=Required)FilterOperator! A description of what the value for the filter should bevalue : string [1..1]PropertyA code that is used to identify the property. The code is used internally (in CodeSystem.concept.property.code) and also externally, such as in property filterscode : code [1..1]Reference to the formal meaning of the property. One possible source of meaning is the [Concept Properties](codesystem-concept-properties.html) code systemuri : uri [0..1]A description of the property- why it is defined, and how its value might be useddescription : string [0..1]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)type : code [1..1] The type of a property value (Strength=Required)PropertyType! ConceptDefinitionA code - a text symbol - that uniquely identifies the concept within the code systemcode : code [1..1]A human readable string that is the recommended default way to present this concept to a userdisplay : string [0..1]The formal definition of the concept. The code system resource does not make formal definitions required, because of the prevalence of legacy systems. However, they are highly recommended, as without them there is no formal meaning associated with the conceptdefinition : string [0..1]DesignationThe language this designation is defined forlanguage : code [0..1] A human language. (Strength=Extensible)Common Languages+ A code that details how this designation would be useduse : Coding [0..1] Details of how a designation would be used. (Strength=Extensible)Designation Use+ The text value for this designationvalue : string [1..1]ConceptPropertyA code that is a reference to CodeSystem.property.codecode : code [1..1]The value of this propertyvalue[x] : Type [1..1] code|Coding|string|integer|boolean|dateTime A filter that can be used in a value set compose statement when selecting concepts using a filterfilter[0..*]A property defines an additional slot through which additional information can be provided about a conceptproperty[0..*]Additional representations for the concept - other languages, aliases, specialized purposes, used for particular purposes, etcdesignation[0..*]A property value for this conceptproperty[0..*]Defines children of a concept to produce a hierarchy of concepts. The nature of the relationships is variable (is-a/contains/categorizes) - see hierarchyMeaningconcept[0..*]Concepts that are in the code system. The concept definitions are inherently hierarchical, but the definitions must be consulted to determine what the meaning of the hierarchical relationships areconcept[0..*]

XML Template

<CodeSystem xmlns="http://hl7.org/fhir"> doco
 <!-- 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 | unknown -->
 <experimental value="[boolean]"/><!-- 0..1 For testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date this was last changed -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) -->
 <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the code system -->
 <useContext><!-- 0..* UsageContext Context the content is intended to support --></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 | example | 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

{doco
  "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 | unknown
  "experimental" : <boolean>, // For testing purposes, not real usage
  "date" : "<dateTime>", // Date this was last changed
  "publisher" : "<string>", // Name of the publisher (organization or individual)
  "contact" : [{ ContactDetail }], // Contact details for the publisher
  "description" : "<markdown>", // Natural language description of the code system
  "useContext" : [{ UsageContext }], // Context the content is intended to support
  "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 | example | 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/> .doco


[ 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 | unknown
  fhir:CodeSystem.experimental [ boolean ]; # 0..1 For testing purposes, not real usage
  fhir:CodeSystem.date [ dateTime ]; # 0..1 Date this was last changed
  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.description [ markdown ]; # 0..1 Natural language description of the code system
  fhir:CodeSystem.useContext [ UsageContext ], ... ; # 0..* Context the content is intended to support
  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 | example | 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

This analysis is available as XML or JSON.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. CodeSystem IDomainResourceA set of codes drawn from one or more code systems
+ Within a code system definition, all the codes SHALL be unique
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... url Σ0..1uriLogical URI to reference this code system (globally unique) (Coding.system)
... identifier Σ0..1IdentifierAdditional identifier for the code system
... version Σ0..1stringBusiness version of the code system (Coding.version)
... name Σ0..1stringName for this code system (computer friendly)
... title Σ0..1stringName for this code system (human friendly)
... status ?!Σ1..1codedraft | active | retired | unknown
PublicationStatus (Required)
... experimental ?!Σ0..1booleanFor testing purposes, not real usage
... date Σ0..1dateTimeDate this was last changed
... publisher Σ0..1stringName of the publisher (organization or individual)
... contact Σ0..*ContactDetailContact details for the publisher
... description 0..1markdownNatural language description of the code system
... useContext Σ0..*UsageContextContext the content is intended to support
... jurisdiction Σ0..*CodeableConceptIntended jurisdiction for code system (if applicable)
Jurisdiction ValueSet (Extensible)
... purpose 0..1markdownWhy this code system is defined
... copyright 0..1markdownUse and/or publishing restrictions
... caseSensitive Σ0..1booleanIf code comparison is case sensitive
... valueSet Σ0..1uriCanonical URL for value set with entire code system
... hierarchyMeaning Σ0..1codegrouped-by | is-a | part-of | classified-with
CodeSystemHierarchyMeaning (Required)
... compositional Σ0..1booleanIf code system defines a post-composition grammar
... versionNeeded Σ0..1booleanIf definitions are not stable
... content Σ1..1codenot-present | example | fragment | complete
CodeSystemContentMode (Required)
... count Σ0..1unsignedIntTotal concepts in the code system
... filter Σ0..*BackboneElementFilter that can be used in a value set
.... code Σ1..1codeCode that identifies the filter
.... description Σ0..1stringHow or why the filter is used
.... operator Σ1..*codeOperators that can be used with filter
FilterOperator (Required)
.... value Σ1..1stringWhat to use for the value
... property Σ0..*BackboneElementAdditional information supplied about each concept
.... code Σ1..1codeIdentifies the property on the concepts, and when referred to in operations
.... uri Σ0..1uriFormal identifier for the property
.... description Σ0..1stringWhy the property is defined, and/or what it conveys
.... type Σ1..1codecode | Coding | string | integer | boolean | dateTime
PropertyType (Required)
... concept 0..*BackboneElementConcepts in the code system
.... code 1..1codeCode that identifies concept
.... display 0..1stringText to display to the user
.... definition 0..1stringFormal definition
.... designation 0..*BackboneElementAdditional representations for the concept
..... language 0..1codeHuman language of the designation
Common Languages (Extensible but limited to All Languages)
..... use 0..1CodingDetails how this designation would be used
Designation Use (Extensible)
..... value 1..1stringThe text value for this designation
.... property 0..*BackboneElementProperty value for the concept
..... code 1..1codeReference to CodeSystem.property.code
..... value[x] 1..1Value of the property for this concept
...... valueCodecode
...... valueCodingCoding
...... valueStringstring
...... valueIntegerinteger
...... valueBooleanboolean
...... valueDateTimedateTime
.... concept 0..*see conceptChild Concepts (is-a/contains/categorizes)

doco Documentation for this format

UML Diagram (Legend)

CodeSystem (DomainResource)An absolute URI that is used to identify this code system when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this code system is (or will be) published. The URL SHOULD include the major version of the code system. For more information see [Technical and Business Versions](resource.html#versions). This is used in [Coding]{datatypes.html#Coding}.systemurl : uri [0..1]A formal identifier that is used to identify this code system when it is represented in other formats, or referenced in a specification, model, design or an instanceidentifier : Identifier [0..1]The identifier that is used to identify this version of the code system when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the code system author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence. This is used in [Coding]{datatypes.html#Coding}.versionversion : string [0..1]A natural language name identifying the code system. This name should be usable as an identifier for the module by machine processing applications such as code generationname : string [0..1]A short, descriptive, user-friendly title for the code systemtitle : string [0..1]The status of this code system. Enables tracking the life-cycle of the content (this element modifies the meaning of other elements)status : code [1..1] The lifecycle status of a Value Set or Concept Map. (Strength=Required)PublicationStatus! A boolean value to indicate that this code system is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage (this element modifies the meaning of other elements)experimental : boolean [0..1]The date (and optionally time) when the code system was published. The date must change if and when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the code system changesdate : dateTime [0..1]The name of the individual or organization that published the code systempublisher : string [0..1]Contact details to assist a user in finding and communicating with the publishercontact : ContactDetail [0..*]A free text natural language description of the code system from a consumer's perspectivedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching for appropriate code system instancesuseContext : UsageContext [0..*]A legal or geographic region in which the code system is intended to be usedjurisdiction : CodeableConcept [0..*] Countries and regions within which this artifact is targeted for use (Strength=Extensible)Jurisdiction ValueSet+ Explaination of why this code system is needed and why it has been designed as it haspurpose : markdown [0..1]A copyright statement relating to the code system and/or its contents. Copyright statements are generally legal restrictions on the use and publishing of the code systemcopyright : markdown [0..1]If code comparison is case sensitive when codes within this system are compared to each othercaseSensitive : boolean [0..1]Canonical URL of value set that contains the entire code systemvalueSet : uri [0..1]The meaning of the hierarchy of conceptshierarchyMeaning : code [0..1] The meaning of the hierarchy of concepts in a code system (Strength=Required)CodeSystemHierarchyMeaning! True If code system defines a post-composition grammarcompositional : boolean [0..1]This flag is used to signify that the code system has not (or does not) maintain the definitions, and a version must be specified when referencing this code systemversionNeeded : boolean [0..1]How much of the content of the code system - the concepts and codes it defines - are represented in this resourcecontent : code [1..1] How much of the content of the code system - the concepts and codes it defines - are represented in a code system resource (Strength=Required)CodeSystemContentMode! The total number of concepts defined by the code system. Where the code system has a compositional grammar, the count refers to the number of base (primitive) conceptscount : unsignedInt [0..1]FilterThe code that identifies this filter when it is used in the instancecode : code [1..1]A description of how or why the filter is useddescription : string [0..1]A list of operators that can be used with the filteroperator : code [1..*] The kind of operation to perform as a part of a property based filter. (Strength=Required)FilterOperator! A description of what the value for the filter should bevalue : string [1..1]PropertyA code that is used to identify the property. The code is used internally (in CodeSystem.concept.property.code) and also externally, such as in property filterscode : code [1..1]Reference to the formal meaning of the property. One possible source of meaning is the [Concept Properties](codesystem-concept-properties.html) code systemuri : uri [0..1]A description of the property- why it is defined, and how its value might be useddescription : string [0..1]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)type : code [1..1] The type of a property value (Strength=Required)PropertyType! ConceptDefinitionA code - a text symbol - that uniquely identifies the concept within the code systemcode : code [1..1]A human readable string that is the recommended default way to present this concept to a userdisplay : string [0..1]The formal definition of the concept. The code system resource does not make formal definitions required, because of the prevalence of legacy systems. However, they are highly recommended, as without them there is no formal meaning associated with the conceptdefinition : string [0..1]DesignationThe language this designation is defined forlanguage : code [0..1] A human language. (Strength=Extensible)Common Languages+ A code that details how this designation would be useduse : Coding [0..1] Details of how a designation would be used. (Strength=Extensible)Designation Use+ The text value for this designationvalue : string [1..1]ConceptPropertyA code that is a reference to CodeSystem.property.codecode : code [1..1]The value of this propertyvalue[x] : Type [1..1] code|Coding|string|integer|boolean|dateTime A filter that can be used in a value set compose statement when selecting concepts using a filterfilter[0..*]A property defines an additional slot through which additional information can be provided about a conceptproperty[0..*]Additional representations for the concept - other languages, aliases, specialized purposes, used for particular purposes, etcdesignation[0..*]A property value for this conceptproperty[0..*]Defines children of a concept to produce a hierarchy of concepts. The nature of the relationships is variable (is-a/contains/categorizes) - see hierarchyMeaningconcept[0..*]Concepts that are in the code system. The concept definitions are inherently hierarchical, but the definitions must be consulted to determine what the meaning of the hierarchical relationships areconcept[0..*]

XML Template

<CodeSystem xmlns="http://hl7.org/fhir"> doco
 <!-- 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 | unknown -->
 <experimental value="[boolean]"/><!-- 0..1 For testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date this was last changed -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) -->
 <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the code system -->
 <useContext><!-- 0..* UsageContext Context the content is intended to support --></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 | example | 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

{doco
  "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 | unknown
  "experimental" : <boolean>, // For testing purposes, not real usage
  "date" : "<dateTime>", // Date this was last changed
  "publisher" : "<string>", // Name of the publisher (organization or individual)
  "contact" : [{ ContactDetail }], // Contact details for the publisher
  "description" : "<markdown>", // Natural language description of the code system
  "useContext" : [{ UsageContext }], // Context the content is intended to support
  "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 | example | 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/> .doco


[ 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 | unknown
  fhir:CodeSystem.experimental [ boolean ]; # 0..1 For testing purposes, not real usage
  fhir:CodeSystem.date [ dateTime ]; # 0..1 Date this was last changed
  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.description [ markdown ]; # 0..1 Natural language description of the code system
  fhir:CodeSystem.useContext [ UsageContext ], ... ; # 0..* Context the content is intended to support
  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 | example | 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

This analysis is available as XML or JSON.

 

Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron (for ) + JSON Schema, ShEx (for Turtle)

4.7.4.1 Terminology Bindings

PathDefinitionTypeReference
CodeSystem.status The lifecycle status of a Value Set or Concept Map.RequiredPublicationStatus
CodeSystem.jurisdiction Countries and regions within which this artifact is targeted for useExtensibleJurisdiction ValueSet
CodeSystem.hierarchyMeaning The meaning of the hierarchy of concepts in a code systemRequiredCodeSystemHierarchyMeaning
CodeSystem.content How much of the content of the code system - the concepts and codes it defines - are represented in a code system resourceRequiredCodeSystemContentMode
CodeSystem.filter.operator The kind of operation to perform as a part of a property based filter.RequiredFilterOperator
CodeSystem.property.type The type of a property valueRequiredPropertyType
CodeSystem.concept.designation.language A human language.Extensible, but limited to All LanguagesCommon Languages
CodeSystem.concept.designation.use Details of how a designation would be used.ExtensibleDesignation Use

4.7.4.2 Constraints

  • csd-1: Within a code system definition, all the codes SHALL be unique (expression : (concept.code | descendants().concept.code).isDistinct())

4.7.4.3 Versioning Code Systems

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

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

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

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

4.7.5 Properties

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:

  • 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.element.target.dependsOn.property and ConceptMap.element.target.product.property
  • ValueSet: ValueSet.compose.include.filter.property can refer to any defined code system property
  • $lookup operation: In Parameters.parameter.name when returning information about a code
  • $translate operation: In Parameters.parameter.part.name for dependencies and products
  • $compose operation: In Parameters.parameter.name when providing codes, and in Parameters.parameter.name when asking for codes

Properties 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 its value might be used
type code | Coding | string | integer | boolean | dateTime The type of the property value. Properties of type "code" contain a code defined by the code system (e.g. a reference to 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.

4.7.6 Concept Status

Many Code Systems have a 'status' associated with the concept. This may categorise 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, 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 labeled as "Abstract' (not to be used in some circumstances), and have dates associated with their retirement or deprecation. All this information is represented as properties of the concepts. In order to assist with consistency between code systems, the following basic property URIs are defined:

http://hl7.org/fhir/concept-properties#statusA 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 (this is the default value)
  • experimental - provided for trial, but may be removed in the future
  • deprecated - planned to be removed from use
  • retired - still present for historical reasons, but no longer allowed to be used
http://hl7.org/fhir/concept-properties#retirementDateDate Concept was retired
http://hl7.org/fhir/concept-properties#deprecationDateDate Concept was deprecated
http://hl7.org/fhir/concept-properties#parentAn immediate parent of the concept in the hierarchy
http://hl7.org/fhir/concept-properties#childAn immediate child of the concept in the hierarchy
http://hl7.org/fhir/concept-properties#notSelectableThis 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.

4.7.6.1 Subsumption Testing

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 hierarchy, or if subsumption is declared explicitly using the subsumes extension).

Where a CodeSystem does not declare its 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:

4.7.6.2 Filters

The following filters are defined for all code systems:

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

4.7.6.3 Code systems with detailed metadata

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 Terminology, (Code System & ValueSet resources) 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:

  • It allows generic systems that support terminology management to perform standard terminology operations on code systems dealing with complex structures - code lookup, validation, subsumption testing, mapping and translation.
  • It allows information to be exchanged about individual medications, data elements and locations. Codes can't be retrieved individually in FHIR - it is necessary to retrieve the entire resource. By packaging the detailed information in separate resources, independent retrieval and update is possible.
  • It supports use-cases for sharing medication, location, observation type and similar information in circumstances where the code may be unknown, unavailable or occasionally non-existent (e.g., custom compounds, non-registered locations). Having a distinct resource supports these capabilities, which would not be possible using CodeSystem/ValueSet.

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

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

4.7.7 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

NameTypeDescriptionExpressionIn Common
codetokenA code defined in the code systemCodeSystem.concept.code
content-modetokennot-present | example | fragment | completeCodeSystem.content
datedateThe code system publication dateCodeSystem.date
descriptionstringThe description of the code systemCodeSystem.description
identifiertokenExternal identifier for the code systemCodeSystem.identifier
jurisdictiontokenIntended jurisdiction for the code systemCodeSystem.jurisdiction
languagetokenA language in which a designation is providedCodeSystem.concept.designation.language
namestringComputationally friendly name of the code systemCodeSystem.name
publisherstringName of the publisher of the code systemCodeSystem.publisher
statustokenThe current status of the code systemCodeSystem.status
systemuriThe system for any codes defined by this code system (same as 'url')CodeSystem.url
titlestringThe human-friendly name of the code systemCodeSystem.title
urluriThe uri that identifies the code systemCodeSystem.url
versiontokenThe business version of the code systemCodeSystem.version