Please note:
- This guidance is currently under revision. There will be disruption as the content will be updated daily and with links not working.
- The latest published guide can be found here.
- Please follow the guidance on the "Contact Us" page if you need any assistance.
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.
Base Resource Definitions
View further information about FHIR base resource definitions.
| Element name | Base Cardinality | UK Core Cardinality | Type | Definition, Constraints and Notes |
|---|---|---|---|---|
| id | 0..1 | 1..1 | id | In the UK Core the format is the following, with the BusinessName in PascalCase:UKCore-[BusinessNames]. |
DomainResource Resource
View further information about FHIR domain resources.
| Element name | Base Cardinality | UK Core Cardinality | Type | Definition, Constraints and Notes |
|---|---|---|---|---|
| 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]. |
| identifier | 0..* | 0..0 | Identifier | identifier SHALL NOT be used within the UKCore |
| version | 0..1 | 1..1 | string | This will follow the Semantic Versioning standard [major.minor.patch]. |
| name | 0..1 | 1..1 | string | In the UK Core the format is PascalCase:UKCore[BusinessNames]. |
| title | 0..1 | 1..1 | string | In the UK Core the format is Proper Case:UK Core [Business Names]. |
| status | 1..1 | 1..1 | code | See NamingSystem.status for more information. |
| date | 0..1 | 1..1 | dateTime | Only the date, without time, is populated in the UK Core. |
| publisher | 0..1 | 1..1 | string | 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 Publisher, Contact & Copyright 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 | The UKCore format SHOULD be as follows: A set of codes that define [description]. |
| copyright | 0..1 | 1..1 | markdown | All UK Core CodeSystems SHALL contain the the copyright as listed in Publisher, Contact & Copyright |
DomainResource Resource
View further information about FHIR Resource CodeSystem - Content.
| Element name | Base Cardinality | UK Core Cardinality | Type | Definition, Constraints and Notes |
|---|---|---|---|---|
| caseSensitive | 0..1 | 1..1 | boolean | For all UK Core CodeSystems this SHALL be set to "true" unless a specific use case justifies it being set to "false". In this case the reasoning for the decision SHALL be added to the description element. |
| 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 | This SHALL be included as this presents the concept to a user in a human-readable manner. |
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
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. For example:
<concept> <code value="prescribed-at-gp-practice" /> <display value="Prescribed at GP practice" /> </concept>
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.
CodeSystem created for the UK Core
HTML View
Table View
| CodeSystem.id[0] | UKCore-MedicationPrescribingOrganization |
| CodeSystem.url[0] | https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationPrescribingOrganization |
| CodeSystem.version[0] | 1.0.0 |
| CodeSystem.name[0] | UKCoreMedicationPrescribingOrganization |
| CodeSystem.title[0] | UK Core Medication Prescribing Organization |
| CodeSystem.status[0] | retired |
| CodeSystem.date[0] | 2022-08-26 |
| CodeSystem.publisher[0] | HL7 UK |
| CodeSystem.contact[0].name[0] | HL7 UK |
| CodeSystem.contact[0].telecom[0].system[0] | |
| CodeSystem.contact[0].telecom[0].value[0] | ukcore@hl7.org.uk |
| CodeSystem.contact[0].telecom[0].use[0] | work |
| CodeSystem.contact[0].telecom[0].rank[0] | 1 |
| CodeSystem.description[0] | A CodeSystem to identify the type of organisation responsible for authorising and issuing a medication. |
| CodeSystem.copyright[0] | Copyright © 2021+ HL7 UK Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html. |
| CodeSystem.caseSensitive[0] | True |
| CodeSystem.content[0] | complete |
| CodeSystem.concept[0].code[0] | prescribed-at-gp-practice |
| CodeSystem.concept[0].display[0] | Prescribed at GP practice |
| CodeSystem.concept[1].code[0] | prescribed-by-another-organisation |
| CodeSystem.concept[1].display[0] | Prescribed by another organisation |
XML View
<CodeSystem xmlns="http://hl7.org/fhir"> <id value="UKCore-MedicationPrescribingOrganization" /> <url value="https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationPrescribingOrganization" /> <version value="1.0.0" /> <name value="UKCoreMedicationPrescribingOrganization" /> <title value="UK Core Medication Prescribing Organization" /> <status value="retired" /> <date value="2022-08-26" /> <publisher value="HL7 UK" /> <contact> <name value="HL7 UK" /> <telecom> <system value="email" /> <value value="ukcore@hl7.org.uk" /> <use value="work" /> <rank value="1" /> </telecom> </contact> <description value="A CodeSystem to identify the type of organisation responsible for authorising and issuing a medication." /> <copyright value="Copyright © 2021+ HL7 UK Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html." /> <caseSensitive value="true" /> <content value="complete" /> <concept> <code value="prescribed-at-gp-practice" /> <display value="Prescribed at GP practice" /> </concept> <concept> <code value="prescribed-by-another-organisation" /> <display value="Prescribed by another organisation" /> </concept> </CodeSystem>
JSON View
{ "resourceType": "CodeSystem", "id": "UKCore-MedicationPrescribingOrganization", "url": "https://fhir.hl7.org.uk/CodeSystem/UKCore-MedicationPrescribingOrganization", "version": "1.0.0", "name": "UKCoreMedicationPrescribingOrganization", "title": "UK Core Medication Prescribing Organization", "status": "retired", "date": "2022-08-26", "publisher": "HL7 UK", "contact": [ { "name": "HL7 UK", "telecom": [ { "system": "email", "value": "ukcore@hl7.org.uk", "use": "work", "rank": 1 } ] } ], "description": "A CodeSystem to identify the type of organisation responsible for authorising and issuing a medication.", "copyright": "Copyright © 2021+ HL7 UK Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html.", "caseSensitive": true, "content": "complete", "concept": [ { "code": "prescribed-at-gp-practice", "display": "Prescribed at GP practice" }, { "code": "prescribed-by-another-organisation", "display": "Prescribed by another organisation" } ] }
CodeSystem based on previously created content
HTML View
Table View
| CodeSystem.id[0] | UKCore-DeathNotificationStatus |
| CodeSystem.url[0] | https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus |
| CodeSystem.version[0] | 2.1.0 |
| CodeSystem.name[0] | UKCoreDeathNotificationStatus |
| CodeSystem.title[0] | UK Core Death Notification Status |
| CodeSystem.status[0] | active |
| CodeSystem.date[0] | 2021-09-10 |
| CodeSystem.publisher[0] | HL7 UK |
| CodeSystem.contact[0].name[0] | HL7 UK |
| CodeSystem.contact[0].telecom[0].system[0] | |
| CodeSystem.contact[0].telecom[0].value[0] | ukcore@hl7.org.uk |
| CodeSystem.contact[0].telecom[0].use[0] | work |
| CodeSystem.contact[0].telecom[0].rank[0] | 1 |
| CodeSystem.description[0] | A CodeSystem to identify the type of death notice as held on Personal Demographics Service (PDS) or any other source system. |
| CodeSystem.copyright[0] | Copyright © 2021+ HL7 UK Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html. |
| CodeSystem.caseSensitive[0] | True |
| CodeSystem.content[0] | complete |
| CodeSystem.concept[0].code[0] | 1 |
| CodeSystem.concept[0].display[0] | Informal - death notice received via an update from a local NHS Organisation such as GP or Trust |
| CodeSystem.concept[1].code[0] | 2 |
| CodeSystem.concept[1].display[0] | Formal - death notice received from Registrar of Deaths |
| CodeSystem.concept[2].code[0] | U |
| CodeSystem.concept[2].display[0] | Removed |
XML View
<CodeSystem xmlns="http://hl7.org/fhir"> <id value="UKCore-DeathNotificationStatus" /> <url value="https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus" /> <version value="2.1.0" /> <name value="UKCoreDeathNotificationStatus" /> <title value="UK Core Death Notification Status" /> <status value="active" /> <date value="2021-09-10" /> <publisher value="HL7 UK" /> <contact> <name value="HL7 UK" /> <telecom> <system value="email" /> <value value="ukcore@hl7.org.uk" /> <use value="work" /> <rank value="1" /> </telecom> </contact> <description value="A CodeSystem to identify the type of death notice as held on Personal Demographics Service (PDS) or any other source system." /> <copyright value="Copyright © 2021+ HL7 UK Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html." /> <caseSensitive value="true" /> <content value="complete" /> <concept> <code value="1" /> <display value="Informal - death notice received via an update from a local NHS Organisation such as GP or Trust" /> </concept> <concept> <code value="2" /> <display value="Formal - death notice received from Registrar of Deaths" /> </concept> <concept> <code value="U" /> <display value="Removed" /> </concept> </CodeSystem>
JSON View
{ "resourceType": "CodeSystem", "id": "UKCore-DeathNotificationStatus", "url": "https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus", "version": "2.1.0", "name": "UKCoreDeathNotificationStatus", "title": "UK Core Death Notification Status", "status": "active", "date": "2021-09-10", "publisher": "HL7 UK", "contact": [ { "name": "HL7 UK", "telecom": [ { "system": "email", "value": "ukcore@hl7.org.uk", "use": "work", "rank": 1 } ] } ], "description": "A CodeSystem to identify the type of death notice as held on Personal Demographics Service (PDS) or any other source system.", "copyright": "Copyright © 2021+ HL7 UK Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html.", "caseSensitive": true, "content": "complete", "concept": [ { "code": "1", "display": "Informal - death notice received via an update from a local NHS Organisation such as GP or Trust" }, { "code": "2", "display": "Formal - death notice received from Registrar of Deaths" }, { "code": "U", "display": "Removed" } ] }