Stream: catalogs
Topic: On CatalogHeader
Brian Kaney (Sep 29 2020 at 21:07):
I am working on building an order-catalog, thanks for all the hard work on the IG!
One thing that I am having trouble getting behind is the use of Composition for CatalogHeader. I really think this should be a Library, and here's why:
From the spec:
The Composition resource - defines a set of healthcare-related information that is assembled together into a single logical document that provides a single coherent statement of meaning, establishes its own context and that has clinical attestation with regard to who is making the statement.
The Library resource is a general-purpose container for knowledge asset definitions. It can be used to describe and expose existing knowledge assets such as logic libraries and information model descriptions, as well as to describe a collection of knowledge assets.
From this and other documentation in the spec, Composition seems more focused on EHR runtime with a patient context and not for organizing definitional artifacts?
Library is already used in several well-used IGs (CPG, CQF measures, for instance) to represent a collection of knowledge artifacts such as: ActivityDefinition, PlanDefinition, Questionnaire, and Measure (https://www.hl7.org/fhir/clinicalreasoning-knowledge-artifact-distribution.html). Which seem to fit perfectly.
And if asset-collection doesn't work, Library.type is extensible (unlike Composition where the binding strength is higher, which is why the examples in the IG probably doesn't have a corresponding code for "catalog").
Anyway, this is my feedback from the field. I would be happy to create a JIRA ticket if this seems like a topic to continue discussing! Thanks again :)
Brian Kaney (Sep 29 2020 at 21:55):
And if it were Library, we could use Canonical references (e.g. PlanDefinition.orderCatalog) instead of a Reference.
Lloyd McKenzie (Sep 29 2020 at 22:57):
Composition supports organizing content into sections, sub-sections, etc. which is aligned with the 'human presentation' aspect of catalogs. Library can't do that. Also, the content of a Library must be an attachment, while the content of a catalog is often references to resources that are maintained independently. (In some cases, the same resource instance might be referenced by multiple catalogs.)
Brian Kaney (Sep 30 2020 at 16:03):
Thanks @Lloyd McKenzie
What do you think about Composition (a) not being able to have a canonical URL and (b) the binding preference of LOINC which seems to have the consequence that the present IG relies on a code.text (and not a code token)?
Composition supports organizing content into sections, sub-sections, etc. which is aligned with the 'human presentation' aspect of catalogs. Library can't do that.
I guess I don't see how this organization would work practically, as CatalogHeader (the topic of this thread) as seen in method #2 (which more likely unless a trivial catalog) where the item refers to the CatalogHeader (child to parent reference -- last paragraph of https://build.fhir.org/ig/HL7/fhir-order-catalog/#technical-overview)?
Also, the content of a Library must be an attachment, while the content of a catalog is often references to resources that are maintained independently. (In some cases, the same resource instance might be referenced by multiple catalogs.)
attachment.url should be able to handle that (if method #1)
Lloyd McKenzie (Sep 30 2020 at 17:58):
I wouldn't expect Composition to have a canonical URL - it's not a 'definitional' artifact. It's a single instance. If you want a definitional resource, it would be something the Composition references, not the Composition itself.
I don't think the preference for LOINC drove the choice of text. The choice of text was driven by the fact the designers didn't think the sections would typically be coded or that there'd be much value in coding them. You can certainly challenge that.
Lloyd McKenzie (Sep 30 2020 at 17:59):
With respect to canonical, I don't think there's a use-case for a catalog being copied and maintained in multiple locations.
Brian Kaney (Sep 30 2020 at 18:11):
So the catalog isn't definitional? I always thought it was, and would be versioned and have canonical URL like any other authored item...
Rob Hausam (Sep 30 2020 at 19:08):
Any resource can be versioned (as long as that is supported by the server), and a canonical url and datatype isn't required for that. I'm also not seeing a clear reason that would be of additional value in this case. Along the lines of what Lloyd said, if this was something like a catalog "definition" or "template" that described how the catalog was structured and organized, rather than an instance that contains the actual catalog content, then that would be appropriate and expected.
Brian Kaney (Sep 30 2020 at 20:09):
@Rob Hausam -- A canonical reference is a way to formalize fetching a resource by a url and optional version. This is a bit different than the history feature of FHIR resource (see https://www.hl7.org/fhir/references.html#canonical).
Brian Kaney (Sep 30 2020 at 20:20):
I guess in the end, I see an order catalog as in the category of "knowledge" (verses instances of clinical fact about a patient).
Rob Hausam (Sep 30 2020 at 20:23):
Well, yes, it is. And I'm definitely aware of that. The main question I think is whether that additional capability is needed/required in this case. If it was always needed for any resource, then all references would be "canonical", and we wouldn't have a separate 'canonical' datatype that is used specifically for references to conformance and knowledge resources.
Rob Hausam (Sep 30 2020 at 20:25):
Yes, I think whether catalogs are actually "knowledge resources" (as they have been defined in FHIR) is the key question for deciding which is the most appropriate in this case.
Brian Kaney (Sep 30 2020 at 20:26):
I think "canonical behavior" in FHIR seems to be common of authored knowledge artifacts (and not clinical facts with a patient). I feel a catalog is a knowledge artifact. So that's my thinking at least :)
Rob Hausam (Sep 30 2020 at 20:26):
I certainly do agree that a catalog is not an "instance of clinical fact about a patient".
Rob Hausam (Sep 30 2020 at 20:27):
It's worth some further discussion in the project group, for sure.
Brian Kaney (Sep 30 2020 at 20:30):
Note that the relationship between the knowledge artifacts of PlanDef to ActivityDef use canonical for a good reason. I think this pattern should exist for catalogheader and the items in a catalog.
Brian Kaney (Sep 30 2020 at 20:32):
And Library would give us this "for free"... :)
Rob Hausam (Sep 30 2020 at 20:42):
I will also mention for clarity that my intent was not to state an equivalence between the history mechanism and explicit versioning of a conformance or knowledge resource, because I agree they are not the same. The question still is if the "good reason" that you are describing is what is needed here - and it could be. Would you be able to join one of the Catalog calls at noon Eastern on Friday to discuss it?
Brian Kaney (Sep 30 2020 at 21:46):
@Rob Hausam I can be, please send me a DM here or elsewhere with coordinates for the call. And thanks :)
Rob Hausam (Sep 30 2020 at 21:50):
@Brian Kaney Here are the call details.
Brian Kaney (Oct 02 2020 at 17:01):
Great call today thanks. At one point, I heard someone mention List, which seems like a good idea as well. But whatever a Catalog /CatalogHeader becomes, and regardless if it has one-way or two-way references to items -- a consideration is to have it implement the Definition Pattern, as seen in R5: http://build.fhir.org/definition.html (url, version, author, jurisdiction, useContext, etc)...
François Macary (Oct 05 2020 at 06:20):
Thanks Brian for the new ideas.
Discussion on this topic much appreciated last Friday. Captured in the catalog call minutes
I'd like @Claude Nanjo and @Lorraine Constable to check the minutes, please, and give your thoughts on the potential use of Library for representing a catalog header.
Rob Hausam (Oct 05 2020 at 14:12):
@François Macary When and how do you prefer to discuss this further, since we are planning to do ballot reconciliation on the call this week? Continue all of the further discussion (at least for now) here on Zulip?
François Macary (Oct 05 2020 at 17:08):
Yes, we have to take care of balloters' comments during our next couple calls. In the meantime, let's continue the discussion on Library as candidate for catalog header on this stream.
Lin Zhang (Oct 10 2020 at 12:45):
What's the difference between such a catalog and a CodeSystem?
Jose Costa Teixeira (Oct 10 2020 at 15:16):
A codesystem can be used to capture a list of items and a description. For example, product code + description.
A catalog is usually a formally issued document that contains the entire (relevant) set of characteristics of the products - attributes, relations with other products, whether they can be ordered (and how), prices, etc
Lin Zhang (Oct 10 2020 at 16:30):
Sound like a more special/specialized concept system, consisting of more concrete/tangible codes/concepts (but not ontological individuals) and their descriptions and relationships. Right?
Jose Costa Teixeira (Oct 10 2020 at 20:45):
I don't understand the question. Perhaps a simpler analogy is the traditional calalogs: a paper-based book(let) with the relevant (and structured) characteristics of all the products.
If we do the same in FHIR, that is also a catalog. If we just keep the codes and definitions, that could be a code system.
Lin Zhang (Oct 11 2020 at 01:15):
@Jose Costa Teixeira Well, it seems I got it a little bit more because of your further clarification. Maybe those volatile characteristics such as prices and specific performing departments are the essential differences. Thanks.
Lin Zhang (Oct 11 2020 at 01:21):
For example, abstract/generic order codes in LOINC v.s. concrete/specific order codes only suitable for a specific entity in a specific period. Am I right?
Bryn Rhodes (Oct 11 2020 at 20:22):
I would second the notion of using Library as a resource to represent a CatalogHeader, there are already other similar use cases in the Quality Measure IG (where it's used as a Quality Program), and the Clinical Guidelines IG (where it's used as an Asset Collection).
François Macary (Oct 13 2020 at 16:23):
Thanks for the links @Bryn Rhodes . At this stage, this seems to confort @Brian Kaney 's initial suggestion, and to confirm that there are two possible approaches to represent catalogs of healthcare items.
- The "document" approach representing the catalog in a document-like manner, representing the whole catalog with the Composition resource (in the Catalog profile) and reaching the items from the Composition.section.entry links. This approach elicits a discrete version management , with the Composition potentially changing version each time a new item is inserted or an old one is retired.
- The "library" approach, more dynamic, considering the catalog as a library of items directly accessible, and using the Library resource to represent the header of the catalog and the organization maintaining the catalog. This approach calls more for continuous version management: The items have their own life cycle, which do not affect the version of the Library referenced by them.
Would that be an issue to reconcile the two approaches in the same order catalog IG, offering both approaches to the catalog custodian, who would then choose and expose one single approach for one catalog? @Rob Hausam.
Brian Kaney (Oct 13 2020 at 16:42):
After much internal deliberation, "mode 1" seems better for managing change of catalog items and versions of the catalog on a whole in our use-case. And I attempted to model "mode #1" with Library and am using relatedArtifact to draw the relationship from the Library catalog to the child catalog entries. I did this instead of attachment, because I need a canonical reference to point at the children (for versioning), which I couldn't do with attachment.
Alternatively I guess it is possible to profile Library.item.attachment to have a canonicalUrl extension, but I wanted to have the FHIR search iterate work out of the box. But I think this could be done by adding a search-parameter on this new extension. However this approach might be contrary to the intention of the design of Library.attachment?
Incidentally, I also tried with List and manually applied all the attributes from the definitional pattern, but that seemed to be the wrong path, as I also needed to add a canonical reference to the children for the reason above.
Rob Hausam (Oct 13 2020 at 16:57):
@François Macary This may make sense. My slight uneasiness, though, is in having the "header" representation be different in the two cases. If the "canonical" reference capability is needed in the one approach (which points toward the use of Library), why isn't that needed in both approaches? The overall idea of a catalog is the same, regardless of which approach is chosen for organizing and managing its content. And for "method 2" (with either Library or CatalogHeader), I think we need to do some further thinking and modeling regarding what the idea of versioning of the catalog content is and how and where it will be represented.
Bryn Rhodes (Oct 13 2020 at 17:11):
The approach we took in modeling Quality Programs was to use composed-of relatedArtifacts, so we could have canonical references:
https://github.com/HL7/cqf-measures/blob/master/resources/library/library-ep-ec-quality-program.json#L72
Bryn Rhodes (Oct 13 2020 at 17:12):
Those can be versioned or versionless, depends on your need, but I think that using Library allows both approaches, because you can specify not just the catalog header, but the actual composition of the catalog with the composed-of listings.
Brian Kaney (Oct 13 2020 at 18:27):
@Rob Hausam this technique could in spirit be used in both. Since the child catalog item is a PlanDefinition, it could optionally point back at the parent(s) with the same releatedArtifact property, however we can't use a new code for type, #part-of (or similar), and the child-to-parent in a catalog context doesn't seem to fit into any of these nicely -- https://www.hl7.org/fhir/valueset-related-artifact-type.html
Brian Kaney (Oct 15 2020 at 17:22):
As I dig into other items kinds of things that might be in a catalog (medication, devices, as seen in the IG), I see MedicationKnowledge and DeviceDefinition. I feel like anything in a catalog ought to have (some or all?) of the basic attributes found in the definition pattern (https://hl7.org/fhir/2020Feb/definition.html), most especially being able to be referenced using Canonical.
I understand it was not endorsed, but perhaps the CatalogItem interface could support this?
Bryn Rhodes (Oct 15 2020 at 21:53):
Seems like MedicationKnowledge should be a definitional resource, but I know that's been discussed by Pharmacy: https://jira.hl7.org/browse/FHIR-21301 and rejected, perhaps submitting a tracker with this use case (being able to reference it from a catalog)?
Bryn Rhodes (Oct 15 2020 at 21:56):
Same with DeviceDefinition, seems like it should be definitional, and this use case is a good example of why.
Jose Costa Teixeira (Oct 15 2020 at 22:41):
DeviceDefinition is meant to be definitional. Is it not?
Jose Costa Teixeira (Oct 15 2020 at 22:42):
I agree with MedicationKnowledge should be definitional.
Jose Costa Teixeira (Oct 15 2020 at 22:42):
CatalogItem has been deprecated
( :sob: )
Jose Costa Teixeira (Oct 15 2020 at 22:47):
@Brian Kaney Catalogs and Product definitions in general are not yet very mature/ consensual yet, I believe. I think feedback is welcome. For DeviceDefinition, what would you suggest?
Brian Kaney (Oct 16 2020 at 00:01):
@Jose Costa Teixeira thanks! My opinion is any resource type that is definitional, ought to follow the definitional pattern. Resource types that literally have the word "definition" in them are, most hopefully, definitional :nerd: And I think order catalogs should always contain definitional items that can be referenced canonically.
Lloyd McKenzie (Oct 16 2020 at 00:04):
I wouldn't expect any of these to adhere to the 'Definition' pattern - which is about activities, not entities
Brian Kaney (Oct 16 2020 at 00:05):
They define the activity?
Lloyd McKenzie (Oct 16 2020 at 00:06):
Definition pattern is used by PlanDefinition, ActivityDefinition, Questionnaire and one or two others - resources that define activities that can occur
Brian Kaney (Oct 16 2020 at 00:07):
Right. DeviceDefinition defines a device and one could make the argument that it ought to incorporate definitional behavior.
Lloyd McKenzie (Oct 16 2020 at 00:08):
It might - but it can't declare mappings to the Definition pattern
Lloyd McKenzie (Oct 16 2020 at 00:09):
We could potentially define a 'Kind' pattern that could be used for resources that define kinds of entities.
Lloyd McKenzie (Oct 16 2020 at 00:09):
Which might share similar data to the Definition pattern
Brian Kaney (Oct 16 2020 at 00:10):
I see, perhaps. My big wish would be for all things that ever go into an order catalog to have canonical referencing behavior.
Lloyd McKenzie (Oct 16 2020 at 00:12):
That only makes sense if that's the way systems typically handle them - and drugs and devices would generally be catalogued by code, not a canonical URL.
Brian Kaney (Oct 16 2020 at 00:19):
I hadn't thought of trivial cases of just codes, where I would imagine using a valueset. I guess I always assumed catalog items would be FHIR resources and have a bit more to them (and might have multiple versions).
Oh I see you said "cataloged by codes", not a catalog of codes. Right... :)
Brian Kaney (Oct 16 2020 at 13:01):
I was thinking wouldn't it be possible to express a code token in the canonical url?
Lloyd McKenzie (Oct 16 2020 at 13:42):
Where are you thinking you you would need to have a canonical url? I.e. what resource?
Brian Kaney (Oct 16 2020 at 13:47):
DeviceDefinition and MedicationKnowledge are two resource types I see in the current order-catalog IG.
Brian Kaney (Oct 16 2020 at 13:49):
Lab services use Plan Def. And I imagine Order Set might end up with Plan Def as well, and support canonical.
Lloyd McKenzie (Oct 16 2020 at 13:51):
How is the order catalog pointing to items? I'd expect it to be able to reference by codes, not only canonicals?
Brian Kaney (Oct 16 2020 at 13:55):
Ah, a problem with DeviceDefinition, I see there already exists a url, but it's for a different purpose.
Bryn Rhodes (Oct 16 2020 at 17:16):
There's a tracker to remove that url element, if I'm reading JIRA correctly there
Bryn Rhodes (Oct 16 2020 at 17:16):
And yes, it has been removed from the latest build
Brian Postlethwaite (Feb 17 2021 at 20:57):
Jose Costa Teixeira said:
CatalogItem has been deprecated
( :sob: )
I'm also sad that it's being deprecated, it suits my need pretty much exactly. For the generic product catalog items available at a Pharmacy. We're able to update just the items, and don't need a single resource view, and this works for cases where items are either FHIR resources (medications/devices) and when they are not (generic stuff).
Lin Zhang (Apr 04 2021 at 12:50):
@Jose Costa Teixeira @Brian Postlethwaite
Why has CatalogItem been deprecated?
Last updated: Apr 12 2022 at 19:14 UTC
