FHIR Chat · Clarification on `url` search parameter · implementers

Stream: implementers

Topic: Clarification on `url` search parameter

Lee Surprenant (Aug 17 2021 at 19:30):

https://build.fhir.org/search.html#uri contains a section on uri parameters that says:

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.

I think that is saying that servers should automatically handle ValueSet?url=http://acme.org/fhir/ValueSet/123%7C1.0.0 the same as ValueSet?url=http://acme.org/fhir/ValueSet/123&version=1.0.0.

1. Am I interpreting the spec right?
2. Why recommend this special behavior for this one search parameter or type uri and is there anything in their SearchParameter definitions to indicate their special-ness?

Lee Surprenant (Aug 17 2021 at 19:36):

The other interpretation I could imagine for this text is that its actually referring to uri search parameter which target canonical references (like the _profile search parameter). This interpretation makes a lot more sense to me, but the preceding text in this latest draft seems to favor the other interpretation:

The search type uri is used with elements of type uri and url. The type reference is used for the types Reference and canonical.

Josh Mandel (Aug 17 2021 at 20:32):

We say something similar at https://build.fhir.org/search.html#versions --

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.

But I agree @Lee Surprenant: for uri, how do you know when to apply this logic? It seems like you can't know to apply this logic based on the search param definition itself; rather, the logic depends on the value supplied. But how do you tell if a uri parameter "refers to the Canonical URLs of the conformance and knowledge resources"? This is an open set. Maybe you just... see if refer to the canonical URL of a conformance/knowledge resource that your servers supports in some way?

Josh Mandel (Aug 17 2021 at 20:33):

I'm looking for examples to understand where this might apply... but yours (?url=) is the best I can find. Maybe it's the only one?

Josh Mandel (Aug 17 2021 at 20:36):

OK, I guess:

for uri parameters that refer to the Canonical URLs of the conformance and knowledge resources

Just essentially means: "search parameters of type 'uri' that index some instance of http://build.fhir.org/definition-definitions.html#Definition.url or http://build.fhir.org/canonicalresource-definitions.html#CanonicalResource.url"

Josh Mandel (Aug 17 2021 at 20:36):

Agreed it'd be really nice to mark these SearchParameters with some indication of their special-ness.

Lee Surprenant (Aug 17 2021 at 20:37):

i'm not even sure i understand why that would be needed. can't clients just use the url=&version= variant?

Lee Surprenant (Aug 17 2021 at 20:38):

like i said the interpretation that makes more sense to me would be if it applied to uri search parameters which target elements of type canonical, because there we actually do need this kind of behavior to be smart about the version

Lee Surprenant (Aug 17 2021 at 20:39):

are you pretty sure its about params like ValueSet?url= and not [Resource]?_profile= ?

Josh Mandel (Aug 17 2021 at 20:39):

Lee Surprenant: i'm not even sure i understand why that would be needed. can't clients just use the url=&version= variant?

I totally agree with this point, and the examples at https://www.hl7.org/fhir/references.html#canonical corroborate

Josh Mandel (Aug 17 2021 at 20:41):

Lee Surprenant: are you pretty sure its about params like ValueSet?url= and not [Resource]?_profile= ?

No. I'm just reading like you; I don't understand the intent here.

Lee Surprenant (Aug 17 2021 at 20:41):

ok, great. i'm glad its not just me :-)

Josh Mandel (Aug 17 2021 at 20:43):

Do you know why _profile SearchParam is of type uri instead of reference?

image.png

at http://build.fhir.org/search.html#table documents that this is expected, but I can't tell/recall why.

Lee Surprenant (Aug 17 2021 at 20:45):

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

Lee Surprenant (Aug 17 2021 at 20:46):

I just left a comment to similar effect on this "applied" jira issue

Josh Mandel (Aug 17 2021 at 20:46):

The other interpretation I could imagine for this text is that its actually referring to uri search parameter which target canonical references (like the _profile search parameter). This interpretation makes a lot more sense to me...

Reviewing up to this point: I agree. I think

The search type uri is used with elements of type uri and url.

should say

The search type uri is used with elements of type uri, [url,??] and canonical.

to match the table and current usage.~~

Lee Surprenant (Aug 17 2021 at 20:47):

My current opinion:

• _profile should be of type reference
• the language about handling certain uri parameters specially should be stricken

Josh Mandel (Aug 17 2021 at 20:48):

Phew, this is fun. I agree, based on the resolution of FHIR-30514

Lee Surprenant (Aug 17 2021 at 20:48):

yes, definitely didn't intend to go down this rabbit hole today :-)

Josh Mandel (Aug 17 2021 at 20:49):

One more addition to your current opinion: the "Y" in that table I screenshotted should be erased.

Lee Surprenant (Aug 17 2021 at 20:50):

yes, I agree

Josh Mandel (Aug 17 2021 at 20:53):

I'll submit a Jira issue to capture these, since we might not review all the notes on an already applied isssue.

Lee Surprenant (Aug 17 2021 at 20:54):

thanks, that will be great. i was gonna see if anyone can explain what we're missing first, but i think a ticket is smart so we don't forget

Gino Canessa (Aug 17 2021 at 20:56):

Probably also relevant is FHIR#30697 .
edit: note that this has actually been voted on, but not updated (I put a note in the FHIR-I stream).

Josh Mandel (Aug 17 2021 at 20:58):

Submitted FHIR-33203 -- though I'll note it assumes that other than _profile, there's nowhere else that a uri-type searchparam is used to index a canonical-type element.

Brian Postlethwaite (Sep 03 2021 at 05:01):

One question I have directly related to this is how can we "resolve" a canonical with versioning rules through the API?
(desiring just the relevant resource, not all versions, and latest if not specified)

Lee Surprenant (Sep 03 2021 at 11:29):

Sorry Brian, I'm not quite clear what you mean

Lee Surprenant (Sep 03 2021 at 11:35):

Maybe you mean as a client you have a resource that has a canonical reference to a definitional resource and now you want to just go "read" that resource from somewhere?
I think you have two options in such cases: go try to look it up in some registry OR try searching for it on a FHIR server (is there a difference?)
If we went with the proposal in FHIR-33203 then to look it up on a FHIR server the client would need to be able to parse the canonical url into is url and version parts so it can do a search like GET [definitionalResourceType]?url=xx&version=yy.

Brian Postlethwaite (Sep 06 2021 at 04:54):

Is the lookup in some registry different to searching on the FHIR server - is there a defined way for that?
If there is no version in the canonical, then you just search for that, then all versions will be returned, not just the latest active one (or whatever the rules should be)

Brian Postlethwaite (Sep 06 2021 at 05:17):

Having the spec define how to resolve canonicals by a server, and not just general search to make the server do the hard work rather than the client is desirable...

Hank Lenzi (Sep 06 2021 at 11:21):

@Brian Postlethwaite
If I understood you correctly, you want to either take a look at what the "Content-Location" header of your GET request says, to see version history:
❯ curl -v -H "Content-Location" http://fhir.hl7fundamentals.org/r4/Patient/500

• Trying 34.220.222.151:80...
• TCP_NODELAY set

• Connected to fhir.hl7fundamentals.org (34.220.222.151) port 80 (#0)

  GET /r4/Patient/500 HTTP/1.1
  Host: fhir.hl7fundamentals.org
  User-Agent: curl/7.68.0
  Accept: /

• Mark bundle as not supporting multiuse
  < HTTP/1.1 200 OK
  < X-Powered-By: HAPI FHIR 3.7.0-SNAPSHOT REST Server (FHIR Server; FHIR 4.0.0/R4)
  < ETag: W/"18"
  < Content-Location: http://fhir.hl7fundamentals.org/r4/Patient/500/_history/18

OR
you want to tweek te search parameters, as described in: https://hl7.org/fhir/r4/search.html
HTH

Josh Mandel (Nov 29 2021 at 21:59):

I wound up withdrawing FHIR-33203 because the core change to the type of _profile in https://build.fhir.org/resource.html#search was applied (... a couple of months after being marked as applied :-)).

That said, I'm still unclear on why the "url" search params like

GET /ValueSet?url=https://myvs.example.org

are defined with SearchParameter.type of uri instead of referenence. @Lloyd McKenzie do you remember the rationale for this?

Lloyd McKenzie (Nov 29 2021 at 23:11):

If you're searching by the URL property of ValueSet, there's no reference to resolve. You're just searching by the string property. In theory, you might want to use the 'above' or 'below' search modifiers. E.g. "Find me all valuesets with a url base of http://hl7.org"

Lloyd McKenzie (Nov 29 2021 at 23:12):

With reference, you're chasing a reference (canonical or Reference) to some other resource and things like 'identifier' come into play.

Josh Mandel (Nov 30 2021 at 01:28):

But we explicitly want things like piped version number syntax to work here, and that syntax is defined on reference type search parameters... Put another way, why is "_profile" a reference when other canonicals are not?

Lloyd McKenzie (Nov 30 2021 at 02:16):

No, we don't. It can't be used here. The ValueSet.url isn't of type 'canonical'. If you want to search for a ValueSet by url + version, then you need to do it this way: ValueSet?url=http://foo&version=bar

Lloyd McKenzie (Nov 30 2021 at 02:17):

On the other hand, you can do this: StructureDefinition.valueset=http://foo|bar

Lloyd McKenzie (Nov 30 2021 at 02:18):

That's because StructureDefinition.snapshot.element.binding.valueset has a type of canonical, not a type of uri.

Grahame Grieve (Nov 30 2021 at 02:54):

I'm not entirely sure we don't want it work, but it certainly doesn't, and making it work would have pain, for sure. I'd vote against it as a server implementer

Josh Mandel (Nov 30 2021 at 04:25):

it can't be used here

Gah, sorry for the confusion about canonical (I jumped back into this thread after a related subject arose on FHIR-I call today without reminding myself what I was talking about!). But for uri type search parameters we do say:

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

at http://build.fhir.org/search.html#uri -- which suggests that GET ValueSet?url=http://foo|v1 "SHOULD" work. If it's unreliable and even Grahame would vote against supporting this and we have a workaround, it sure seems like we should eliminate this guidance

Lloyd McKenzie (Nov 30 2021 at 14:22):

@Josh Mandel can you raise a tracker item?

Josh Mandel (Nov 30 2021 at 18:55):

FHIR-34398

Lee Surprenant (Nov 30 2021 at 22:06):

What about this part of FHIR#33203 ?

• The "Y" indicating that URIs can be used to index "canonical" elements should be removed from the "Cross-map between search parameter types and Data types:" table at http://build.fhir.org/search.html#table

Did we ever find a case where a search parameter of type uri is used to index an element of type canonical?

Last updated: Apr 12 2022 at 19:14 UTC