Stream: shorthand
Topic: Alias naming convention
Rob Reynolds (May 19 2020 at 21:03):
The language reference (https://build.fhir.org/ig/HL7/fhir-shorthand/reference.html#defining-aliases) describes two conventions for naming aliases ($ and CAPS) and I was wondering if folks have guidance on when to use which.
Nick Freiter (May 20 2020 at 12:21):
The advantage of $ is that it does give you extra, more clear, error checking. For example, if you have:
Alias: $USCoreOrganization = http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization
And then, in your profile, you do (note that I am intentionally making a typo on USCoreOrganizatioN):
Profile: MyPatient
Parent: Patient
* generalPractitioner only Reference($USCoreOrganizatioN)
you will get the following error:
Value $USCoreOrganizatioN does not resolve as alias, values beginning with "$" must resolve
If instead, you did not use the dollar sign:
Alias: USCoreOrganization = http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization
Profile: MyPatient
Parent: Patient
* generalPractitioner only Reference(USCoreOrganizatioN)
you would get the error:
No definition for the type "USCoreOrganizatioN" could be found.
In this example, perhaps it isn't a big difference, but I would argue the first error is much more clear and more quickly points you towards the issue, that something that should resolve to an aliased value is not resolving. We can give this more clear error only when the $ is used, since this signifies that the value is always an alias.
So my suggestion would be to use $ if you can. Using caps is also good since it makes aliases more visually obvious. If you are giving a short codesystem name like:
Alias: $LNC = http://loinc.org
The caps can be helpful. However, you will notice that further above I did not use caps, since in my opinion:
Alias: $USCOREORGANIZATION = http://hl7.org/fhir/us/core/StructureDefinition/us-core-organization
is hard to visually parse. So in my opinion best practice is $ always, and caps when you feel it doesn't detract from readability. However, those are just guidelines, not syntax requirements, and you are welcome to ignore them if you have a preferred style that is more readable to you.
Chris Moesel (May 20 2020 at 17:50):
As Nick noticed, one advantage of using the $ prefix is that SUSHI knows it must be an alias, so it treats it like such. Without using the $, it could be an alias, but it also could be some existing profile's name or id (which is another way SUSHI can resolve things).
Since $ is only allowed in alias names (and not any other names), it prevents the unintentional mistake of having an alias name that is the same as the name of some other thing in the IG (or the IG's dependencies) -- in which case it is not clear whether SUSHI would use the alias or the thing that has the same name as the alias.
Last updated: Apr 12 2022 at 19:14 UTC
