Release 5 4

This page is part of the FHIR Specification (v5.0.0: R5 (v4.0.1: R4 - Mixed Normative and STU ). This is the ) in it's permanent home (it will always be available at this URL). The current published version. 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.8 Resource CodeSystem - Content

Terminology Infrastructure Vocabulary Work Group Maturity Level : N   Normative (from v4.0.0) Security Category : Anonymous Compartments : No Not linked to any defined compartments
This page has been approved as part of an ANSI standard. See the Conformance Package for further details.

The CodeSystem resource is used to declare the existence of and describe a code system or code system supplement and its key properties, and optionally define a part or all of its content.

4.8.1 Scope and Usage

The FHIR terminology specification is based on the concepts of code system and value set two key concepts, originally defined in HL7 v3 Core Principles :

  • code system - declares the existence of and describes a code system or code system supplement and its key properties, and optionally defines a part or all of its content. Also known as Ontology, Terminology, or Enumeration
  • value set - specifies a set of codes drawn from one or more code systems, intended for use in a particular context. Value sets link between CodeSystem definitions and their use in coded elements

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

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

  • Identifying URL and version
  • Description, Copyright, publication date, and other metadata
  • Some key properties of the code system itself - e.g. whether it exhibits concept permanence, whether it defines a compositional grammar, and whether the codes that it defines are case sensitive
  • What filters can be used in value sets that use the code system in a ValueSet.compose element
  • What concept properties are 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. Code System resources may also be used to define supplements, which extend an existing code system with additional designations and properties.

The CodeSystem resource is not intended to support the process of maintaining code systems. 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 maintenance systems and distribution formats, and CodeSystem is generally not an efficient way to distribute their content, though it is used as one way of declaring the filters and properties associated with those code systems.

4.8.2 Boundaries and Relationships

  • Code systems are used in ValueSet resources
  • The system element in the Coding (i.e. Coding.system) data type refers to a CodeSystem resource instance resources by its their canonical URL (i.e. CodeSystem.url)
  • The CodeSystem resource design is based, in part, on the code system functionality described in the HL7 CTS 2 specification. A CTS2 server can be used to maintain code systems which are then published using the CodeSystem resource
  • The CodeSystem resource documents the inherent structure and capabilities of code system, whereas the TerminologyCapabilities resource documents what a server hosting the code system is capable of

The CodeSystem resource declares the existence of a code system and its key properties including its preferred identifier. The NamingSystem resource identifies the existence of a code or identifier system, and its possible and preferred identifiers. The key difference between the resources is who creates and manages them - CodeSystem resources are managed by the owner or publisher of the code system, who can properly define the code system features and content. 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 system, but ideally there would be only one authoritative CodeSystem resource (identified by its canonical URL) that is provided by the code system publisher, with multiple copies distributed on additional FHIR servers or elsewhere and used where needed.

Both Code System supplements and Concept Maps may be used to define relationships between concepts in different systems. ConceptMaps are assertions of the relationships between different concepts that are associated with particular contexts of use, while CodeSystem supplements are used to define inherent properties and semantics of the concepts in the code system

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

4.8.3.1 CodeSystem Identification

A code system has three identifiers. The first two can be used to reference the code system in the FHIR context:

  • CodeSystem.id : The logical id on the system that holds the CodeSystem resource instance - this typically is expected to change as the resource moves from server to server. The location URI is constructed by appending the logical id to the server base address where the instance is found and the resource type. This URI should be a resolvable URL by which the resource instance may be retrieved, usually from a FHIR server, and it may be a relative reference typically to the server base URL.
  • CodeSystem.url : The canonical URL that never changes for this code system - it is the same in every copy. The element is named url rather than uri for legacy reasons and to strongly encourage providing a resolvable URL as the identifier whenever possible. This canonical URL is used to refer to all instances of this particular code system across all servers and systems. Ideally, this URI should be a URL which resolves to the location of the master version of the code system, though this is not always possible.

For example, for CodeSystems that are the code systems published as part of the FHIR specification, CodeSystem.url specification all have a location ("literal") URI which is the url URL where the CodeSystem they may be accessed in the FHIR specification. specification itself. However, while a new version of the FHIR specification is being prepared, new code systems that are published in CI build versions the drafts will not be found in the released current FHIR specification version.

Because it is common practice to copy (cache) code systems locally, most references to code systems can use either the canonical URL or the location ("literal") URL.

The third code system identifier is used typically for external references to the code system outside of FHIR:

  • 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 URIs that can be used to reference it - its canonical URL (the url element), and its local location from which it may be retrieved (which includes the id element). Most Because it is common practice to copy (cache) code systems locally, most references to code systems use the canonical URL because it is stable and does not change from one FHIR server instance to another. 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.8.4 References to this Resource Resource References: itself ,

This resource is referenced by Coding , itself, ConceptMap , TerminologyCapabilities and ValueSet Extension References: ValueSet Supplement and ValueSet System Profile References: CQL Library , ELM Library , FHIRPath Library , Logic Library and Module Definition Library

4.8.5 4.8.4 Resource Content

Structure

versionAlgorithmCoding T T T copyrightLabel T TU 0..1 string Copyright holder and year(s) C C C
Name Flags Card. Type Description & Constraints doco
. . CodeSystem I N DomainResource Declares the existence of and describes a code system or code system supplement
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
+ Rule: Within a code system definition, all the codes SHALL be unique
+ Warning: If there is an explicit hierarchy, a hierarchyMeaning should be provided + Warning: If there is an implicit hierarchy, a hierarchyMeaning should be provided + Rule: If the code system content = supplement, it must nominate what it's a supplement for Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension Interfaces Implemented: MetadataResource
. . . url Σ C 0..1 uri Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system) + Warning: URL should not contain | or # - these characters make processing canonical references problematic
. . . identifier Σ 0..* Identifier Additional identifier for the code system (business identifier)
. . . version Σ 0..1 string Business version of the code system (Coding.version)
. . versionAlgorithm[x] . name Σ TU I 0..1 How to compare versions Binding: Version Algorithm ( Extensible ) versionAlgorithmString string Coding name Σ C 0..1 string Name for this code system (computer friendly)
. . . title Σ T 0..1 string Name for this code system (human friendly)
. . . status ?! Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus ( Required )
. . . experimental Σ 0..1 boolean For testing purposes, not real usage
. . . date Σ 0..1 dateTime Date last changed
. . . publisher Σ T 0..1 string Name of the publisher/steward publisher (organization or individual)
. . . contact Σ 0..* ContactDetail Contact details for the publisher
. . . description 0..1 markdown Natural language description of the code system
. . . useContext Σ TU 0..* UsageContext The context that the content is intended to support
. . . jurisdiction Σ XD 0..* CodeableConcept Intended jurisdiction for code system (if applicable)
Binding: Jurisdiction ValueSet ( Extensible )
. . . purpose 0..1 markdown Why this code system is defined
. . . copyright 0..1 markdown Use and/or publishing restrictions
. . . approvalDate TU 0..1 date When the CodeSystem was approved by publisher lastReviewDate TU 0..1 date When the CodeSystem was last reviewed by the publisher effectivePeriod caseSensitive Σ TU 0..1 Period When the CodeSystem is expected to be used topic XD 0..* CodeableConcept E.g. Education, Treatment, Assessment, etc Binding: Definition Topic ( Example ) author TU 0..* ContactDetail Who authored the CodeSystem editor TU 0..* ContactDetail Who edited the CodeSystem reviewer TU 0..* ContactDetail Who reviewed the CodeSystem endorser TU 0..* ContactDetail Who endorsed the CodeSystem relatedArtifact TU 0..* RelatedArtifact Additional documentation, citations, etc caseSensitive Σ 0..1 boolean If code comparison is case sensitive
. . . valueSet Σ 0..1 canonical ( ValueSet ) Canonical reference to the value set with entire code system
. . . hierarchyMeaning Σ C 0..1 code grouped-by | is-a | part-of | classified-with
Binding: Code System Hierarchy Meaning CodeSystemHierarchyMeaning ( Required )
. . . compositional Σ 0..1 boolean If code system defines a compositional grammar
. . . versionNeeded Σ 0..1 boolean If definitions are not stable
. . . content Σ C 1..1 code not-present | example | fragment | complete | supplement
Binding: Code System Content Mode CodeSystemContentMode ( Required )
. . . supplements Σ C TU 0..1 canonical ( CodeSystem ) Canonical URL of Code System this adds designations and properties to
. . . 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 = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | child-of | descendent-leaf | exists
Binding: Filter Operator 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 | decimal
Binding: Property Type 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
+ Rule: Must have a value for concept.designation.use if concept.designation.additionalUse is present
. . . . . language 0..1 code Human language of the designation
Binding: All Languages ( Required ) Additional Bindings Purpose Common Languages Starter Set use C 0..1 Coding Details how this designation would be used Binding: Designation Use ( Extensible Preferred but limited to AllLanguages )
. . . . . additionalUse use C TU 0..* 0..1 Coding Additional ways Details how this designation would be used
Binding: Designation Use ( Extensible )
. . . . . value 1..1 string The text value for this designation
. . . . property 0..* BackboneElement Property value for the concept
. . . . . code C 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
. . . . . . valueDecimal decimal
. . . . concept C 0..* see concept Child Concepts (is-a/contains/categorizes)

doco Documentation for this format
See the Extensions for this resource

UML Diagram ( Legend )

CodeSystem ( DomainResource ) + MetadataResource An absolute URI that is used to identify this code system when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which at which an authoritative instance of this code system is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the code system is stored on different servers. 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..*] The identifier that is used to identify this version of the code system when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the code system author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence. This is used in [Coding](datatypes.html#Coding).version version : string [0..1] Indicates the mechanism used to compare versions to determine which CodeSystem is more current versionAlgorithm[x] : DataType [0..1] « string | Coding ; null (Strength=Extensible) VersionAlgorithm + » 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] « This element has or is affected by some invariants C » 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 date (and optionally time) when the content code system resource was created or revised (this element modifies the meaning of other elements) status : code [1..1] « null The lifecycle status of an artifact. (Strength=Required) PublicationStatus ! » A Boolean value to indicate that this code system is authored for testing purposes (or education/evaluation/marketing) and is not intended to be used for genuine usage experimental : boolean [0..1] The date (and optionally time) when the code system was last significantly changed. published. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the code system changes date : dateTime [0..1] The name of the organization or individual responsible for the release and ongoing maintenance of 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..*] A free text natural language description of the code system from a consumer's perspective description : markdown [0..1] The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate code system instances useContext : UsageContext [0..*] A legal or geographic region in which the code system is intended to be used jurisdiction : CodeableConcept [0..*] « null Countries and regions within which this artifact is targeted for use. (Strength=Extensible) JurisdictionValueSet Jurisdiction ValueSet + » Explanation of 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] A short string (<50 characters), suitable for inclusion in a page footer that identifies the copyright holder, effective period, and optionally whether rights are resctricted. (e.g. 'All rights reserved', 'Some rights reserved') copyrightLabel : string [0..1] The date on which the resource content was approved by the publisher. Approval happens once when the content is officially approved for usage approvalDate : date [0..1] The date on which the resource content was last reviewed. Review happens periodically after approval but does not change the original approval date lastReviewDate : date [0..1] The period during which the CodeSystem content was or is planned to be in active use effectivePeriod : Period [0..1] Descriptions related to the content of the CodeSystem. Topics provide a high-level categorization as well as keywords for the CodeSystem that can be useful for filtering and searching topic : CodeableConcept [0..*] « null (Strength=Example) DefinitionTopic ?? » An individiual or organization primarily involved in the creation and maintenance of the CodeSystem author : ContactDetail [0..*] An individual or organization primarily responsible for internal coherence of the CodeSystem editor : ContactDetail [0..*] An individual or organization asserted by the publisher to be primarily responsible for review of some aspect of the CodeSystem reviewer : ContactDetail [0..*] An individual or organization asserted by the publisher to be responsible for officially endorsing the CodeSystem for use in some setting endorser : ContactDetail [0..*] Related artifacts such as additional documentation, justification, dependencies, bibliographic references, and predecessor and successor artifacts relatedArtifact : RelatedArtifact [0..*] If code comparison is case sensitive when codes within this system are compared to each other caseSensitive : boolean [0..1] Canonical reference to the value set that contains all codes in the entire code system independent of code status valueSet : canonical [0..1] « ValueSet » The meaning of the hierarchy of concepts as represented in this resource hierarchyMeaning : code [0..1] « null The meaning of the hierarchy of concepts in a code system. (Strength=Required) CodeSystemHierarchyMeaning ! » « This element has or is affected by some invariants C » The code system defines a compositional (post-coordination) grammar compositional : boolean [0..1] This flag is used to signify that the code system does not commit to concept permanence across versions. If true, a version must be specified when referencing this code system versionNeeded : boolean [0..1] The extent of the content of the code system (the concepts and codes it defines) are represented in this resource instance content : code [1..1] « null The extent of the content of the code system (the concepts and codes it defines) are represented in a code system resource. (Strength=Required) CodeSystemContentMode ! » « This element has or is affected by some invariants C » The canonical URL of the code system that this code system supplement is adding designations and properties to supplements : canonical [0..1] « CodeSystem » « This element has or is affected by some invariants C » The total number of concepts defined by the code system. Where the code system has a compositional grammar, the basis of this count is defined by the system steward count : unsignedInt [0..1] Filter The code that identifies this filter when it is used as a filter in [ValueSet](valueset.html#).compose.include.filter [[[ValueSet]]].compose.include.filter 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..*] « null 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 its 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 another defined concept) type : code [1..1] « null 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] « This element has or is affected by some invariants C » 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] « null (Strength=Required) A human language. (Strength=Preferred) AllLanguages ! CommonLanguages ? » A code that details how this designation would be used use : Coding [0..1] « null (Strength=Extensible) DesignationUse + » « This element has or is affected by some invariants C » Additional codes that detail Details of how this a designation would be used, if there is more than one use additionalUse : Coding [0..*] « null used. (Strength=Extensible) DesignationUse + » « This element has or is affected by some invariants C » 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] « This element has or is affected by some invariants C » The value of this property value[x] : DataType Type [1..1] « code | Coding | string | integer | boolean | dateTime | decimal » 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 meanings 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 Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system) -->

 <identifier><!-- 0..* Identifier Additional identifier for the code system (business identifier) --></identifier>
 <version value="[string]"/><!-- 0..1 Business version of the code system (Coding.version) -->
 <</versionAlgorithm[x]>
 <

 <name value="[string]"/><!-- ?? 0..1 Name for this code system (computer friendly) -->

 <title value="[string]"/><!-- 0..1 Name for this code system (human friendly) -->
 <

 <status value="[code]"/><!-- 1..1 draft | active | retired | unknown -->

 <experimental value="[boolean]"/><!-- 0..1 For testing purposes, not real usage -->
 <
 <

 <date value="[dateTime]"/><!-- 0..1 Date last changed -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) -->

 <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the code system -->
 <useContext><!-- 0..* UsageContext The context that the content is intended to support --></useContext>
 <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for code system (if applicable) --></jurisdiction>
 <purpose value="[markdown]"/><!-- 0..1 Why this code system is defined -->
 <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions -->
 <
 <
 <
 <</effectivePeriod>
 <</topic>
 <</author>
 <</editor>
 <</reviewer>
 <</endorser>
 <</relatedArtifact>

 <caseSensitive value="[boolean]"/><!-- 0..1 If code comparison is case sensitive -->
 <</valueSet>
 <

 <valueSet><!-- 0..1 canonical(ValueSet) Canonical reference to the value set with entire code system --></valueSet>
 <hierarchyMeaning value="[code]"/><!-- 0..1 grouped-by | is-a | part-of | classified-with -->

 <compositional value="[boolean]"/><!-- 0..1 If code system defines a compositional grammar -->
 <versionNeeded value="[boolean]"/><!-- 0..1 If definitions are not stable -->
 <
 <</supplements>

 <content value="[code]"/><!-- 1..1 not-present | example | fragment | complete | supplement -->
 <supplements><!-- 0..1 canonical(CodeSystem) Canonical URL of Code System this adds designations and properties to --></supplements>

 <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..* = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists -->

  <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 | decimal -->
 </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 -->
   <
   <</use>
   <</additionalUse>

   <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|decimal Value of the property for this concept --></value[x]>
  </property>
  <</concept>

  <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>", // Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system)

  "identifier" : [{ Identifier }], // Additional identifier for the code system (business identifier)
  "version" : "<string>", // Business version of the code system (Coding.version)
  
  ">",
  " },
  "

  "name" : "<string>", // C? Name for this code system (computer friendly)

  "title" : "<string>", // Name for this code system (human friendly)
  "

  "status" : "<code>", // R!  draft | active | retired | unknown

  "experimental" : <boolean>, // For testing purposes, not real usage
  "
  "

  "date" : "<dateTime>", // Date last changed
  "publisher" : "<string>", // Name of the publisher (organization or individual)

  "contact" : [{ ContactDetail }], // Contact details for the publisher
  "description" : "<markdown>", // Natural language description of the code system
  "useContext" : [{ UsageContext }], // The context that the content is intended to support
  "jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for code system (if applicable)
  "purpose" : "<markdown>", // Why this code system is defined
  "copyright" : "<markdown>", // Use and/or publishing restrictions
  "
  "
  "
  "
  "
  "
  "
  "
  "
  "

  "caseSensitive" : <boolean>, // If code comparison is case sensitive
  "
  "

  "valueSet" : { canonical(ValueSet) }, // Canonical reference to the value set with entire code system
  "hierarchyMeaning" : "<code>", // grouped-by | is-a | part-of | classified-with

  "compositional" : <boolean>, // If code system defines a compositional grammar
  "versionNeeded" : <boolean>, // If definitions are not stable
  "
  "

  "content" : "<code>", // R!  not-present | example | fragment | complete | supplement
  "supplements" : { canonical(CodeSystem) }, // Canonical URL of Code System this adds designations and properties to

  "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!  = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists

    "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 | decimal
  }],
  "
    "

  "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 7:
      ">",
      " },
      ">",
      ">,
      ">,
      ">",

      "valueCode" : "<code>"
      "valueCoding" : { Coding }
      "valueString" : "<string>"
      "valueInteger" : <integer>
      "valueBoolean" : <boolean>
      "valueDateTime" : "<dateTime>"

      "valueDecimal" : <decimal>
    }],
    "

    "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:
  fhir:
  fhir:
  # . One of these 2
    fhir: ]
    fhir: ]
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
  ] ... ) ;
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
  ] ... ) ;
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
      fhir:
      fhir:
      fhir:
      fhir:
    ] ... ) ;
    fhir:
      fhir:
      # . One of these 7
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
    ] ... ) ;
    fhir:
  ] ... ) ;

  fhir:CodeSystem.url [ uri ]; # 0..1 Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system)
  fhir:CodeSystem.identifier [ Identifier ], ... ; # 0..* Additional identifier for the code system (business identifier)
  fhir:CodeSystem.version [ string ]; # 0..1 Business version of the code system (Coding.version)
  fhir:CodeSystem.name [ string ]; # 0..1 Name for this code system (computer friendly)
  fhir:CodeSystem.title [ string ]; # 0..1 Name for this code system (human friendly)
  fhir:CodeSystem.status [ code ]; # 1..1 draft | active | retired | unknown
  fhir:CodeSystem.experimental [ boolean ]; # 0..1 For testing purposes, not real usage
  fhir:CodeSystem.date [ dateTime ]; # 0..1 Date last changed
  fhir:CodeSystem.publisher [ string ]; # 0..1 Name of the publisher (organization or individual)
  fhir:CodeSystem.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher
  fhir:CodeSystem.description [ markdown ]; # 0..1 Natural language description of the code system
  fhir:CodeSystem.useContext [ UsageContext ], ... ; # 0..* The context that the content is intended to support
  fhir:CodeSystem.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for code system (if applicable)
  fhir:CodeSystem.purpose [ markdown ]; # 0..1 Why this code system is defined
  fhir:CodeSystem.copyright [ markdown ]; # 0..1 Use and/or publishing restrictions
  fhir:CodeSystem.caseSensitive [ boolean ]; # 0..1 If code comparison is case sensitive
  fhir:CodeSystem.valueSet [ canonical(ValueSet) ]; # 0..1 Canonical reference to the 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 compositional grammar
  fhir:CodeSystem.versionNeeded [ boolean ]; # 0..1 If definitions are not stable
  fhir:CodeSystem.content [ code ]; # 1..1 not-present | example | fragment | complete | supplement
  fhir:CodeSystem.supplements [ canonical(CodeSystem) ]; # 0..1 Canonical URL of Code System this adds designations and properties to
  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..* = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists
    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 | decimal
  ], ...;
  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 7
        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.property.valueDecimal [ decimal ]
    ], ...;
    fhir:CodeSystem.concept.concept [ See CodeSystem.concept ], ... ; # 0..* Child Concepts (is-a/contains/categorizes)
  ], ...;

]

Changes from both R4 and R4B since R3

CodeSystem.copyrightLabel Added Element CodeSystem.topic Added Element
CodeSystem CodeSystem.versionAlgorithm[x] Added Element
CodeSystem.approvalDate CodeSystem.identifier
  • Added Element Max Cardinality changed from 1 to *
CodeSystem.lastReviewDate CodeSystem.status
  • Added Element Change value set from http://hl7.org/fhir/ValueSet/publication-status to http://hl7.org/fhir/ValueSet/publication-status|4.0.1
CodeSystem.effectivePeriod CodeSystem.experimental
  • Added Element No longer marked as Modifier
CodeSystem.author CodeSystem.valueSet
  • Added Element Type changed from uri to canonical(ValueSet)
CodeSystem.editor CodeSystem.hierarchyMeaning
  • Added Element Change value set from http://hl7.org/fhir/ValueSet/codesystem-hierarchy-meaning to http://hl7.org/fhir/ValueSet/codesystem-hierarchy-meaning|4.0.1
CodeSystem.reviewer CodeSystem.content
  • Added Element Change value set from http://hl7.org/fhir/ValueSet/codesystem-content-mode to http://hl7.org/fhir/ValueSet/codesystem-content-mode|4.0.1
CodeSystem.endorser CodeSystem.supplements
  • Added Element
CodeSystem.relatedArtifact CodeSystem.filter.operator
  • Added Element Change value set from http://hl7.org/fhir/ValueSet/filter-operator to http://hl7.org/fhir/ValueSet/filter-operator|4.0.1
CodeSystem.filter.operator CodeSystem.property.type
  • Add codes child-of , descendent-leaf Change value set from http://hl7.org/fhir/ValueSet/concept-property-type to http://hl7.org/fhir/ValueSet/concept-property-type|4.0.1
CodeSystem.concept.designation.language
  • Change binding strength from preferred to required Change value set from Common Languages to All Languages Change max value set from All Languages extensible to none preferred
CodeSystem.concept.designation.additionalUse CodeSystem.concept.property.value[x]
  • Added Element Add Type decimal

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and for R4B as XML or JSON .

See R4 R3 <--> R5 R4 Conversion Maps (status = See Conversions Summary .) 4 tests that all execute ok. All tests pass round-trip testing and 3 r3 resources are invalid (0 errors). )

Structure

versionAlgorithmCoding T T T copyrightLabel T TU 0..1 string Copyright holder and year(s) C C C
Name Flags Card. Type Description & Constraints doco
. . CodeSystem I N DomainResource Declares the existence of and describes a code system or code system supplement
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
+ Rule: Within a code system definition, all the codes SHALL be unique
+ Warning: If there is an explicit hierarchy, a hierarchyMeaning should be provided + Warning: If there is an implicit hierarchy, a hierarchyMeaning should be provided + Rule: If the code system content = supplement, it must nominate what it's a supplement for Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension Interfaces Implemented: MetadataResource
. . . url Σ C 0..1 uri Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system) + Warning: URL should not contain | or # - these characters make processing canonical references problematic
. . . identifier Σ 0..* Identifier Additional identifier for the code system (business identifier)
. . . version Σ 0..1 string Business version of the code system (Coding.version)
. . versionAlgorithm[x] . name Σ TU I 0..1 How to compare versions Binding: Version Algorithm ( Extensible ) versionAlgorithmString string Coding name Σ C 0..1 string Name for this code system (computer friendly)
. . . title Σ T 0..1 string Name for this code system (human friendly)
. . . status ?! Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus ( Required )
. . . experimental Σ 0..1 boolean For testing purposes, not real usage
. . . date Σ 0..1 dateTime Date last changed
. . . publisher Σ T 0..1 string Name of the publisher/steward publisher (organization or individual)
. . . contact Σ 0..* ContactDetail Contact details for the publisher
. . . description 0..1 markdown Natural language description of the code system
. . . useContext Σ TU 0..* UsageContext The context that the content is intended to support
. . . jurisdiction Σ XD 0..* CodeableConcept Intended jurisdiction for code system (if applicable)
Binding: Jurisdiction ValueSet ( Extensible )
. . . purpose 0..1 markdown Why this code system is defined
. . . copyright 0..1 markdown Use and/or publishing restrictions
. . . approvalDate TU 0..1 date When the CodeSystem was approved by publisher lastReviewDate TU 0..1 date When the CodeSystem was last reviewed by the publisher effectivePeriod caseSensitive Σ TU 0..1 Period When the CodeSystem is expected to be used topic XD 0..* CodeableConcept E.g. Education, Treatment, Assessment, etc Binding: Definition Topic ( Example ) author TU 0..* ContactDetail Who authored the CodeSystem editor TU 0..* ContactDetail Who edited the CodeSystem reviewer TU 0..* ContactDetail Who reviewed the CodeSystem endorser TU 0..* ContactDetail Who endorsed the CodeSystem relatedArtifact TU 0..* RelatedArtifact Additional documentation, citations, etc caseSensitive Σ 0..1 boolean If code comparison is case sensitive
. . . valueSet Σ 0..1 canonical ( ValueSet ) Canonical reference to the value set with entire code system
. . . hierarchyMeaning Σ C 0..1 code grouped-by | is-a | part-of | classified-with
Binding: Code System Hierarchy Meaning CodeSystemHierarchyMeaning ( Required )
. . . compositional Σ 0..1 boolean If code system defines a compositional grammar
. . . versionNeeded Σ 0..1 boolean If definitions are not stable
. . . content Σ C 1..1 code not-present | example | fragment | complete | supplement
Binding: Code System Content Mode CodeSystemContentMode ( Required )
. . . supplements Σ C TU 0..1 canonical ( CodeSystem ) Canonical URL of Code System this adds designations and properties to
. . . 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 = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | child-of | descendent-leaf | exists
Binding: Filter Operator 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 | decimal
Binding: Property Type 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
+ Rule: Must have a value for concept.designation.use if concept.designation.additionalUse is present
. . . . . language 0..1 code Human language of the designation
Binding: All Languages ( Required ) Additional Bindings Purpose Common Languages Starter Set use C 0..1 Coding Details how this designation would be used Binding: Designation Use ( Extensible Preferred but limited to AllLanguages )
. . . . . additionalUse use C TU 0..* 0..1 Coding Additional ways Details how this designation would be used
Binding: Designation Use ( Extensible )
. . . . . value 1..1 string The text value for this designation
. . . . property 0..* BackboneElement Property value for the concept
. . . . . code C 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
. . . . . . valueDecimal decimal
. . . . concept C 0..* see concept Child Concepts (is-a/contains/categorizes)

doco Documentation for this format
See the Extensions for this resource

UML Diagram ( Legend )

CodeSystem ( DomainResource ) + MetadataResource An absolute URI that is used to identify this code system when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which at which an authoritative instance of this code system is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the code system is stored on different servers. 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..*] The identifier that is used to identify this version of the code system when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the code system author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequence. This is used in [Coding](datatypes.html#Coding).version version : string [0..1] Indicates the mechanism used to compare versions to determine which CodeSystem is more current versionAlgorithm[x] : DataType [0..1] « string | Coding ; null (Strength=Extensible) VersionAlgorithm + » 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] « This element has or is affected by some invariants C » 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 date (and optionally time) when the content code system resource was created or revised (this element modifies the meaning of other elements) status : code [1..1] « null The lifecycle status of an artifact. (Strength=Required) PublicationStatus ! » A Boolean value to indicate that this code system is authored for testing purposes (or education/evaluation/marketing) and is not intended to be used for genuine usage experimental : boolean [0..1] The date (and optionally time) when the code system was last significantly changed. published. The date must change when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the code system changes date : dateTime [0..1] The name of the organization or individual responsible for the release and ongoing maintenance of 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..*] A free text natural language description of the code system from a consumer's perspective description : markdown [0..1] The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate code system instances useContext : UsageContext [0..*] A legal or geographic region in which the code system is intended to be used jurisdiction : CodeableConcept [0..*] « null Countries and regions within which this artifact is targeted for use. (Strength=Extensible) JurisdictionValueSet Jurisdiction ValueSet + » Explanation of 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] A short string (<50 characters), suitable for inclusion in a page footer that identifies the copyright holder, effective period, and optionally whether rights are resctricted. (e.g. 'All rights reserved', 'Some rights reserved') copyrightLabel : string [0..1] The date on which the resource content was approved by the publisher. Approval happens once when the content is officially approved for usage approvalDate : date [0..1] The date on which the resource content was last reviewed. Review happens periodically after approval but does not change the original approval date lastReviewDate : date [0..1] The period during which the CodeSystem content was or is planned to be in active use effectivePeriod : Period [0..1] Descriptions related to the content of the CodeSystem. Topics provide a high-level categorization as well as keywords for the CodeSystem that can be useful for filtering and searching topic : CodeableConcept [0..*] « null (Strength=Example) DefinitionTopic ?? » An individiual or organization primarily involved in the creation and maintenance of the CodeSystem author : ContactDetail [0..*] An individual or organization primarily responsible for internal coherence of the CodeSystem editor : ContactDetail [0..*] An individual or organization asserted by the publisher to be primarily responsible for review of some aspect of the CodeSystem reviewer : ContactDetail [0..*] An individual or organization asserted by the publisher to be responsible for officially endorsing the CodeSystem for use in some setting endorser : ContactDetail [0..*] Related artifacts such as additional documentation, justification, dependencies, bibliographic references, and predecessor and successor artifacts relatedArtifact : RelatedArtifact [0..*] If code comparison is case sensitive when codes within this system are compared to each other caseSensitive : boolean [0..1] Canonical reference to the value set that contains all codes in the entire code system independent of code status valueSet : canonical [0..1] « ValueSet » The meaning of the hierarchy of concepts as represented in this resource hierarchyMeaning : code [0..1] « null The meaning of the hierarchy of concepts in a code system. (Strength=Required) CodeSystemHierarchyMeaning ! » « This element has or is affected by some invariants C » The code system defines a compositional (post-coordination) grammar compositional : boolean [0..1] This flag is used to signify that the code system does not commit to concept permanence across versions. If true, a version must be specified when referencing this code system versionNeeded : boolean [0..1] The extent of the content of the code system (the concepts and codes it defines) are represented in this resource instance content : code [1..1] « null The extent of the content of the code system (the concepts and codes it defines) are represented in a code system resource. (Strength=Required) CodeSystemContentMode ! » « This element has or is affected by some invariants C » The canonical URL of the code system that this code system supplement is adding designations and properties to supplements : canonical [0..1] « CodeSystem » « This element has or is affected by some invariants C » The total number of concepts defined by the code system. Where the code system has a compositional grammar, the basis of this count is defined by the system steward count : unsignedInt [0..1] Filter The code that identifies this filter when it is used as a filter in [ValueSet](valueset.html#).compose.include.filter [[[ValueSet]]].compose.include.filter 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..*] « null 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 its 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 another defined concept) type : code [1..1] « null 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] « This element has or is affected by some invariants C » 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] « null (Strength=Required) A human language. (Strength=Preferred) AllLanguages ! CommonLanguages ? » A code that details how this designation would be used use : Coding [0..1] « null (Strength=Extensible) DesignationUse + » « This element has or is affected by some invariants C » Additional codes that detail Details of how this a designation would be used, if there is more than one use additionalUse : Coding [0..*] « null used. (Strength=Extensible) DesignationUse + » « This element has or is affected by some invariants C » 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] « This element has or is affected by some invariants C » The value of this property value[x] : DataType Type [1..1] « code | Coding | string | integer | boolean | dateTime | decimal » 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 meanings 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 Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system) -->

 <identifier><!-- 0..* Identifier Additional identifier for the code system (business identifier) --></identifier>
 <version value="[string]"/><!-- 0..1 Business version of the code system (Coding.version) -->
 <</versionAlgorithm[x]>
 <

 <name value="[string]"/><!-- ?? 0..1 Name for this code system (computer friendly) -->

 <title value="[string]"/><!-- 0..1 Name for this code system (human friendly) -->
 <

 <status value="[code]"/><!-- 1..1 draft | active | retired | unknown -->

 <experimental value="[boolean]"/><!-- 0..1 For testing purposes, not real usage -->
 <
 <

 <date value="[dateTime]"/><!-- 0..1 Date last changed -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) -->

 <contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
 <description value="[markdown]"/><!-- 0..1 Natural language description of the code system -->
 <useContext><!-- 0..* UsageContext The context that the content is intended to support --></useContext>
 <jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for code system (if applicable) --></jurisdiction>
 <purpose value="[markdown]"/><!-- 0..1 Why this code system is defined -->
 <copyright value="[markdown]"/><!-- 0..1 Use and/or publishing restrictions -->
 <
 <
 <
 <</effectivePeriod>
 <</topic>
 <</author>
 <</editor>
 <</reviewer>
 <</endorser>
 <</relatedArtifact>

 <caseSensitive value="[boolean]"/><!-- 0..1 If code comparison is case sensitive -->
 <</valueSet>
 <

 <valueSet><!-- 0..1 canonical(ValueSet) Canonical reference to the value set with entire code system --></valueSet>
 <hierarchyMeaning value="[code]"/><!-- 0..1 grouped-by | is-a | part-of | classified-with -->

 <compositional value="[boolean]"/><!-- 0..1 If code system defines a compositional grammar -->
 <versionNeeded value="[boolean]"/><!-- 0..1 If definitions are not stable -->
 <
 <</supplements>

 <content value="[code]"/><!-- 1..1 not-present | example | fragment | complete | supplement -->
 <supplements><!-- 0..1 canonical(CodeSystem) Canonical URL of Code System this adds designations and properties to --></supplements>

 <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..* = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists -->

  <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 | decimal -->
 </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 -->
   <
   <</use>
   <</additionalUse>

   <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|decimal Value of the property for this concept --></value[x]>
  </property>
  <</concept>

  <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>", // Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system)

  "identifier" : [{ Identifier }], // Additional identifier for the code system (business identifier)
  "version" : "<string>", // Business version of the code system (Coding.version)
  
  ">",
  " },
  "

  "name" : "<string>", // C? Name for this code system (computer friendly)

  "title" : "<string>", // Name for this code system (human friendly)
  "

  "status" : "<code>", // R!  draft | active | retired | unknown

  "experimental" : <boolean>, // For testing purposes, not real usage
  "
  "

  "date" : "<dateTime>", // Date last changed
  "publisher" : "<string>", // Name of the publisher (organization or individual)

  "contact" : [{ ContactDetail }], // Contact details for the publisher
  "description" : "<markdown>", // Natural language description of the code system
  "useContext" : [{ UsageContext }], // The context that the content is intended to support
  "jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for code system (if applicable)
  "purpose" : "<markdown>", // Why this code system is defined
  "copyright" : "<markdown>", // Use and/or publishing restrictions
  "
  "
  "
  "
  "
  "
  "
  "
  "
  "

  "caseSensitive" : <boolean>, // If code comparison is case sensitive
  "
  "

  "valueSet" : { canonical(ValueSet) }, // Canonical reference to the value set with entire code system
  "hierarchyMeaning" : "<code>", // grouped-by | is-a | part-of | classified-with

  "compositional" : <boolean>, // If code system defines a compositional grammar
  "versionNeeded" : <boolean>, // If definitions are not stable
  "
  "

  "content" : "<code>", // R!  not-present | example | fragment | complete | supplement
  "supplements" : { canonical(CodeSystem) }, // Canonical URL of Code System this adds designations and properties to

  "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!  = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists

    "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 | decimal
  }],
  "
    "

  "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 7:
      ">",
      " },
      ">",
      ">,
      ">,
      ">",

      "valueCode" : "<code>"
      "valueCoding" : { Coding }
      "valueString" : "<string>"
      "valueInteger" : <integer>
      "valueBoolean" : <boolean>
      "valueDateTime" : "<dateTime>"

      "valueDecimal" : <decimal>
    }],
    "

    "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:
  fhir:
  fhir:
  # . One of these 2
    fhir: ]
    fhir: ]
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
  ] ... ) ;
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
  ] ... ) ;
  fhir:
    fhir:
    fhir:
    fhir:
    fhir:
      fhir:
      fhir:
      fhir:
      fhir:
    ] ... ) ;
    fhir:
      fhir:
      # . One of these 7
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
        fhir: ]
    ] ... ) ;
    fhir:
  ] ... ) ;

  fhir:CodeSystem.url [ uri ]; # 0..1 Canonical identifier for this code system, represented as a URI (globally unique) (Coding.system)
  fhir:CodeSystem.identifier [ Identifier ], ... ; # 0..* Additional identifier for the code system (business identifier)
  fhir:CodeSystem.version [ string ]; # 0..1 Business version of the code system (Coding.version)
  fhir:CodeSystem.name [ string ]; # 0..1 Name for this code system (computer friendly)
  fhir:CodeSystem.title [ string ]; # 0..1 Name for this code system (human friendly)
  fhir:CodeSystem.status [ code ]; # 1..1 draft | active | retired | unknown
  fhir:CodeSystem.experimental [ boolean ]; # 0..1 For testing purposes, not real usage
  fhir:CodeSystem.date [ dateTime ]; # 0..1 Date last changed
  fhir:CodeSystem.publisher [ string ]; # 0..1 Name of the publisher (organization or individual)
  fhir:CodeSystem.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher
  fhir:CodeSystem.description [ markdown ]; # 0..1 Natural language description of the code system
  fhir:CodeSystem.useContext [ UsageContext ], ... ; # 0..* The context that the content is intended to support
  fhir:CodeSystem.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for code system (if applicable)
  fhir:CodeSystem.purpose [ markdown ]; # 0..1 Why this code system is defined
  fhir:CodeSystem.copyright [ markdown ]; # 0..1 Use and/or publishing restrictions
  fhir:CodeSystem.caseSensitive [ boolean ]; # 0..1 If code comparison is case sensitive
  fhir:CodeSystem.valueSet [ canonical(ValueSet) ]; # 0..1 Canonical reference to the 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 compositional grammar
  fhir:CodeSystem.versionNeeded [ boolean ]; # 0..1 If definitions are not stable
  fhir:CodeSystem.content [ code ]; # 1..1 not-present | example | fragment | complete | supplement
  fhir:CodeSystem.supplements [ canonical(CodeSystem) ]; # 0..1 Canonical URL of Code System this adds designations and properties to
  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..* = | is-a | descendent-of | is-not-a | regex | in | not-in | generalizes | exists
    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 | decimal
  ], ...;
  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 7
        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.property.valueDecimal [ decimal ]
    ], ...;
    fhir:CodeSystem.concept.concept [ See CodeSystem.concept ], ... ; # 0..* Child Concepts (is-a/contains/categorizes)
  ], ...;

]

Changes from both R4 and R4B since Release 3

CodeSystem.versionAlgorithm[x] CodeSystem.copyrightLabel Added Element CodeSystem.approvalDate Added Element
CodeSystem Added Element
CodeSystem.lastReviewDate CodeSystem.identifier
  • Added Element Max Cardinality changed from 1 to *
CodeSystem.effectivePeriod CodeSystem.status
  • Added Element Change value set from http://hl7.org/fhir/ValueSet/publication-status to http://hl7.org/fhir/ValueSet/publication-status|4.0.1
CodeSystem.topic CodeSystem.experimental
  • Added Element No longer marked as Modifier
CodeSystem.author CodeSystem.valueSet
  • Added Element Type changed from uri to canonical(ValueSet)
CodeSystem.editor CodeSystem.hierarchyMeaning
  • Added Element Change value set from http://hl7.org/fhir/ValueSet/codesystem-hierarchy-meaning to http://hl7.org/fhir/ValueSet/codesystem-hierarchy-meaning|4.0.1
CodeSystem.reviewer CodeSystem.content
  • Added Element Change value set from http://hl7.org/fhir/ValueSet/codesystem-content-mode to http://hl7.org/fhir/ValueSet/codesystem-content-mode|4.0.1
CodeSystem.endorser CodeSystem.supplements
  • Added Element
CodeSystem.relatedArtifact CodeSystem.filter.operator
  • Added Element Change value set from http://hl7.org/fhir/ValueSet/filter-operator to http://hl7.org/fhir/ValueSet/filter-operator|4.0.1
CodeSystem.filter.operator CodeSystem.property.type
  • Add codes child-of , descendent-leaf Change value set from http://hl7.org/fhir/ValueSet/concept-property-type to http://hl7.org/fhir/ValueSet/concept-property-type|4.0.1
CodeSystem.concept.designation.language
  • Change binding strength from preferred to required Change value set from Common Languages to All Languages Change max value set from All Languages extensible to none preferred
CodeSystem.concept.designation.additionalUse CodeSystem.concept.property.value[x]
  • Added Element Add Type decimal

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and for R4B as XML or JSON .

See R4 R3 <--> R5 R4 Conversion Maps (status = See Conversions Summary .) 4 tests that all execute ok. All tests pass round-trip testing and 3 r3 resources are invalid (0 errors). )

 

Additional See the Profiles & Extensions and the alternate definitions: Master Definition XML + JSON , XML Schema / Schematron + JSON Schema , ShEx (for Turtle ) , + see the spreadsheet version extensions & the dependency analysis

4.8.5.1 4.8.4.1 Terminology Bindings

CodeSystem.versionAlgorithm[x] VersionAlgorithm Extensible Indicates the mechanism used to compare versions to determine which is more current. CodeSystem.topic CodeSystem.concept.designation.language AllLanguages (a valid code from Tags for the Identification   Common Languages starter
Path ValueSet Definition Type Documentation Reference
CodeSystem.status PublicationStatus Required The lifecycle status of an artifact. CodeSystem.jurisdiction JurisdictionValueSet Extensible Required This value set defines a base set of codes for country, country subdivision and region for indicating where a resource is intended to be used. Note: The codes for countries and country subdivisions are taken from ISO 3166 PublicationStatus while the codes for "supra-national" regions are from UN Standard country or area codes for statistical use (M49) .
CodeSystem.jurisdiction DefinitionTopic Countries and regions within which this artifact is targeted for use. Example Extensible High-level categorization of the definition, used for searching, sorting, and filtering. Jurisdiction ValueSet
CodeSystem.hierarchyMeaning CodeSystemHierarchyMeaning Required The meaning of the hierarchy of concepts in a code system. CodeSystem.content CodeSystemContentMode Required CodeSystemHierarchyMeaning
CodeSystem.content The extent of the content of the code system (the concepts and codes it defines) are represented in a code system resource. CodeSystem.filter.operator FilterOperator Required CodeSystemContentMode
CodeSystem.filter.operator The kind of operation to perform as a part of a property based filter. CodeSystem.property.type PropertyType Required The type of a property value. FilterOperator
CodeSystem.property.type The type of Languages ) a property value. Required This value set includes all possible codes from BCP-47 (see http://tools.ietf.org/html/bcp47) PropertyType
CodeSystem.concept.designation.language A human language. Preferred , but limited to AllLanguages CommonLanguages
CodeSystem.concept.designation.use DesignationUse Extensible Details of how a designation would be used CodeSystem.concept.designation.additionalUse DesignationUse used. Extensible Details of how a designation would be used DesignationUse

4.8.5.2 4.8.4.2 Constraints

UniqueKey id Level Location Description Expression
 cnl-0 csd-0 Warning (base) Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$') name.matches('[A-Z]([A-Za-z0-9_]){0,254}')
 csd-1 csd-1 Rule (base) Within a code system definition, all the codes SHALL be unique concept.exists() implies concept.code.combine(%resource.concept.descendants().concept.code).isDistinct()  cnl-1 Warning CodeSystem.url URL should not contain | or # - these characters make processing canonical references problematic exists() implies matches('^[^|# ]+$')  csd-2 Warning (base) If there is an explicit hierarchy, a hierarchyMeaning should be provided concept.concept.exists() implies hierarchyMeaning.exists()  csd-3 Warning (base) If there is an implicit hierarchy, a hierarchyMeaning should be provided concept.where(property.code = 'parent' or property.code = 'child').exists() implies hierarchyMeaning.exists()  csd-4 Rule (base) If the code system content = supplement, it must nominate what it's a supplement for CodeSystem.content = 'supplement' implies CodeSystem.supplements.exists()  csd-5 Rule CodeSystem.concept.designation Must have a value for concept.designation.use if concept.designation.additionalUse is present additionalUse.exists() implies use.exists() concept.code.combine($this.descendants().concept.code).isDistinct()

4.8.6 4.8.5 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, version identifier, though HL7 recommends a date-based approach, or sem-ver . approach.

When the CodeSystem.versionNeeded is 'true', then the CodeSystem.version value 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.8.7 4.8.6 Multi-part Code Systems

The simple case for a code system is that the entire code system - all the concepts and their codes, designations and properties are distributed in a single CodeSystem resource. However, for a variety of reasons, code systems may be distributed by the code system authority in a set of fragments, and other authorities may issue additional designations and properties in supplements.

4.8.8 4.8.7 Code System Fragments

If the CodeSystem.content value is fragment , then the resource describes part of a code system.

Code Systems may be distributed in fragments for the following reasons:

  • Different IP distribution rules for different parts of the code system
  • Special purpose modules for specific purposes
  • Distribution of proposed content for evaluation

The following rules apply to code system fragments:

  • All fragments SHALL have the same CodeSystem.url
  • Fragments can only be published by the code system authority, or according to a process defined by the authority, if they have defined one
  • Fragments cannot contain any codes, concepts or properties that would not be found in a complete representation of the code system, if one exists. Implementers should note that a "complete representation" of the code system might not exist in a single authoritative publication (e.g., SNOMED International with all modules/extensions) exists
  • Publishing a code system in multiple fragments can create confusion for terminology servers and terminology service consumers. Code System authorities that publish fragments should be careful and communicate their intent clearly

4.8.9 4.8.8 Code System Supplements Trial Use

If the CodeSystem.content value is supplement , then the resource describes a code system supplement. The following rules apply to code system supplements:

  • The CodeSystem.supplements element SHALL have a value, which is the URL of the code system being supplemented
  • The CodeSystem.url for a supplement SHALL never appear in a Coding.system
  • The CodeSystem.url for a supplement must be under the control of the authority creating or publishing the supplement (e.g. not in the same space as the code system being supplemented, unless the supplement is being issued by the same authority as the original code system
  • A codesystem supplement cannot define any new CodeSystem.concept.code. i.e.: all CodeSystem.concept.code in the supplement must be a code from the "supplemented" code system

If a supplement needs to define new concepts/codes to use as property values, it can be paired with a new (possibly contained) Code System and use the Coding type for the property values.

The impact of Code System supplements on value set expansion - and therefore value set validation - is subject to ongoing experimentation and implementation testing, and further clarification and additional rules might be proposed in future versions of this specification.

4.8.10 4.8.9 Display, Definition and Designations

Concepts have both a display and a definition . The display is a short text that represents the meaning of the concept to human users, while the definition is a more formal statement of the meaning of the concept, which is often longer. All concepts SHOULD have a display and a definition , though it is not mandatory because there are many cases where no such properties are provided, in spite of their utility and importance for clear and safe communication.

In addition to the display and definition, a concept can have one or more designation elements. The display is equivalent to a special designation with an implied designation.use meaning "primary code/designation" and a language equal to the Resource Language . The designations can provide additional displays for other language, as well as designations for other purposes. When using concepts, applications use the display and designation unless the language or usage in context provides a reason to use one of the designations.

4.8.11 4.8.10 Concept Properties

Each code system can define one or more concept properties. Each concept defined by the code system may have one or more values for each concept property defined by the code system. Typical uses for properties include:

  • Tracking administrative status (inactive, deprecation date)
  • Providing additional statements about the meaning of the concept
  • Defining structured relationships with other concepts in the code system
  • Assigning scoring values to the concepts

Properties are identified by their master URI ( CodeSystem.property.uri ), and then, by their code ( CodeSystem.property.code ), which is used both internally within the code system resource ( CodeSystem.concept.property.code ) and also externally, in the following places:

  • ConceptMap : ConceptMap.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
  • $find-matches 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, in the places shown in the list immediately above this table
uri optional uri Reference to the formal meaning of the property. One possible source of meaning is the Concept Properties code system. This part of the definition is optional, but is recommended to provide an additional level of definitional consistency
description optional string A description of the property- why it is defined, and how its value might be used
type code | Coding | string | integer | boolean | dateTime The type of the property value. Properties of type "code" contain a code defined by the code system (e.g. a reference to another 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.8.12 4.8.11 Defined Concept Properties Status

Many Code Systems have a 'status' associated with the concept. This may categorize the concept as:

  • Experimental - provided for trial, but may be removed in the future
  • Active - in normal use
  • Deprecated - planned to be removed from use
  • Retired - still present for historical reasons, but no longer allowed to be used

There is wide variation in the life cycles supported by the different code systems, 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 also be labeled as "Abstract' (not to be used in some circumstances), and have dates associated with their retirement or deprecation. All this information is represented as properties of the concepts. In order to assist with consistency between code systems, the following basic property URIs are defined in the Concept Properties code system: defined:

http://hl7.org/fhir/concept-properties#status : code A property that indicates the status of the concept. If the property is identified by this URL, then it SHALL use at least these status values (where appropriate):
  • active - the concept is for normal use
  • experimental - provided for trial, but may be removed in the future
  • deprecated - the concept is outdated and planned to be withdrawn removed from use
  • retired - still present for historical reasons, but no longer allowed to be used
http://hl7.org/fhir/concept-properties#inactive : boolean True if the concept is not considered active - e.g. not a valid concept any more. Property type is boolean, default value is false http://hl7.org/fhir/concept-properties#effectiveDate : date The date at which HL7 defined code systems (whether defined by the concept status was last changed FHIR project, the V3 framework, or the V2 standard) all use this property to define their status. HL7 uses "active" (and considers this the default status), and deprecated and retired (= inactive)
http://hl7.org/fhir/concept-properties#deprecationDate http://hl7.org/fhir/concept-properties#retirementDate : date Date Concept was deprecated retired
http://hl7.org/fhir/concept-properties#retirementDate http://hl7.org/fhir/concept-properties#deprecationDate : date Date Concept was retired http://hl7.org/fhir/concept-properties#notSelectable : boolean This concept is a grouping concept and not intended to be used in the normal use of the code system (though may be used for filters etc.). This is also known as 'Abstract' deprecated
http://hl7.org/fhir/concept-properties#parent : code An immediate parent of the concept in the hierarchy
http://hl7.org/fhir/concept-properties#child : code An immediate child of the concept in the hierarchy
http://hl7.org/fhir/concept-properties#partOf http://hl7.org/fhir/concept-properties#notSelectable : code boolean The concept identified in this property (by its code) contains this This concept as is a component http://hl7.org/fhir/concept-properties#synonym : code This property contains an alternative code that may be used to identify this grouping concept instead of the primary code http://hl7.org/fhir/concept-properties#comment : code A string that provides additional detail pertinent and not intended to be used in the normal use or understanding of the concept http://hl7.org/fhir/concept-properties#itemWeight : decimal A numeric value that allows the comparison (less than, greater than) or other numerical manipulation of a concept (e.g. Adding up components of a score). Scores are usually a whole number, but occasionally decimals are encountered in scores code system (though may be used for filters etc.). This is also known as 'Abstract'

Code System representations SHOULD use these properties where possible. The parent and child properties are used when performing concept lookup (using the $lookup operation), and when using properties to indicate parent/child relationships (see below).

4.8.12.1 Concept Status Many Code Systems have a 'status' associated with the concept. This may categorize the concept as: Experimental - provided for trial, but may be removed in the future Active - in normal use Deprecated - planned to be removed from use Retired - still present for historical reasons, but no longer allowed to be used There is wide variation in the life cycles supported by the different code systems and the words they use to describe the various status values they use, and some code systems have additional status values. HL7 uses Active, Deprecated and Retired. These ideas overlap with setting the concept to 'inactive'. In addition, concepts have dates associated with their retirement or deprecation and some code systems imply the status by providing dates. In addition to these status codes, concepts may also be labeled 'notSelectable' (aka 'Abstract'), which means "not to be used in some circumstances", though the exact circumstances need to be clarified somewhere. This is sometimes also considered a status, though it's usually dependent on the context of use (e.g. set in a ValueSet).

4.8.13 4.8.12 Concept Hierarchy

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

Some code systems define concepts that have multiple parents. If a code system hierarchy is represented using properties has concepts like this (typically, concepts that are subsumed by more than one other concept), nested concepts the code system SHOULD NOT be used to represent any parts of represented using the hierarchy structure in the Code System resource; resource, and the relationships between concepts should be defined using properties . If the hierarchy is used, implementers SHALL use a property to indicate additional parents that are not represented in the structural (nested concepts) hierarchy.

Operations based on the codeSystem resource SHALL have the same result whether or not the relationships are represented explicitly as properties or implicitly using the CodeSystem resource hierarchy.

4.8.14 4.8.13 Subsumption Testing

The words 'subsume', 'subsumes', 'subsumed' and 'subsumption' are defined in relation to the type of hierarchy (i.e. the value of CodeSystem.hierarchyMeaning ) identified for the code system that is being represented by the CodeSystem resource. Concept A is considered to be subsumed by Concept B if it comes under Concept B in the hierarchy, or if a parent/child relationship is declared in the properties, and the hierarchyMeaning is "is-a").

Where a CodeSystem does not declare its hierarchy meaning directly, then the code system documentation must be consulted manually to determine how subsumption is determined. If there is no definition, none of the subsumption based features can be used with the code system.

Subsumption based logic arises explicitly or implicitly in the following places in the FHIR specification:

4.8.15 4.8.14 Filters

The following filters are defined for all code systems:

[property] regex [string] Includes all codes that have a property value matching the specified regex [property] exists true or false When value is "true", includes all codes that have
Property Name Operation Value Definition Notes
code regex [string] Matches any concept with the code matching the supplied string The regex flavor is determined by the server [property] = [string] Includes all codes that have a property value equal to the specified string, where [property] is the code for any defined property . Where the type of the property is on of integer , dateTime or decimal , the FHIR search prefixes and semantics apply (see below)
[property] in [string,string...] Includes all codes that have a property value equal to one of the specified strings, where [property] is the code for any defined property The values cannot include ",", since it is being used as a delimiter

This draft section about the specified property. When value relationships between rich terminologies and structured content is "false", includes all codes that lack the specified property still undergoing review.

designation = [string] Matches any concept with a designation equal to the supplied string Designations considered include the concept.display, which counts as a designation designation regex [string] Matches any concept with a designation matching the supplied string Designations considered include

4.8.15 Implicit Code Systems

Some other parts of the concept.display, which counts FHIR infrastructure define set of concepts that may also be treated as a designation The following filters are defined for all code systems that support "is-a" relationships systems. This is most useful when mapping between concepts. (The filters can systems using Concept Maps , but might also be used regardless of whether the "is-a" relationships are conveyed as concept properties or useful for other code system related functionality (e.g. subsetting use Value Sets ). This table summarizes how to treat these items as concept nesting): a terminology:

Property Name Operation Value Definition Notes concept is-a concept child-of [string] concept
[string] concept code StructureDefinition Includes all concept ids that have a transitive is-a relationship with The StructureDefinition.url (canonical URL) is the concept Id provided as system . Each .snapshot.element.id in the value, including snapshot is a code in the provided concept itself (include descendant codes and self). code system
concept descendent-of [string] concept code Questionnaire Includes all concept ids that have a transitive is-a relationship with the concept Id provided as The Questionnaire.url (canonical URL) is the value, excluding system . Each .item.linkId in the provided concept itself (i.e. include descendant codes only). concept is-not-a [string] concept snapshot is a code The specified property of in the code does not have an is-a relationship system. Items with the provided value. no linkId cannot be addressed
concept generalizes [string] concept code Medication Includes all concept ids that Medication resources are a bit different, since they don't have a transitive is-a relationship from canonical URL, and there are not multiple items in a resource. So to refer to a medication resource, the concept system is [base]/Medication, where base is the server address. The Logical Id provided as of the value, including resource is the provided concept itself (i.e. include ancestor codes and self). code

The use of these implicit code Only concepts with a direct hierarchical systems is not yet well tested, so this section remains informative.

For medications, the relationship to between the index code system and no other concepts. This does not include the index medication resource is complex. Many medication related code in the output. concept descendent-leaf [string] concept systems (e.g. RxNorm, DM+D, AMT, etc.) represent more complex information than just code, display name and code Includes concept ids that have a transitive is-a relationship with system. These often contain information about the concept Id provided as content of the value, but medication A similar principle applies to observation definitions, which do not have any concept ids with transitive is-a relationships overlap significantly with themselves. 4.8.15.1 FHIR Search Semantics LOINC and other related code systems, which contain a set of observation definitions, that contain methods, units, etc. Other similar arrangements exist for Location and many other kinds of resource.

If In FHIR, these are handled by splitting the concept into two distinct parts - the Terminology, ( Code System & = ValueSet filter resources) is used with a property that is defined on to manage the CodeSystem, codes, display names and if the property has a type of integer , dateTime relationships. A separate "detail" resource (e.g., Medication resource instances for RxNorm code details, ObservationDefinition instances for LOINC code details, or decimal , then the FHIR search rules apply. This means that the following prefixes may be Location , etc.) is used in the value to convey detailed information (dose form & strength, allowed data type or permitted values, address & hours of the filter: operation, etc.). One "detail" resource instance is created for each code.

This division accomplishes several things:

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

Note that this division in FHIR does not imply that a value for the property on the code and it similar division is less or equal 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 provided value sa : discrete resource instances or only the code has a value for the property on set).

The linkage between the code "detail" resource and it is starts after the provided value eb : Terminology resources is accomplished via the code has a value for the property element (or equivalent) on the code and it is ends before detail resource. As well, the provided value ap : "name" or "title" on the code has a value for detail resource generally corresponds with the property display name on the code and it is approximately the same matching code. Most detail resources will also have an "identifier" element. This can be set to the provided same value The semantics of prefixes are and namespace as explained on the search page with regard to precision and range considerations, particularly on dates and decimals. Note that eq is not redundant - in it's absence, code, but if the semantics are for a direct string match, not only identifier a smart match as defined by resource has is its defining code, it may be better to omit the search semantics. Some Examples: { "property": "retiredDate", "operator": "=", "value": "lt2021-01-01" } Any code that was retired before 2021. Regarding precision: { "property": "retiredDate", "operator": "=", "value": "eq2022" } would match a concept with a retiredDate of 2022-09-12. However: { "property": "retiredDate", "operator": "=", "value": "2022" } would not match a concept with a retiredDate of 2022-09-12. identifier entirely. .

4.8.16 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource , and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name Type Description Expression In Common
code TU token A code defined in the code system CodeSystem.concept.code
content-mode TU token not-present | example | fragment | complete | supplement CodeSystem.content
context TU token A use context assigned to the code system (CodeSystem.useContext.value.ofType(CodeableConcept)) (CodeSystem.useContext.value as CodeableConcept) 30 Resources
context-quantity TU quantity A quantity- or range-valued use context assigned to the code system (CodeSystem.useContext.value.ofType(Quantity)) (CodeSystem.useContext.value as Quantity) | (CodeSystem.useContext.value.ofType(Range)) (CodeSystem.useContext.value as Range) 30 Resources
context-type TU token A type of use context assigned to the code system CodeSystem.useContext.code 30 Resources
context-type-quantity TU composite A use context type and quantity- or range-based value assigned to the code system On CodeSystem.useContext:
  context-type: code
  context-quantity: value.ofType(Quantity) value.as(Quantity) | value.ofType(Range) value.as(Range) 		30 Resources
context-type-value TU composite A use context type and value assigned to the code system On CodeSystem.useContext:
  context-type: code
  context: value.ofType(CodeableConcept) value.as(CodeableConcept) 		30 Resources
date TU date The code system publication date CodeSystem.date 30 Resources derived-from TU reference A resource that the CodeSystem is derived from CodeSystem.relatedArtifact.where(type='derived-from').resource (Any) 10 Resources
description TU string The description of the code system CodeSystem.description 28 Resources effective TU date The time during which the CodeSystem is intended to be in use CodeSystem.effectivePeriod 12 Resources
identifier TU token External identifier for the code system CodeSystem.identifier 34 Resources
jurisdiction TU token Intended jurisdiction for the code system CodeSystem.jurisdiction 26 Resources
language TU token A language in which a designation is provided CodeSystem.concept.designation.language
name TU string Computationally friendly name of the code system CodeSystem.name 26 Resources predecessor TU reference The predecessor of the CodeSystem CodeSystem.relatedArtifact.where(type='predecessor').resource (Any) 10 Resources
publisher TU string Name of the publisher of the code system CodeSystem.publisher 30 Resources
status TU token The current status of the code system CodeSystem.status 35 Resources
supplements TU reference Find code system supplements for the referenced code system CodeSystem.supplements
( CodeSystem )
system TU uri The system for any codes defined by this code system (same as 'url') CodeSystem.url
title TU string The human-friendly name of the code system CodeSystem.title 27 Resources topic TU token Topics associated with the CodeSystem CodeSystem.topic 10 Resources
url TU uri The uri that identifies the code system CodeSystem.url 34 Resources
version TU token The business version of the code system CodeSystem.version 30 Resources