CodeSystem Design
This section provides background information on metadata used within CodeSystem resources, a section that lists HL7 FHIR standard extensions that may be considered relevant to a UK Core CodeSystem, and links to example CodeSystems already created for the UK Core.
Further information about the CodeSystem resource is available online.
Metadata usage
The list below contains the element differences between the UKcore and HL7. The tables are split into generic Resource elements, followed by generic DomainResource elements, followed by CodeSystem resource elements.
View further information about FHIR base resource definitions and elements.
View further information about FHIR domain resources.
| Element name | Base Cardinality | UK Core Cardinality | Type | Definition, Constraints and Notes |
|---|---|---|---|---|
| id | 0..1 | 1..1 | id | Logical id of this artifact. In the UK Core the format is the following, with the BusinessName in PascalCase: UKCore-[BusinessNames]. |
| url | 0..1 | 1..1 | uri | In the UK Core the format is the following, with the BusinessName in PascalCase:https://fhir.hl7.org.uk/CodeSystem/UKCore-[BusinessNames]. |
| Element name | Base Cardinality | UK Core Cardinality | Type | Definition, Constraints and Notes |
|---|---|---|---|---|
| identifier | 0..* | 0..* | Identifier | Additional identifier for the ValueSet, for example an OID. If this is an OID, this should be in the following format: <identifier>
<system value="urn:ietf:rfc:3986"/>
<value value="urn:oid:2.16.840.1.113883.2.1.3.2.4.16.21"/>
</identifier>Further guidance may be needed in due course. |
| version | 0..1 | 1..1 | string | Business version of the ValueSet. This will follow the Semantic Versioning standard [major.minor.patch]. |
| name | 0..1 | 1..1 | string | Computer readable name, this should reflect the name in the url element. In the UK Core the format is PascalCase: UKCore[BusinessNames]. |
| title | 0..1 | 1..1 | string | Human readable name, this should reflect the name in the url element. In the UK Core the format is Proper Case: UK Core [Business Names]. |
| status | 1..1 | 1..1 | code | The publication status as defined in value set publication-status. For the UKCore these are defined as:
|
| date | 0..1 | 1..1 | dateTime | The date (and optionally time) when the CodeSystem was published or last changed. The date must change when the business version or status changes. Only the date, without time, is populated in the UK Core. |
| publisher | 0..1 | 1..1 | string | Name of the publisher (organization or individual). For all UK Core CodeSystems, where the base URL is https://fhir.hl7.org.uk, this will be HL7 UK. |
| contact | 0..* | 1..* | ContactDetail | Contact details for the publisher. See the Metadata Design for details of how this SHALL be populated for all UK Core CodeSystems, where the base URL is https://fhir.hl7.org.uk/. |
| description | 0..1 | 1..1 | markdown | A free text natural language description of the of the code system from a consumer's perspective. The UKCore format SHOULD be as follows: A set of codes that define [description]. |
| copyright | 0..1 | 1..1 | markdown | A copyright statement relating to the code system and/or its contents. All UK Core CodeSystems SHALL contain the the copright as listed in Metadata Design |
| caseSensitive | 0..1 | 0..1 | boolean | A boolean to describe if code comparison is case sensitive. This element is primarily provided to support validation software. For UK Core CodeSystems comprising codes which contain alphabetic characters, this SHALL be set to "true". For UK Core CodeSystems comprising codes which do not contain alphabetic characters, this SHOULD NOT be used. |
| Element name | Base Cardinality | UK Core Cardinality | Type | Definition, Constraints and Notes |
|---|---|---|---|---|
| content | 1..1 | 1..1 | code | A code from required ValueSet https://hl7.org/fhir/valueset-codesystem-content-mode.html to describe how much of the content of the code system - the concepts and codes it defines - are represented in this resource [not-present | example | fragment | complete | supplement]. This SHOULD normally be set to ‘complete’, i.e. all the concepts defined by the code system are included in the code system resource. |
| concept | 0..* | 0..* | Backbone Element |
Concepts that are in the code system. Cardinality would normally be 1..* but set to the standard 0..* to allow for a use case where the content element has a value of "not-present". |
| concept .display |
0..1 | 1..1 | uri | A human readable string that is the recommended default way to present this concept to a user. |
CodeSystem Extensions
This section lists HL7 FHIR standard code system extensions that could be considered for use in UK Core code systems.
The full list of FHIR standard code system extensions is available online.
codesystem-concept-comments
The FHIR Standard extension https://hl7.org/fhir/extension-codesystem-concept-comments.html could be considered where there is a need to include comments against individual code system concepts, for example https://hl7.org/fhir/codesystem-administrative-gender.xml.html
XML template for a new CodeSystem
<!--Only include the following caseSensitive element where the CodeSystem contains alpha/alphanumeric codes.--> <caseSensitive value="true" /> <content value="complete" /> <!--The concept element below is repeated for each concept in the code system.--> <concept> <code value="[conceptCode]" /> <display value="[conceptDisplay]" /> </concept> </CodeSystem>
Creating codes for a CodeSystem
Where they don't already exist, the UK Core approach to creating codes for concepts in a new CodeSystem is by placing a hyphen between each word of the display value (if they contain more than one word) and using solely lower case alphabetic characters.
An exception to this is where the CodeSystem is a copy of a Data Dictionary set of concepts from any of the UK nations, where the approach is to faithfully use both the code and its description within the CodeSystem as defined within the Data Dictionary source at the time of creation of the CodeSystem. Note that for some CodeSystems already in existence in the UK core, including content previously created for other projects, alternative code construction forms have also been used.
Example CodeSystems from the UK Core
Code system created for the UK Core
https://simplifier.net/HL7FHIRUKCoreR4/UKCore-MedicationPrescribingOrganization/~xml
Code system based on previously created content
https://simplifier.net/HL7FHIRUKCoreR4/UKCore-DeathNotificationStatus/~xml
Code system based on Data Dictionary content (to be provided once the resource has been incorporated into the UK Core).