Most mistakes in FHIR data modeling are easily resolved in a later iteration of your guide. But there are some that are better done right the first time. One of them? FHIR canonical URLs, the unique identifiers for your models.
FHIR conformance resources, like profiles, terminology resources and operations, are uniquely identified across servers by their canonical URL (technically a Unique Resource Identifier, but it generally indeed looks like a web link). And with every new version, systems and users will expect these to remain stable, and only their version to change.
So, which link should you choose? Here are the 4 things to consider when choosing a canonical base URL:
- Choose a domain name that is under your control. HL7 International publishes all their specifications under hl7.org and if you are publishing on behalf of ACME Corp., you may want to publish all your specifications under acme.com.
- Choose a part of your domain that is not yet being used for anything else. While it is not mandatory that the canonical URL for your project works in a browser, you do want to keep that option open. And you certainly don't want to confuse your users by ending up on something unrelated. A common approach is to use a fhir subfolder or subdomain, so for example: acme.com/fhir or fhir.acme.com.
- Choose http or https. Because of its security, https is becoming the standard protocol for all websites. For the primary use of your canonical (uniquely identifying your resources) it does not matter which protocol you put on them. Since you may still use the canonicals in a browser, I prefer the looks of https. On the other hand HL7 has historically used http for its resources. But whichever you choose, apply it consistently throughout your work.
- Leave room for other upcoming specifications. While you may be tempted to publish your first profiles directly under https://acme.com/fhir/, keep in mind that your current specification may not be ACME's last. So try to use a project specific folder in there to leave some room for differentiation and use a base that describes your project, like https://acme.com/fhir/eprescription/
Now you have figured out a future proof base for your project's canonical URLs! From here on you can safely experiment with building FHIR resources and improving them through iteration with the FHIR development cycle.
For your resources themselves, you will also want to think about a consistent way to build
their canonical URL extension to complete the picture, for example: .../<resourceType>/<resourceId>.
If you are looking for an easy way to actually make all these URLs resolve in a regular browser, have a look at https://simplifier.net/resolve. With a simple script hosted on the domain you've chosen as base URL, you can forward any browser via Simplifier to a nice view of the resource.
The original version of this article was published by Ward Weistra on LinkedIn.