Stream: IG creation
Topic: ImplementationGuide - Grouping/List in several levels
Rick Geimer (Dec 07 2020 at 21:21):
FHIR-I would like some feedback on the proposed resolution for the following JIRA tracker:
https://jira.hl7.org/browse/FHIR-25458
Repeated here for convenience:
Drop the notion of 'grouping' and grouping references from the ImplementationGuide resource
Define an IG Parameter that points to a List resource that defines the groupings to use when generating the table of contents (determines order of artifacts in the ToC). Like the parameter for terminology settings, this can either be a file location or a # reference to a contained resource.
The base template will generate a list if you don't specify one. If you don't use the template and don't specify the parameter, then the order of the artifact entries in the ToC will be arbitrary
The List can point to sub-lists if there's a desire for greater hierarchy.
Will use List.title for the grouping name and define a standard extension to allow providing a description of the List. (Will make a change request to consider having this be a core element for R5?)
Will change the base template to produce the artifact list from the List resources rather than groupings.
If someone wants to use the same mechanism to define alternate lists such that there are multiple orthogonal artifact lists navigable in different ways, they can, but only one can be primary and drive the ToC.
At some point, could explore whether some portions of the menu could be generated from these lists, but that's a separate discussion.
The anchor points used in the artifacts page would be driven by List.id
@Jose Costa Teixeira @Sean McIlvenna
Jose Costa Teixeira (Dec 07 2020 at 21:35):
Thanks for this. Apologies for missing the call.
I think the suggested resolution makes sense. A few thoughts:
- With this solution, do we still need to list the resources in the IG? It would make sense if this solution also covers that. We could add an extension to replace implementationguide.resource.exampleCanonical.
Jose Costa Teixeira (Dec 07 2020 at 21:35):
- Just to share athought I had meanwhile - I've wondered if Composition would be more suited than List? just because it includes nested sections and has a .text attribute already.
Jose Costa Teixeira (Dec 07 2020 at 21:37):
I'm happy to provide some examples (and help with adapting the template of course)
David Pyke (Dec 07 2020 at 21:42):
I'd prefer List to overloading the usage of Composition. A List of Lists seems to me to be a better organization than one large resource. If we're going to have a monolithic resource, we can stick with adding levels to ImplementationGuide
Jose Costa Teixeira (Dec 07 2020 at 22:26):
The idea from Composition came when I was creating content - I realized that this is actually an authored set of resources, with a focus on presentation, and I realized that besides the title and narrative, the nesting would be really handy - you could say "This section contains the profile, and sub-sections are the examples" - this should look neat in the ToC and the template could pick it up quite easily
Eric Haas (Dec 07 2020 at 22:33):
+1 on Composition for TOC generation... especially if Sushi can build from a config sushi-config,yml
Gino Canessa (Dec 07 2020 at 22:36):
FHIR#25458 is only about the Artifact Index page; e.g., using List to control the artifacts and how they are listed / grouped. I think Composition would be something interesting to look into for an entire IG, but it doesn't feel like the right fit for just listing artifacts to me.
Eric Haas (Dec 07 2020 at 22:42):
if listing artifacts includes titles and descriptions of the groups and nesting, then I am with @Jose Costa Teixeira , everytime I look at composition structure, I see a table of contents.
Eric Haas (Dec 07 2020 at 22:44):
but I am more interested in Sushi doing this for me whatever the structure(s) winds up being. So asking @Chris Moesel his opinion.
Jose Costa Teixeira (Dec 07 2020 at 22:52):
@Eric Haas Yes, my idea (initially for List but also applicable for Composition) is that this would be supported in sushi - we'd have a fsh file (not necessarily sushi-config) and that creates the composition (and avoid those new extensions that were discussed recently). In my case, when I need to copy content across IGs, I would just copy the fsh files and I would not need to touch the ig.json - but that sushi feature would be a request for Sushi, once this Jira is settled
Lloyd McKenzie (Dec 07 2020 at 22:55):
- The referenced List would be pointed to by file-path. So long as that was just in input or some other folder not searched for resources, it wouldn't show up in the IG. (We didn't talk about the possibility of how to find other lists though... I guess we'd need extensions that pointed to all of them.
- That's actually somewhat appealing. It has build in hierarchy and has both title and text, which takes care of label and description. Composition is an 'organizer'. It's fine if we're just using it to organize only the resources, not everything. The need to have independent Lists of Lists only really matters if you've got a tool generating some of the Lists and you're then compiling them into your own ordered List of Lists.
If SUSHI is representing this, it should be the same way it represents Compositions (or Lists) generally - it shouldn't create a custom solution just for this I don't think.
Jose Costa Teixeira (Dec 07 2020 at 22:57):
Yes, sushi would just use the standard sushi way of creating Compositions.
Jose Costa Teixeira (Dec 07 2020 at 22:59):
One thing I did not think through was the impact of using Composition in multidimensional structuring of contents - I guess it would not change much?
One Composition for artifacts grouped by type, other for artifacts grouped by topic (e.g. Vaccination vs Allergies vs Procedures).. (or one single Composition and different sections for each group)
Elliot Silver (Dec 07 2020 at 23:03):
The resources (whether list or composition) could be done as contained (inline in FSH) resources.
Jose Costa Teixeira (Dec 07 2020 at 23:10):
why contained? contained in which resource?
Lloyd McKenzie (Dec 07 2020 at 23:11):
The 'base' organizer used to generate the ToC can't be multi-dimensional. Every artifact should appear in the hierarchy exactly once. However, other Compositions that don't have that requirement could also be used and it's possible to have the artifact list be driven by a different organizer than the ToC.
Elliot Silver (Dec 07 2020 at 23:11):
Well, my first thought was contained in the IG resource. But I suppose that might get in the way of actual resources contained in the IG. Hmm, needs more thought.
Lloyd McKenzie (Dec 07 2020 at 23:11):
Agree that contained is possible, but shouldn't be a requirement. (Formally speaking, 'contained' is appropriate as the organizers would presumably have no meaning/relevance if the IG went away.)
Lloyd McKenzie (Dec 07 2020 at 23:12):
However, from a maintenance perspective, you might want different individuals to work on the organizer(s) than are allowed to mess with the IG itself.
Jose Costa Teixeira (Dec 07 2020 at 23:17):
Lloyd McKenzie said:
The 'base' organizer used to generate the ToC can't be multi-dimensional. Every artifact should appear in the hierarchy exactly once. However, other Compositions that don't have that requirement could also be used and it's possible to have the artifact list be driven by a different organizer than the ToC.
Yes, the 'base' organizer could be a Composition but it could also be a section in the composition, right?
Lloyd McKenzie (Dec 07 2020 at 23:26):
I suppose, though we'd then need to point to both the file and an id within the file
Elliot Silver (Dec 07 2020 at 23:27):
Lloyd McKenzie said:
I suppose, though we'd then need to point to both the file and an id within the file
Unless the id was a magic value, like "TOC".
Lloyd McKenzie (Dec 07 2020 at 23:32):
Elliot Silver said:
Unless the id was a magic value, like "TOC".
That'd work
Eric Haas (Dec 07 2020 at 23:37):
well I was thinking adding it as a YAML list to the sushi-config.yml and foregoing using fsh and let sushi do all the work like it does for the ig resource :-)
Eric Haas (Dec 07 2020 at 23:41):
all this for a stupid TOC. sigh.. If git didn't sort alphabetically we could just used the tree structure....
Lloyd McKenzie (Dec 07 2020 at 23:42):
It's not just sorting, it's names and descriptions. We don't want to create custom YAML files all over. We're trying to minimize the number of things that aren't proper resources.
Eric Haas (Dec 07 2020 at 23:45):
it is a proper resource... I am talking about convenient data entry
Eric Haas (Dec 07 2020 at 23:48):
This only support my opinion that for static web site should use the menu for navigation. TOC are for pdfs.
Lloyd McKenzie (Dec 07 2020 at 23:48):
Data entry needs to be in one of the official syntaxes
Eric Haas (Dec 07 2020 at 23:49):
.... or whatever gets the job done. :-)
Chris Moesel (Dec 08 2020 at 00:14):
I think I'll need to see this in action before fully understanding it, but SUSHI can support it in whatever way makes sense. One of the things SUSHI does is try to support graceful transitions from configuration changes -- so I wouldn't be surprised if we at least supported converting the old way (via IG groups) to the new way (Composition?) for a period of time to ease that transition. As for how else SUSHI supports it, I'd have to see how it shakes out before I comment further.
Jose Costa Teixeira (Dec 08 2020 at 22:00):
I got lost on a detail above.
I presume we can have one single Composition, with one section that works as a TOC, and other sections that work as other dimensions to group content, right?
the section that works as a TOC could have the identifier as a magic value, but why not use Composition.section.code = "IG_TOC"
Jose Costa Teixeira (Dec 08 2020 at 22:01):
also, to make it fun, we can add pages (DocumentReference) as well as resources, right?
Lloyd McKenzie (Dec 08 2020 at 22:08):
How would you reference a page as a DocumentReference?
Jose Costa Teixeira (Dec 09 2020 at 07:27):
point to the xhtml / md?
Frank Oemig (Dec 09 2020 at 09:50):
It would be nice if we could use compositions to provide the page content. Currently only the text is rendered, not sections.
Lloyd McKenzie (Dec 09 2020 at 15:23):
From an authoring perspective, I don't think we want to go there. Each page needs to be its own file. We don't want all the pages glommed into a single resource. That would make both authoring and source control pretty miserable.
Frank Oemig (Dec 09 2020 at 16:07):
Not a single one. But why not using the structures composition provides in case it is helpful?
Eric Haas (Dec 09 2020 at 16:09):
My markdown is more robust as a standalone file for one
Eric Haas (Dec 09 2020 at 16:10):
( less surprises when rendered than when nested inside a resource)
Eric Haas (Dec 09 2020 at 16:14):
I do pull some content out of resources directly but editing directly in files is so much easier too. it could be packaged in a composition if you want. just stick em all in a data folder and reference them from there using liquid tags. it sounds a little like FHIR purity over practicality to me.
Lloyd McKenzie (Dec 09 2020 at 17:11):
One composition per page would be a huge amount of overhead for no obvious benefit.
Sean McIlvenna (Dec 09 2020 at 18:13):
IMO, I'm not fond of the idea of having a separate List resource to define the grouping of resources in an IG. It seems to me like it would be really easy for that List resource to deviate from the resources defined in the IG. And requires more logic to address issues like what happens when a resource defined in the List group doesn't existing the ImplementationGuide.definition.resource.
Jose Costa Teixeira (Dec 09 2020 at 19:05):
Lloyd McKenzie said:
One composition per page would be a huge amount of overhead for no obvious benefit.
that would be silly indeed. I didn't think it through, but Composition.section.entry would point to N DocumentReferences whose content.attachment points to the xml / md
Jose Costa Teixeira (Dec 09 2020 at 19:07):
Sean McIlvenna said:
IMO, I'm not fond of the idea of having a separate List resource to define the grouping of resources in an IG. It seems to me like it would be really easy for that List resource to deviate from the resources defined in the IG. And requires more logic to address issues like what happens when a resource defined in the List group doesn't existing the ImplementationGuide.definition.resource.
The List resource would not only deviate from the resources defined in the IG, it would replace it. No issue should happen when a resource in the List doesn't exist in the IG.definition.resource , because that is the intended situation.
Eric Haas (Dec 09 2020 at 19:07):
but Composition.section.entry would point to N DocumentReferences whose content.attachment points to the xml / md
and why is this indirection better that the direct reference in the IG resource?
Jose Costa Teixeira (Dec 09 2020 at 19:08):
@Sean McIlvenna perhaps you assumed that the IG.definition.resource would still list all resources, and List would only be to structure them? That is not the intent (not mine, at least)
Jose Costa Teixeira (Dec 09 2020 at 19:09):
Eric Haas said:
but Composition.section.entry would point to N DocumentReferences whose content.attachment points to the xml / md
and why is this indirection better that the direct reference in the IG resource?
You only have one IG, but you could have many Compositions, right? (again, this part I did not think through, so we can avbandon it. I'm just exploring)
Jose Costa Teixeira (Dec 09 2020 at 19:11):
Scenario: I'm done with Vaccination part in my Project IG. I want the whole thing - profiles, pages, extensions, model, examples, vocabulary, etc. to become a legal standard. I would send a single pack to the government people:
-
my resources
+ -
my Composition with the structure that I need, including the profiles and examples already pointing to that profile, the pages, the models, etc.
Jose Costa Teixeira (Dec 09 2020 at 21:04):
@Sean McIlvenna I responded to your comment in Jira - we can discuss here or there (i think it's easier to get a broader discussion here.
Sean McIlvenna (Dec 09 2020 at 21:56):
@Jose Costa Teixeira , sure, we can chat here... I just see my email notifications from JIRA more predominantly than I do from chat.fhir.org (for some reason).
Sean McIlvenna (Dec 09 2020 at 21:57):
As I stated in JIRA:
I'm still pretty strongly opposed to this. Seems like a lot of extra resources, references, and more, to support multiple people working on different sections of the groups of resources in an IG. I'm also skeptical that the List/Composition resource would even give you all the functionality we need to replace ImplementationGuide.definition.resource; what about things like exampleCanonical and exampleBoolean? It also needs to be easy to determine what resources are in an implementation guide, and it should be supported by the server's _has search parameters (ex: I should be able to say, list all StructureDefinition resources that are part of the XX ImplementationGuide).
Jose Costa Teixeira (Dec 09 2020 at 22:29):
I don't see a reason yet to be strongly opposed. Let's start with that to see if that opposition is from any misunderstanding:
Jose Costa Teixeira (Dec 09 2020 at 22:35):
- The goal is not only supporting more people working in parts of an IG (which is something that I consider a condition for better management of IGs, instead of one person handling everything), but especially to allow better structure - the TOC and the Artifact index are quite poor
Jose Costa Teixeira (Dec 09 2020 at 22:36):
- The starting point is removing the ig.grouping. Do you oppose that? Do you think the grouping should only and always be defined as is now - one-dimension, flat groupings? Why? I think this is not good enough as IGs grow more complex.
Jose Costa Teixeira (Dec 09 2020 at 22:36):
- If you really need to keep grouping as it is - for simple IGs, do you mean oppose adding the more advanced structuring as option? Or you mean that you don't have any issue with the Composition as long as the current grouping stays?
Jose Costa Teixeira (Dec 09 2020 at 22:36):
...
Jose Costa Teixeira (Dec 09 2020 at 22:36):
- Knowing that the IG will include resources that are NOT defined in the ig.json, we don't always have the possibility to search using the _has, right? So is that a must have?
Jose Costa Teixeira (Dec 09 2020 at 22:36):
- I'm sure we can easily find a solution for exampleCanonical - one that IMO is a bit better than the extension we need to have in sushi. And that looks nicer in the ToC. No need for skepticism until we try /see
Jose Costa Teixeira (Dec 09 2020 at 22:37):
- This is a lot of work for toolsmiths, but I would not be defending this proposal if I did not think that this is definitely worth the effort I will probably have with XSLTs. I want to support a clean process that does not have the IG editor as a bottleneck.
Eric Haas (Dec 09 2020 at 23:52):
I think @Sean McIlvenna has brought up a coupla great points, I forgot about the exampleBool/Ref thing - is not a feature of Comp/List and I am not a fan of repeating that either. I generally don't use Group and don't look at the TOC . If all we are concerned about is the TOC sorting then we can fix that with a better template so it looks more like this one: https://www.hl7.org/fhir/us/core/toc.html
Eric Haas (Dec 09 2020 at 23:52):
using liquid
Sean McIlvenna (Dec 10 2020 at 00:01):
@Eric Haas I've asked that we make some other improvements to the ToC before, as well :) I think the ToC is not very usable as it stands. I really would love for the ToC to be in a pop-up div on all pages, so that the user doesn't have to navigate to a separate page in order to look at the ToC. I'd also really like some search functionality on the ToC.
At a minimum, I think it needs to be clear what each resource type is in the ToC, and the distinction between a page vs. a resource. In many cases, CodeSystem resources have the same name as ValueSet resources, so if they're both included in the same IG, then it is pretty much impossible to distinguish the difference between the two resources.
However, I digress... I'd ask that if we're considering improvements to the ToC, that we meet and brainstorm amongst a group of us.
Eric Haas (Dec 10 2020 at 00:26):
I think the point here that using a List/Comp does not solve this issue
Lloyd McKenzie (Dec 10 2020 at 03:04):
The rendering of the ToC is orthogonal. The key thing is that there needs to be an ordered list of artifacts in order to produce a ToC. It's also necessary to produce a navigable artifacts list. When the list of artifacts gets too long (>15 or so) you need to split them into groupings. When it gets very long (>150?) then you start to want a multi-layer hierarchy and perhaps even multiple orthogonal hierarchical ways of navigation (though one must be primary to allow a sequential ToC and section numbering). Right now, we have no mechanism to support a multi-layer hierarchy in the ToC at all and no 'standard' way of maintaining one in IGs in general (though you could develop one manually, tooling can't check that it's complete/consistent). We need a way to support that capability.
Note that the question of what artifacts exist and what examples they're part of is orthogonal to the question of groupings. I'm still expecting the IG to include a complete list of all artifacts (and what examples they're associated with). My assumption was that the Composition/Lists/whatever would simply point to the artifacts, not that they'd be the authoritative list of the artifact contents. We still need names and definitions for artifacts, etc. Those wouldn't live in Composition or List.
Eric Haas (Dec 10 2020 at 03:40):
I'm still expecting the IG to include a complete list of all artifacts (and what examples they're associated with)
We still need names and definitions for artifacts, etc. Those wouldn't live in Composition or List.
then the Comp/List is redundant and I am completely against that. Why not allow the groupings to nest
as far as tooling - use a file tree in the source and tell the tool to suck up and group based on that. it will still sort alphabetically but is a step in the right direction.
Jose Costa Teixeira (Dec 10 2020 at 07:08):
So here's a first idea for the ExampleCanonical:
For one conformance resource , all the examples would be listed in a sub .section.
that .section.code would be "examples" and the .section.focus would be the conformance resource.
In the TOC, the examples would appear under the conformance resource(s), because they are in a sub section.
The template /publisher would create the internal links as usual.
This would also work for other things like history and testing
Jose Costa Teixeira (Dec 10 2020 at 07:12):
changing the tool to support a file tree in the source does not solve any problem - it was my first idea but I don't think it works.
Jose Costa Teixeira (Dec 10 2020 at 07:15):
Sean McIlvenna said:
However, I digress... I'd ask that if we're considering improvements to the ToC, that we meet and brainstorm amongst a group of us.
@Sean McIlvenna that is what we are trying to do.
Jose Costa Teixeira (Dec 10 2020 at 07:19):
@Lloyd McKenzie we could explore a way to include name and description with Composition.section.entry... - although that would be a step 2 or 3..?
Jose Costa Teixeira (Dec 10 2020 at 07:22):
I'll try and focus on the grouping only - leaving aside for now the menu, the exampleOf, etc.
Jose Costa Teixeira (Dec 10 2020 at 07:24):
I'm happy with the openness to revisit the resources. So let's do it right, without custom fsh or yaml, no assumptions that one editor handles it all.
Sean McIlvenna (Dec 10 2020 at 15:42):
I was not clear... I was suggesting we hash this out on a call. Might be easier
Eric Haas (Dec 18 2020 at 03:08):
I think we should have the option to add sort keys as front-matter to the pages (can hear Lloyd frowning) and extensions to the resources. that way the information lives with pages or artifacts. you can create Lists and Compositions from them even!
Lloyd McKenzie (Dec 18 2020 at 03:30):
Definitely frowning. Pages shouldn't have any metadata at all. They should be bare XHTML or markdown. Any metadata should be in the IG resource. Just list them in the order you want them in.
Last updated: Apr 12 2022 at 19:14 UTC
