Skip to end of metadata
Go to start of metadata

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:

  1.  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.
    1. 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.
  2. 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.
  3. 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.  
  4. 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.) 

Discussion Points:

  1. 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.
    1. i.e. the canonical URL should be a 'permalink'


  • No labels


  1. Do we have formal definitions for "redistribution or republishing"?  I am sure we have discussed them, but my memory fades at the conclusions.

    Also, somewhere in this policy I'd like to see either a statement or a hyperlink to a formal statement elsewhere that describes the purpose of the canonical URL for the code system.  It is only against the purpose that the goals listed above can be judged or fulfilled.  I have searched a bit in the FHIR spec, and found something I could paste in here as a suggestion, but there may be others better placed to do that than me.  

    The initial rubric mentions value sets, but the title and the listed goals refer to code systems.  I think we should be clear that this is code systems only

  2. Julie, I will dig up the references to the need for unique stable identifiers for code systems.  This has been well known and well documented since the days of the Desiderata.

    Although the immediate and most pressing need is to identify Code Systems, the same requirement exists for Value Sets.    At this time, HL7/UTG does not have any value sets curated by organizations outside of HL7.    Very soon, we will have maybe half a dozen of them (ones from CDC and some other places) that are used very widely in HL7 IGs.  Note that ALL implementations using FHIR resources and tools REQUIRE unique URLs for BOTH code systems and value sets. This goes for FHIR terminology services as well.

  3. We need to also add that we prefer to not have https://, instead prefer http://