STU 3 Ballot

This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). 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 GroupMaturity Level: 0Compartments: 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 idenifier system, and it's 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 dsscribe 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

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
... url Σ0..1uriGlobally unique logical identifier for code system (Coding.system)
... identifier Σ0..1IdentifierAdditional identifier for the code system (e.g. HL7 v2 / CDA)
... version Σ0..1stringLogical identifier for this version (Coding.version)
... name Σ0..1stringInformal name for this code system
... status ?!Σ1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... publisher Σ0..1stringName of the publisher (organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... date Σ0..1dateTimeDate for given status
... description Σ0..1markdownHuman language description of the code system
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... requirements 0..1markdownWhy needed
... copyright 0..1stringUse 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 | subsumes | 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 | examplar | 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 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. This is used in [Coding]{datatypes.html#Coding}.systemurl : uri [0..1]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]Used to identify this version of the code system when it is referenced in a specification, model, design or instance (e.g. Coding.version). This is an arbitrary value managed by the profile author manually and the value should be a timestamp. This is used in [Coding]{datatypes.html#Coding}.versionversion : string [0..1]A free text natural language name describing the code systemname : string [0..1]The status of the code system (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)ConformanceResourceStatus! »This CodeSystem was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean [0..1]The name of the individual or organization that published the code systempublisher : string [0..1]The date that the code system status was last changed. 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 implementation guide changes (e.g. the 'content logical definition')date : dateTime [0..1]A free text natural language description of the use of the code system - reason for definition, "the semantic space" to be included in the code system, conditions of use, etc. The description may include a list of expected usages for the code system and can also describe the approach taken to build the code systemdescription : 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 definitionsuseContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible)Context of Use ValueSet+ »Explains why this code system is needed and why it has been constrained as it hasrequirements : 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 : string [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 heirarchy 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]ContactThe name of an individual to contact regarding the code systemname : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]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 it's 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 »Contacts to assist a user in finding and communicating with the publishercontact[0..*]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) and can only be determined by examining the definitions of the conceptsconcept[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 Globally unique logical identifier for  code system (Coding.system) -->
 <identifier><!-- 0..1 Identifier Additional identifier for the code system (e.g. HL7 v2 / CDA) --></identifier>
 <version value="[string]"/><!-- 0..1 Logical identifier for this version (Coding.version) -->
 <name value="[string]"/><!-- 0..1 Informal name for this code system -->
 <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..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of an individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <date value="[dateTime]"/><!-- 0..1 Date for given status -->
 <description value="[markdown]"/><!-- 0..1 Human language description of the code system -->
 <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext>
 <requirements value="[markdown]"/><!-- 0..1 Why needed -->
 <copyright value="[string]"/><!-- 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 | subsumes | 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>", // Globally unique logical identifier for  code system (Coding.system)
  "identifier" : { Identifier }, // Additional identifier for the code system (e.g. HL7 v2 / CDA)
  "version" : "<string>", // Logical identifier for this version (Coding.version)
  "name" : "<string>", // Informal name for this code system
  "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" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "date" : "<dateTime>", // Date for given status
  "description" : "<markdown>", // Human language description of the code system
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "requirements" : "<markdown>", // Why needed
  "copyright" : "<string>", // 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 | subsumes | 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 Globally unique logical identifier for  code system (Coding.system)
  fhir:CodeSystem.identifier [ Identifier ]; # 0..1 Additional identifier for the code system (e.g. HL7 v2 / CDA)
  fhir:CodeSystem.version [ string ]; # 0..1 Logical identifier for this version (Coding.version)
  fhir:CodeSystem.name [ string ]; # 0..1 Informal name for this code system
  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 [ # 0..* Contact details of the publisher
    fhir:CodeSystem.contact.name [ string ]; # 0..1 Name of an individual to contact
    fhir:CodeSystem.contact.telecom [ ContactPoint ], ... ; # 0..* Contact details for individual or publisher
  ], ...;
  fhir:CodeSystem.date [ dateTime ]; # 0..1 Date for given status
  fhir:CodeSystem.description [ markdown ]; # 0..1 Human language description of the code system
  fhir:CodeSystem.useContext [ CodeableConcept ], ... ; # 0..* Content intends to support these contexts
  fhir:CodeSystem.requirements [ markdown ]; # 0..1 Why needed
  fhir:CodeSystem.copyright [ string ]; # 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 | subsumes | 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

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
... url Σ0..1uriGlobally unique logical identifier for code system (Coding.system)
... identifier Σ0..1IdentifierAdditional identifier for the code system (e.g. HL7 v2 / CDA)
... version Σ0..1stringLogical identifier for this version (Coding.version)
... name Σ0..1stringInformal name for this code system
... status ?!Σ1..1codedraft | active | retired
ConformanceResourceStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... publisher Σ0..1stringName of the publisher (organization or individual)
... contact Σ0..*BackboneElementContact details of the publisher
.... name Σ0..1stringName of an individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... date Σ0..1dateTimeDate for given status
... description Σ0..1markdownHuman language description of the code system
... useContext Σ0..*CodeableConceptContent intends to support these contexts
Context of Use ValueSet (Extensible)
... requirements 0..1markdownWhy needed
... copyright 0..1stringUse 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 | subsumes | 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 | examplar | 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 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. This is used in [Coding]{datatypes.html#Coding}.systemurl : uri [0..1]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]Used to identify this version of the code system when it is referenced in a specification, model, design or instance (e.g. Coding.version). This is an arbitrary value managed by the profile author manually and the value should be a timestamp. This is used in [Coding]{datatypes.html#Coding}.versionversion : string [0..1]A free text natural language name describing the code systemname : string [0..1]The status of the code system (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)ConformanceResourceStatus! »This CodeSystem was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean [0..1]The name of the individual or organization that published the code systempublisher : string [0..1]The date that the code system status was last changed. 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 implementation guide changes (e.g. the 'content logical definition')date : dateTime [0..1]A free text natural language description of the use of the code system - reason for definition, "the semantic space" to be included in the code system, conditions of use, etc. The description may include a list of expected usages for the code system and can also describe the approach taken to build the code systemdescription : 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 definitionsuseContext : CodeableConcept [0..*] « Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use. (Strength=Extensible)Context of Use ValueSet+ »Explains why this code system is needed and why it has been constrained as it hasrequirements : 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 : string [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 heirarchy 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]ContactThe name of an individual to contact regarding the code systemname : string [0..1]Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint [0..*]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 it's 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 »Contacts to assist a user in finding and communicating with the publishercontact[0..*]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) and can only be determined by examining the definitions of the conceptsconcept[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 Globally unique logical identifier for  code system (Coding.system) -->
 <identifier><!-- 0..1 Identifier Additional identifier for the code system (e.g. HL7 v2 / CDA) --></identifier>
 <version value="[string]"/><!-- 0..1 Logical identifier for this version (Coding.version) -->
 <name value="[string]"/><!-- 0..1 Informal name for this code system -->
 <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..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of an individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <date value="[dateTime]"/><!-- 0..1 Date for given status -->
 <description value="[markdown]"/><!-- 0..1 Human language description of the code system -->
 <useContext><!-- 0..* CodeableConcept Content intends to support these contexts --></useContext>
 <requirements value="[markdown]"/><!-- 0..1 Why needed -->
 <copyright value="[string]"/><!-- 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 | subsumes | 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>", // Globally unique logical identifier for  code system (Coding.system)
  "identifier" : { Identifier }, // Additional identifier for the code system (e.g. HL7 v2 / CDA)
  "version" : "<string>", // Logical identifier for this version (Coding.version)
  "name" : "<string>", // Informal name for this code system
  "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" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of an individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "date" : "<dateTime>", // Date for given status
  "description" : "<markdown>", // Human language description of the code system
  "useContext" : [{ CodeableConcept }], // Content intends to support these contexts
  "requirements" : "<markdown>", // Why needed
  "copyright" : "<string>", // 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 | subsumes | 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 Globally unique logical identifier for  code system (Coding.system)
  fhir:CodeSystem.identifier [ Identifier ]; # 0..1 Additional identifier for the code system (e.g. HL7 v2 / CDA)
  fhir:CodeSystem.version [ string ]; # 0..1 Logical identifier for this version (Coding.version)
  fhir:CodeSystem.name [ string ]; # 0..1 Informal name for this code system
  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 [ # 0..* Contact details of the publisher
    fhir:CodeSystem.contact.name [ string ]; # 0..1 Name of an individual to contact
    fhir:CodeSystem.contact.telecom [ ContactPoint ], ... ; # 0..* Contact details for individual or publisher
  ], ...;
  fhir:CodeSystem.date [ dateTime ]; # 0..1 Date for given status
  fhir:CodeSystem.description [ markdown ]; # 0..1 Human language description of the code system
  fhir:CodeSystem.useContext [ CodeableConcept ], ... ; # 0..* Content intends to support these contexts
  fhir:CodeSystem.requirements [ markdown ]; # 0..1 Why needed
  fhir:CodeSystem.copyright [ string ]; # 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 | subsumes | 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)

4.11.4.1 Terminology Bindings

PathDefinitionTypeReference
CodeSystem.status The lifecycle status of a Value Set or Concept Map.RequiredConformanceResourceStatus
CodeSystem.useContext Indicates the countries, regions, disciplines and other aspects of use within which this artifact is targeted for use.ExtensibleContext of Use 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.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 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.5.1 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.6 Search Parameters

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

NameTypeDescriptionPaths
codetokenA code defined in the code systemCodeSystem.concept.code
contenttokennot-present | examplar | fragment | completeCodeSystem.content
contexttokenA use context assigned to the code systemCodeSystem.useContext
datedateThe code system publication dateCodeSystem.date
descriptionstringText search in the description of the code systemCodeSystem.description
identifiertokenThe identifier for the code systemCodeSystem.identifier
languagetokenA language in which a designation is providedCodeSystem.concept.designation.language
namestringThe name of the code systemCodeSystem.name
publisherstringName of the publisher of the code systemCodeSystem.publisher
statustokenThe status of the code systemCodeSystem.status
systemuriThe system for any codes defined by this code system (same as 'url')CodeSystem.url
urluriThe logical URL for the code systemCodeSystem.url
versiontokenThe version identifier of the code systemCodeSystem.version