Stream: shorthand
Topic: Doc for thoughts
Nick George (Feb 02 2020 at 23:00):
Hey Folks, I've put together a doc with some of my thoughts from working with FSH - figured it might be useful as a place for people to put their thoughts too. I'll turn these into issues on the tracker, but for now it's easier for me to have a place to put ideas:
https://docs.google.com/document/d/1dPC8sWsNzYtZevlQp8FCvn5EbHZt5LoacYfqhWYcVfc/
Nick George (Feb 02 2020 at 23:28):
Seems google docs doesn't work for everyone, I'll upload here:
Nick George (Feb 02 2020 at 23:28):
Chris Moesel (Feb 03 2020 at 00:33):
Thanks, @Nick George -- some really good feedback here. Regarding #1...
1) The profile has no control over the name of the slice
Technically you can control the slicename by using an alias. For example, US Core could create an alias called race that points to their race extension and then use that alias when introducing the extension to a profile. But that is admittedly a bit more complicated than we'd like. I don't mention it as a counter-example, but moreso to provide a workaround that should work w/ current FSH/SUSHI for those struggling with this now. I agree we should think more about how we control slicenames in general.
Chris Moesel (Feb 03 2020 at 00:35):
2) The slice name is non-standard case (CapitalCase instead of camelCase)
Does FHIR actually say anything about this? I also prefer lowercase when given the choice, but there are counterexamples in the core FHIR spec. For example, the BP profile contains the following slicenames: BPCode, SystolicBP, DiastolicBP. In fact, this is the profile that convinced me it is OK to have capitalized slicenames.
Chris Moesel (Feb 03 2020 at 00:44):
Proposal: specify slice name separate from type.
extension[species] FishSpecies
extension[species] 0..1 FishSpecies
Personally, I kind of like the consistency that whenever you add a slice, you always do it the same way, regardless of context -- so I like using extension contains... But that is a personal preference. I may be in the minority (I am kind of known for really liking consistency). But I do like your idea of separating the slice name from the type. What do you think of this?
- extension contains FishSpecies as species
or if we did away w/ contains here:
- extension[FishSpecies as species] 0..1
Or we could borrow from CQL's convention for renaming imported libraries (e.g., FishSpecies called species).
Nick George (Feb 03 2020 at 00:59):
I'm a huge fan of consistency too, but I think it's worth considering Extensions as a separate case because they're so far and away the most common kind of slicing people will do. I think optimizing/ for the most common case makes sense.
Nick George (Feb 03 2020 at 01:01):
regarding
extension[FishSpecies as species] 0..1
that seems doable, but a bit odd, imho. I think that
$FIELD_NAME[$SLICE_ NAME] $info $about $slice
is a more obvious pattern
Nick George (Feb 03 2020 at 01:03):
as for SystolicBP, I consider those non-standard :)
that being said, the flexibility for a given resource to define its own slicenames, regardless of the information on the extension SD, is more important to me than the actually slicename that gets chosen
Chris Moesel (Feb 03 2020 at 01:33):
Thought: Referring to extensions by name makes me a little uncomfortable, because it could be ambiguous, e.g., if two Extensions share a name, or Extension has a name that is a Resource type.
Yeah, I think in an effort to try to be ultra flexible, we might be shooting ourselves in the foot a bit. I expect we might need some more strict naming resolution rules in the near future. You're right on.
Nick George (Feb 03 2020 at 01:35):
I updated that one in the google doc - was writing exactly what you ended up saying on stream - that reserving name resolution for things within the same package, and using URLs for external resolution could be a reasonable solution
Chris Moesel (Feb 03 2020 at 01:40):
Yes, although we can still run into this issue even locally -- for example, if someone uses Foo as the name of one extension and then Foo as the id of another. Since we allow you to reference by name or id, this would be ambiguous. (Although doing what I just said is a horrible idea, so no one should ever do that).
More realistically, FHIR does allow you to re-use the id for a different type, even in the same IG. So you could have a profile w/ name/id Foo and a ValueSet w/ name/id Foo in the same IG. Usually we could tell from context which one is intended (when Foo is referenced), but maybe there are some cases where that might be ambiguous?
Also, someone reported on GitHub that there are issues if you give a profile a name/id that matches a FHIR resource name (e.g., Patient). Is it fair/reasonable/user-friendly to require that even FHIR base resources must be specified by URL? We have to figure this stuff out.
Nick George (Feb 03 2020 at 01:43):
my vote would be to pick one of name or id (I'd vote id), and error out if two things in the same package have the same id. Not sure what the spec says about package-wide uniqueness of id on SDs, but it seems a reasonable requirement to me. If it's not something that is enforced, I think we'd have to go URL everywhere. But my vote would be for Name to not have syntactical meaning
Nick George (Feb 03 2020 at 01:43):
for ValueSets/CodeSystems, I'd vote always use URL
Nick George (Feb 03 2020 at 01:43):
the number of cases where you're using a local ValueSet/CodeSystem are rare enough that I don't think we need the ambiguity
Chris Moesel (Feb 03 2020 at 01:44):
If we make a specialized grammar for keyword ComplexExtensions...
We did consider the syntax that allows you to omit the extension[] bit and just refer to the extension slicename (or id? -- I say this because if you look at the profile documentation in a published IG, and that profile uses an extension, the table actually shows the extension's id (not the slicename) -- so that might be what users want to use). Anyway, I think @Mark Kramer is a fan of supporting a shorter syntax for referencing extensions and complex extension sub-extensions. We didn't go quite as far as you suggest, but only because we did not think of it!
Chris Moesel (Feb 03 2020 at 01:45):
(but just to be clear, none of that is implemented at this point and we weren't 100% agreed on how it should work -- so your feedback is very helpful).
Nick George (Feb 03 2020 at 01:47):
I think it puts the id of the extension just to be helpful (and not spit out the full url). The rule is that slicename of a subfield matches url of the subfield (when it's not an externally defined extension).
Yeah, and to be clear I'm just spitballing ideas here myself, all of this is just things to consider, based on my experience using our language internally
Nick George (Feb 03 2020 at 01:47):
Also just to be clear, I think you've all done a fantastic job so far :) The main reason I'm making so many suggestions is that I wanna be able to switch over from my langauge to yours :)
Chris Moesel (Feb 03 2020 at 01:48):
my vote would be to pick one of name or id (I'd vote id)
Hmm... currently when you declare a thing (e.g., Profile: MyPatientProfile), the bit that goes after the : becomes the name. This is partially why we allow reference by name, because it seems natural given that specific approach. Do you think the bit after the : should actually be the id then as well?
Nick George (Feb 03 2020 at 01:50):
hmm good point. The Software Engineer in me is tempted to say the id should be the top-level definer, but Name is probably more aesthetically pleasing... Personally I've always found the whole, Id/Name/Title a bit excessive...
Nick George (Feb 03 2020 at 01:50):
which do you use for the URL?
Chris Moesel (Feb 03 2020 at 01:51):
Also just to be clear, I think you've all done a fantastic job so far :)
Understood. And we definitely appreciate the feedback, especially from someone who has experience designing a similar thing themselves. And don't worry -- we're trying not to make changes just because one person suggests them. Ideally, these sorts of things will be discussed in a telecon or other open meeting so we can come to consensus of a broader diversity of users. Of course, that depends on users dialing in and/or contributing here on Zulip!
Chris Moesel (Feb 03 2020 at 01:52):
which do you use for the URL?
We use id. At one point, I think the IG Publisher required the url to have form ${canonicalbase}/${type}/${id} -- although you're the second person to ask me that, so I'm beginning to second-guess myself!
Nick George (Feb 03 2020 at 01:55):
in that case I'd vote for making the top level identifier the id. This would also minimize the diffs between an internal reference and an external reference. it would either be
${id}
or
${external_url}/StructureDefinition/${id}
Chris Moesel (Feb 03 2020 at 01:55):
The Software Engineer in me is tempted to say the id should be the top-level definer, but Name is probably more aesthetically pleasing
It is actually a difficult call. The name is intended to be the machine-friendly name used for code generation. In that way, it seems like a fair way to want to reference something and it is aesthetically pleasing. The other thing is that it seems ids most often start w/ lowercase, so (to me) profiles and extensions lose the feel of being like a class when we start doing Profile: us-core-patient. (But I don't know exactly why I want them to have a class-y feel in the first place).
Nick George (Feb 03 2020 at 01:56):
but this is a more minor point to me because it doesn't really affect the capability
Chris Moesel (Feb 03 2020 at 01:58):
If I understand correctly, it’s not currently possible to define a multi-level complex extensions via FSH
I think this is possible? At least it is intended to be. If it doesn't work that's a bug. That said, point taken on the simpler grammar.
Chris Moesel (Feb 03 2020 at 01:59):
Ginzu/auto slicing on Coding
Aside from the very simple approach for extensions, we haven't defined any of the rules/algorithms for Ginzu slicing -- so your suggestions are very welcome. Thanks!
Chris Moesel (Feb 03 2020 at 02:01):
5) Alias feel a bit ambiguous
...
Suggestion: Adopt the common “$VARIABLE” pattern.
Yeah, I think you made a really good point about this in the meeting. I too have noticed that fat-fingered aliases generally just get processes as strings, so it's hard for SUSHI to know it was not intended that way. A $ prefix would certainly help with that! We'll discuss this further for sure.
Chris Moesel (Feb 03 2020 at 02:03):
Thanks again for the excellent feedback! I'm going to signoff for now. Enjoy the rest of the connectathon!
BTW -- if the doc becomes cumbersome (especially w/out Google docs), feel free to introduce further topics here or even as issues on the appropriate GitHub (SUSHI or fhir-shorthand, depending on if it's a comment about the language or the implementation).
Nick George (Feb 03 2020 at 02:03):
Sounds good! Great to meet you and look forward to working with you!
Chris Moesel (Feb 03 2020 at 02:08):
Same!
Jose Costa Teixeira (Feb 03 2020 at 23:42):
My top 3 things that would make this more ready for prime time (I will put these suggestions where they belong, but wanted to see if worth discussing)
- SUSHI - Support roundtripping between FHIR and shorthand
- SUSHI - Clean the unnecessary / legacy content that sushi puts in a structure definition (I didn't feel comfortable that sushi started by cloning the core resource)
- SHORTHAND and SUSHI- Logical models
Ward Weistra (Feb 03 2020 at 23:47):
@Jose Costa Teixeira @Rick Geimer had the first implementation of Hatchery in XSLT at the end of the connectathon and was able to do round tripping with that + SUSHI. @Alexander Zautke also suggested to implement FHIR Shorthand -> Structure Definitions in the FHIR Mapping Language...
Grahame Grieve (Feb 03 2020 at 23:48):
reconciliation of the mapping language and short hand is in the future
Last updated: Apr 12 2022 at 19:14 UTC
