fsh-link-references keys by Id or Name

[LodewijkSioen]

Some resources like CodeSystem or Profile allow you to declare an Id. This is not allowed for Instances. If you want to give an Instance an Id, you need to do that explicitly trough the id element. This is often needed for consistency in the Url of NamingSystems. For example:

Instance: PatientNumber
InstanceOf: NamingSystem
Usage: #definition
* id = "patient-number"

CodeSystem: PatientEvents
Id: patient-events

Referencing resources in fsh-files can be done using the name of the resource: Reference(PatientEvents) or Canonical(PatientNumber). This work great.

Referencing these resources in markdown files using fsh-link-references doesn't work so great. A resource that allows you to declare an Id can be Referenced by name, but a resource that declares an explicit id element must by referenced by that id. This is how the above example looks like in the fsh-link-references.md file:

[patient-number]: NamingSystem-patient-number.html
[PatientEvents]: CodeSystem-patient-events.html

This is not very intuitive. I realise that changing this would be breaking. That's why I suggest adding both variants (id and name) to the file.

[LodewijkSioen]

Extra: the text of the link in the markdown file will also be like this:

[patient-number]()

instead of the nice name of the resource.

[cmoesel]

Hi @LodewijkSioen. Thank you for filing this. Just to clarify, when you create an Instance in FSH, the name you put after Instance: is the id (since not all resource types have a name). So... you do not need to use a rule to assign id if you put the id after Instance: in the first place.

That said, I think your general comment still stands since FSH does allow you to put a friendlier name after Instance: and then assign the id directly if that's what you choose to do. It is a little trickier in this case since, but we'll look into it to see what we might be able to do to make this more user-friendly.

[LodewijkSioen]

I knew that you don't need to set the id-element, but most IGs I've seen the wild (eg us core patient) have the Computable Name as PascalCase while the id is kebap-case. We have set up naming guidelines to keep this consistent in our IG and then we ran into problems when links were not generated.

Thanks for considering it.

[cmoesel]

What I mean is that when you are defining an Instance, the part after the Instance: declaration maps to the id. For other item types, like Profile:, Extension:, ValueSet:, and CodeSystem:, the value after the declaration maps to the name. Since Instance can target any resource type, however, we can't map its declaration value to name since not every resource type has a name element. This is why we map it to id instead.

So, for Profile, Extension, Logical, Resource, ValueSet and CodeSystem:

• Use corresponding declaration (e.g., Profile: X) to set the name
• Use Id: keyword to set the id

But for Instance:

• Use Instance: to set the id
• Use * name = "X" to set the name (if it has a name element)
• If you use * id = "x" to set the id, then what you specified after Instance: becomes just a handle for referencing in FSH but is not exported into any field in the FHIR JSON

Again, however, I think your basic feature request is still the same. I just wanted to call out the difference in Instance: since it's different than all the others.