There is a need to give advice to organizations outside of HL7 so that they have guidance when assigning canonical URLs for code systems, code system supplements and sometimes value sets that they publish and which are (or are expected to be) used in FHIR-based implementations. For any terminological content that is licensed for redistribution or republishing (through agreements negotiated by the HL7 Terminology Authority), the publishing and distribution mechanism is via the HL7 Terminology, maintained through the UTG process - this requires all code systems and value sets to have a canonical URL also. There also exist organizations with terminological content widely used in healthcare IT systems where there exists no canonical URL, or where the responsible organization chooses not to assign a URL.
The goal for a Code System canonical URL is that it is:
- Stable over time. It is used to identify the code system of captured information in numerous clinical and administrative healthcare systems (potentially into the tens or hundreds of thousands of installs), and thus would present both a hardship for the industry and a cause for patient errors on longitudinal data look-ups and searches if the URL changes. Once established and in use, the canonical URL should never be changed.
- i.e even if the organization responsible for managing the code system, the preferred descriptive name for the code system, or other key metadata changes, the canonical URL should remain unchanged.
- The canonical URL should be human readable and recognizable. It has turned out that development and debugging of implementations is slowed and made more expensive with the use of meaningless identifiers for things like code systems, and the current sense is that the advantages of using meaningless identifiers does not make up for the cost increases for system development. Meaningful identifiers are also slightly less susceptible to keying errors that result in the wrong URL being used.
- It is preferable that a code system URL be a resolvable endpoint, i.e. pasting it into a browser will do something more than a "404 - not found' error. In some cases, this might be to a terminology server endpoint or formal FHIR resource definition, but in many cases it will just point to a documentation page about the code system.
- The syntax of the URL must be machine processable by XML tools, i.e. no special characters or active script commands embedded in it. It should also not be specific to the format of the page (i.e. it shouldn't end in .pdf, .html or .htm, etc.)
- Organizations have the flexibility to name their servers or domains and/or folders to be whatever makes the most sense to their business. If, as time goes on, the original canonical URL is a string that no longer closely matches what the organization considers to be its primary key words, this is not a problem: all servers that can support DNS and internet browsing have the capability of a simple redirect to a browsable web page for their domain (usually the root of their main server), or any folder under that domain on that server. This is a server configuration parameter, supported by all server technologies and products. This permits the entry page for the code system canonical URL to be anything the publisher wants it to be; all that is required is the server configuration parameter to make the canonical URL redirect to that page.
- i.e. the canonical URL should be a 'permalink'