Support for searching via canonical references

[lmsurpre]

According to the spec, we should support searching canonical references as either a URI or a Reference.

Presently, we extract the Canonical value and store it in our X_STRING_VALUES table which serves both URI and Reference searches. However, we don't handle the |<version> part of it and we certainly don't support advanced reference stuff like chaining or includes/revincludes.

From https://www.hl7.org/fhir/search.html#versions:

Elements of type canonical may contain a version specific reference, but this version is different in both meaning and format to version specific references that might be found in a Reference:

   <valueSet value="http://hl7.org/fhir/ValueSet/example|3.0"/>
This version is a reference to the business version of the resource.

For canonical references, servers SHOULD support searching by Canonical URLs, and SHOULD support automatically detecting a |[version] portion as part of the search parameter and interpreting that portion as a search on the business version of the target resource. The modifier :below is used with canonical references, to control whether the version is considered in the search. The search:

GET {base]/Observation?definition:below=http:http://acme.com/some-profile
matches all of these element values:

http://acme.com/some-profile|1.0
http://acme.com/some-profile|1.1
http://acme.com/some-profile|2.0
The search:

GET {base]/Observation?definition:below=http:http://acme.com/some-profile|1
matches the first two element values.

And from https://www.hl7.org/fhir/search.html#uri

Note that for uri parameters that refer to the Canonical URLs of the conformance and knowledge resources (e.g. StructureDefinition, ValueSet, PlanDefinition etc), servers SHOULD support searching by canonical references, and SHOULD support automatically detecting a |[version] portion as part of the search parameter, and interpreting that portion as a search on the version.

[lmsurpre]

Need to start with unit tests and figure out where we are now. If estimate seems off after that, please update it.

Note: Work we did with "common tokens" (#1366) could conflict with this.

[lmsurpre]

A couple related HL7 JIRA issues (with corresponding discussion on chat.fhir.org):

• https://jira.hl7.org/browse/FHIR-30514
• https://jira.hl7.org/browse/FHIR-30697

[csandersdev]

As a related test case, please consider the following...

I have Measure resources that refer to Library resources and I would like to retrieve both resource types in a single call as in
/Measure?_id=MEASUREIDHERE&_include=Measure:depends-on:Library. The Measure resource is defined with canonical URL references as in the snippet below.

{
  "library": [
    "http://ibm.com/fhir/wh-cohort/Library/EXM101"
  ],
}

The Library resources can themselves depend on other Library resources. Ideally, I would be able to get all the related Libraryes in a single call with _include:iterate. I see that some work was done in that area under #1158 / #2141. Would need to make sure that those features work with canonical URL references as well.

[michaelwschroeder]

Design doc attached
issue772Design_v2.docx

[csandersdev]

@michaelwschroeder I don't see any mention of the _include:iterate case in the design doc. Will that be handled by this change or is that work for a later point?

[lmsurpre]

@csandersdev that should be taken care of in the current implementation.

[lmsurpre]

To QA this one, I uploaded the test resources from https://github.com/IBM/FHIR/tree/issue-2480/operation/fhir-operation-cqf/src/test/resources and ran some queries.

GET [base]/Measure?_include=Measure:depends-on:Library now returns both Measures and their dependent libraries.
GET [base]/Measure?_include=Measure:depends-on:Library&_include:iterate=Library:depends-on:Library now returns the measures, the libraries they depend on, AND the those libraries' transitive dependencies.

[lmsurpre]

I also confirmed that I can find a CodeSystems with url http://ibm.com/fhir/CodeSystem/test and version 1.0.0 via any of the following now:

• GET [base]/CodeSystem?url=http://ibm.com/fhir/CodeSystem/test
• GET [base]/CodeSystem?url=http://ibm.com/fhir/CodeSystem/test&version=1.0.0
• GET [base]/CodeSystem?url=http://ibm.com/fhir/CodeSystem/test|1.0.0

However, it is my opinion that the 3rd query there is above and beyond what is needed.
I helped to open https://jira.hl7.org/browse/FHIR-33203 for this and I expect it to go away in a future version, so I've definitely recommend users to search the url and version independently (the second variant listed above).

[lmsurpre]

I also ran this query which essentially looks for all the Libraries that are directly referenced by a Measure:

GET [base]/Library?_has:Measure:depends-on:status:missing=false

Interestingly, I couldn’t just do GET [base]/Library?_has:Measure:depends-on …even though I don’t care about the property of the Measure thats referencing this, just that it is referenced.