STU3 Candidate

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

4.11 Resource CodeSystem - Content

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.

4.11.1 Scope and Usage

The FHIR terminology specification is based 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 it's 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.11.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 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.

4.11.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.11.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.11.4 Resource Content

Structure

Name Flags Card. Type Description & Constraints doco
. . 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)

doco Documentation for this format

UML Diagram ( Legend )

CodeSystem ( DomainResource ) An absolute URL 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}.system url : 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 instance identifier : 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 are orderable. This is used in [Coding]{datatypes.html#Coding}.version version : 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 generation name : string [0..1] A short, descriptive, user-friendly title for the code system title : 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 flag 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 name of the individual or organization that published the code system publisher : string [0..1] Contact details to assist a user in finding and communicating with the publisher contact : ContactDetail [0..*] The date (and optionally time) when the code system was published. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the code system changes date : dateTime [0..1] A free text natural language description of the code system from the consumer's perspective description : 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 of code system definitions useContext : UsageContext [0..*] A jurisdiction in which the code system is intended to be used jurisdiction : CodeableConcept [0..*] « Countries and regions within which this artifact is targeted for use (Strength=Extensible) Jurisdiction ValueSet + » Explains why this code system is needed and why it has been designed as it has purpose : 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 system copyright : markdown [0..1] If code comparison is case sensitive when codes within this system are compared to each other caseSensitive : boolean [0..1] Canonical URL of value set that contains the entire code system valueSet : uri [0..1] The meaning of the heirarchy of concepts hierarchyMeaning : 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 grammar compositional : 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 system versionNeeded : boolean [0..1] How much of the content of the code system - the concepts and codes it defines - are represented in this resource content : 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) concepts count : unsignedInt [0..1] Filter The code that identifies this filter when it is used in the instance code : code [1..1] A description of how or why the filter is used description : string [0..1] A list of operators that can be used with the filter operator : 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 be value : string [1..1] Property A code that is used to identify the property. The code is used internally (in CodeSystem.concept.property.code) and also externally, such as in property filters code : 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 system uri : uri [0..1] A description of the property- why it is defined, and how it's value might be used description : 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 ! » ConceptDefinition A code - a text symbol - that uniquely identifies the concept within the code system code : code [1..1] A human readable string that is the recommended default way to present this concept to a user display : 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 concept definition : string [0..1] Designation The language this designation is defined for language : code [0..1] « A human language. (Strength=Extensible) Common Languages + » A code that details how this designation would be used use : Coding [0..1] « Details of how a designation would be used. (Strength=Extensible) Designation Use + » The text value for this designation value : string [1..1] ConceptProperty A code that is a reference to CodeSystem.property.code code : code [1..1] The value of this property value[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 filter filter [0..*] A property defines an additional slot through which additional information can be provided about a concept property [0..*] Additional representations for the concept - other languages, aliases, specialized purposes, used for particular purposes, etc designation [0..*] A property value for this concept property [0..*] Defines children of a concept to produce a hierarchy of concepts. The nature of the relationships is variable (is-a/contains/categorizes) - see hierarchyMeaning concept [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 are concept [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 -->
 <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 

{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
  "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/> .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
  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 doco
. . 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)

doco Documentation for this format

UML Diagram ( Legend )

CodeSystem ( DomainResource ) An absolute URL 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}.system url : 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 instance identifier : 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 are orderable. This is used in [Coding]{datatypes.html#Coding}.version version : 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 generation name : string [0..1] A short, descriptive, user-friendly title for the code system title : 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 flag 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 name of the individual or organization that published the code system publisher : string [0..1] Contact details to assist a user in finding and communicating with the publisher contact : ContactDetail [0..*] The date (and optionally time) when the code system was published. The date must change when the business version changes, if it does, and it must change if the status code changes. In addition, it should change when the substantive content of the code system changes date : dateTime [0..1] A free text natural language description of the code system from the consumer's perspective description : 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 of code system definitions useContext : UsageContext [0..*] A jurisdiction in which the code system is intended to be used jurisdiction : CodeableConcept [0..*] « Countries and regions within which this artifact is targeted for use (Strength=Extensible) Jurisdiction ValueSet + » Explains why this code system is needed and why it has been designed as it has purpose : 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 system copyright : markdown [0..1] If code comparison is case sensitive when codes within this system are compared to each other caseSensitive : boolean [0..1] Canonical URL of value set that contains the entire code system valueSet : uri [0..1] The meaning of the heirarchy of concepts hierarchyMeaning : 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 grammar compositional : 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 system versionNeeded : boolean [0..1] How much of the content of the code system - the concepts and codes it defines - are represented in this resource content : 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) concepts count : unsignedInt [0..1] Filter The code that identifies this filter when it is used in the instance code : code [1..1] A description of how or why the filter is used description : string [0..1] A list of operators that can be used with the filter operator : 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 be value : string [1..1] Property A code that is used to identify the property. The code is used internally (in CodeSystem.concept.property.code) and also externally, such as in property filters code : 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 system uri : uri [0..1] A description of the property- why it is defined, and how it's value might be used description : 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 ! » ConceptDefinition A code - a text symbol - that uniquely identifies the concept within the code system code : code [1..1] A human readable string that is the recommended default way to present this concept to a user display : 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 concept definition : string [0..1] Designation The language this designation is defined for language : code [0..1] « A human language. (Strength=Extensible) Common Languages + » A code that details how this designation would be used use : Coding [0..1] « Details of how a designation would be used. (Strength=Extensible) Designation Use + » The text value for this designation value : string [1..1] ConceptProperty A code that is a reference to CodeSystem.property.code code : code [1..1] The value of this property value[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 filter filter [0..*] A property defines an additional slot through which additional information can be provided about a concept property [0..*] Additional representations for the concept - other languages, aliases, specialized purposes, used for particular purposes, etc designation [0..*] A property value for this concept property [0..*] Defines children of a concept to produce a hierarchy of concepts. The nature of the relationships is variable (is-a/contains/categorizes) - see hierarchyMeaning concept [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 are concept [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 -->
 <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 

{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
  "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/> .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
  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 ),

4.11.4.1 Terminology Bindings

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

4.11.4.2 Constraints

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

4.11.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.11.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
  • $infer 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 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.

4.11.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 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):
  • 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#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.

4.11.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 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:

4.11.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.11.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 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:

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

4.11.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.

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