Stream: fhir/infrastructure-wg
Topic: Sorting versions of knowledge artifacts
Bas van den Heuvel (Jan 11 2022 at 08:30):
Knowledge resources are identified by their cannonical url and the version. The specification states that when the versionis not specified, the "most recent" version should be used. The specification does not specify how to order the versions.
This topic is related to the topic raised in https://jira.hl7.org/browse/FHIR-26370. Which was discussed in the FHIR-i telco of 2022-01-10, in which a possible solution was proposed on which we would like to receive feedback.
FHIR versions use semantic versioning (http://hl7.org/fhir/r4/versions.html#versions) to identify the version of the specification.
This would work as well for knowledge resources such as ValueSets, CodeSystems, PlanDefinitions, .... Mandating this would be tricky as some parties are likely to use other versioning mechanisms such as: string sort, numbers, dates, ...
Yet without knowledge of the sorting algorithm to use, the most recent version cannot be found.
I propose that we resolve this issues in the following manner:
Knowledge artifacts will use semantic versioning for their version numbers unless a different algorithm is specified using an extension.
An initial proposal for such extension could be:
Extension: SortAlgorithmExtension
Id: sort-algorithm
Title: Sorting Algorithm Extension
Description: """
This extension defines the algorithm to be used to determine the most recent version of a knowledge artifact. The algorithm indicates in what manner the version of this knowledge artifact can be compared to previous versions.
For default algoritihms, a default set of values have been defined. More advanced use cases can use an fhirpath expression.
In the case the fhirpath expression is used, the context will be knowledge artifact holding, the extension. The variable %previousVersion refers to the version it is compared to. The FHIRpath expression SHALL evaluate to a boolean. The value true indicates the version of the ValueSet holding the extension is more recent than the ValueSet it compares to.
"""
- value[x] only Coding or string
- valueCoding from SortingAlgorithms (extensible)
ValueSet: SortingAlgorithms
Title: "Sorting Algorithms"
Description: "Algorithms used for sorting versions"
- $HL7#integer "Value represents an integer version."
- $HL7#date "Value represents an ISO8601 date."
- $HL7#string "Value represents a string and string sort should be used to order them."
- $HL7#integer "Value represents an integer version."
Lloyd McKenzie (Jan 11 2022 at 14:36):
integer is listed twice? We should also clarify string sort, as there are multiple string sorting algorithms (e.g. how are accented characters or upper and lower case ordered). Date should also allow for partial date. E.g. YYYY or YYYY-MM, but we might want to dictate that different schemes can't intermix. E.g. you can't use both YYYY-MM and YYYY-DDD or YYYY-MM-DD and YYYYMMDD (all of which are valid 8601 syntaxes)
Even HL7 is sort of moving away from SEMVER. We're going to be moving to something like 5.1.0-ballot1 and 5.1.0-draft. The 'sort' order of those is going to get messy...
Chris Moesel (Jan 11 2022 at 14:47):
Lloyd McKenzie said:
Even HL7 is sort of moving away from SEMVER. We're going to be moving to something like 5.1.0-ballot1 and 5.1.0-draft. The 'sort' order of those is going to get messy...
Actually, I think HL7 is moving closer to SEMVER, as this approach (adding a -label at the end) is the SEMVER way of doing pre-releases (as opposed to what HL7 was doing before, which violated SEMVER). See: https://semver.org/#spec-item-9.
The SEMVER spec does indicate how sorting should happen with pre-releases. See step 11 here. Now... we've chosen non-standard prerelease identifiers, so... you're right -- sorting might still be messy unless it just sort of works out by chance.
Lloyd McKenzie (Jan 11 2022 at 14:57):
We haven't talked about what our labels will be, so I guess we could theoretically avoid messing it up...
Brian Postlethwaite (Jan 21 2022 at 00:32):
I notice that the tracker for the operation to request for this passed (good) but still need answer to this to evaluate.
I like the valueset proposed.
And wonder where this extension would live, and what would happen if the extension value was different in different versions?
Lloyd McKenzie (Jan 21 2022 at 01:12):
If it's different in different versions, then I'd probably return an error. Extension could live at the root or on version. Preferences?
Brian Postlethwaite (Jan 24 2022 at 02:27):
Still no detail on how to call the API and request to resolve the latest resource, the disposition only covers the data to store about the algorithm, not how to call it.
I'm not a fan of the proposal in the tracker, do we need to log another tracker, or is there another already there?
I like the idea of an operation for this e.g.
[base]/ValueSet/$resolve?url=http://hl7.org/fhir/ValueSet/marital-status&version=4.0.1&mode=exact&status=active,retired
where mode could be exact, exactOrCurrent, current,
version is optional
status is optional and provides a list of statuses to consider
Lloyd McKenzie (Jan 24 2022 at 02:39):
If you have version, no need to call an operation - just do a search...
Lloyd McKenzie (Jan 24 2022 at 02:40):
Don't understand the purpose of mode=exact.
Brian Postlethwaite (Jan 24 2022 at 02:46):
Searching doesn't help you find the most recent, and doesn't consider statuses in a predictable way.
Brian Postlethwaite (Jan 24 2022 at 02:48):
And we'd need to change the version search parameter to something different, there is nothing in search-token about text values and modifiers.
Lloyd McKenzie (Jan 24 2022 at 02:50):
If you're specifying a version, you're not going to find the most recent.
My expectation was [base]/ValueSet/$most-recent?url=http//hl7.org/fhir/ValueSet/marital-status&status=active,retired. I don't see a need for other parameters. Response would either be a ValueSet instance or an OperationOutcome.
Brian Postlethwaite (Jan 24 2022 at 02:51):
I didn't see anything about a $most-recent anywhere, have I missed something?
Lloyd McKenzie (Jan 24 2022 at 02:54):
Actually, I guess the proposed name is $current-canonical. FHIR#35834
Brian Postlethwaite (Jan 24 2022 at 02:57):
Thanks, that's what I was missing, looks ok to me.
Brian Postlethwaite (Jan 24 2022 at 02:58):
So all resolved and I can implement that and try things out.
Thanks
Last updated: Apr 12 2022 at 19:14 UTC
