Stream: implementers
Topic: Search parameter for a positiveInteger
Craig Newman (Oct 23 2018 at 15:23):
gForge ticket 19340 (https://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemEdit&tracker_item_id=19340&start=0) concerns a search parameter for an element which can be a string or a positive integer (see gForge ticket #13185 for details on this decision). I'd appreciate guidance anyone has on setting up the search parameters for an element like this. Or alternatively, if anyone has comments on whether or not we even need to have a search for this element (Immunization.protocolApplied.doseNumber), we'll take those too.
gForge comment:
The dose-number search parameter is defined as a Token datatype - which I assume is to ensure that this is an exact match, however this behaviour isn't defined for positiveInteger (or even integer).
This either needs to be documented in search.html, or some other behaviour noted here.
Lloyd McKenzie (Oct 23 2018 at 17:39):
You'll probably need two search parameters - one that deals with each type
Craig Newman (Oct 23 2018 at 19:45):
So a search type of"token" for doseNumber when it's a string and "number" when it's a number?
In the spreadsheet (Search tab) are the paths then doseNumberString and doseNumberPositiveInt respectively?
Thanks
Lloyd McKenzie (Oct 23 2018 at 20:07):
That sounds correct. (Token is appropriate if you're looking for exact match behavior)
Grahame Grieve (Oct 23 2018 at 20:54):
how is the behavior different for the 2 types?
Craig Newman (Oct 23 2018 at 21:50):
Graham - not sure if your question is more technical or workflow related. In case it's workflow related, we would want the searches to behave the same (look for an exact match). The reason we need both string and positiveInteger is so that we can document either a number (2nd dose) or the fact that it's a booster or yearly recurring dose (tetanus or influenza)
Grahame Grieve (Oct 23 2018 at 21:55):
I understand why the element has the behavior it does. The question is, do you believe that there's grounds for seaching , for instance, doseSequence > 2 ? If there is, then you need a number search. But if they're just magic identifiers, and you just search for =, then token search is fine - though then I think, why not just have doseSequence be a string, and people can use a number when that's appropriate? Saves some machinery that doesn't bring value to any one?
Craig Newman (Oct 23 2018 at 22:08):
I can't think of a reason why you'd want to search for something like ">2". Historically, the element's always been a number. When we made the change, I think actually felt there wasn't going to be a compelling reason to do a search on this element, so we could just remove the search altogether if that's not bad form. Are there any best practices for removing existing search parameters on an STU resource?
So does a token search work with a number element? Number wasn't one of the data types listed in section 2.21.1.4.10 on the search page (https://www.hl7.org/fhir/search.html) and the gforge comment seemed to imply it didn't work.
@Joginder Madra - can you think of a reason why doseNumber couldn't be a string? How about seriesDoses?
Lloyd McKenzie (Oct 23 2018 at 22:17):
Best practice on removing search parameters on an STU resource is to just drop them. You're free to drop, add, rename, etc. at will. Only limitation is that if you're FMM4+, then you're expected to consult the community if making a breaking change (such as removing a search parameter).
Grahame Grieve (Oct 23 2018 at 22:18):
process wise, you can remove search parameters; implementers can still use them if they want (whether defined or not; defining them encourages consistency), and they can propose to bring them back in future versions. I'm not sure what the utility of searching on dose sequence number is; I suppose there might some usage when doing to data analysis, though I'd be interested if the idea appears in any quality measures (@Bryn Rhodes do you know?)
I agree that doseSequence is a usually a number but I can't think of any first principle reason why you couldn't have named items in the sequence, though I've not seen it. So you could make it a string and note that it's very usually a number. Personally, I'd prefer this than having a choice of integer or string (though other's might not agree?)
The table in section 2.21.1.4.10 is built automatically from what is done. We can add a note in the page somewhere clarifying that a token search applied to an integer element means that exact matches apply, and the comparators like less than etc don't apply.
Craig Newman (Oct 23 2018 at 22:21):
So is gforge #19340 actually incorrect that there is something wrong with the search parameter not being defined for positiveInteger?
gForge comment:
The dose-number search parameter is defined as a Token datatype - which I assume is to ensure that this is an exact match, however this behaviour isn't defined for positiveInteger (or even integer).
This either needs to be documented in search.html, or some other behaviour noted here.
Grahame Grieve (Oct 23 2018 at 22:29):
I think it's right that one of those two things needs to happen. I don't believe that clarifying the use of token search on an integer is a substantive change (@Lloyd McKenzie ?)
Lloyd McKenzie (Oct 23 2018 at 22:41):
The question is whether a reasonable interpretation of the previous specification was that token wasn't useable for numerics. If that's the case, then a clarification indicating how it could be used would be substantive.
Grahame Grieve (Oct 23 2018 at 22:50):
hmm. the language is ambiguous, but probably implies that you can only apply token to types Coding, CodeableConcept, Identifier, ContactPoint, code, boolean, uri, string. But I note that we already use it for the id type as well.
Joginder Madra (Oct 23 2018 at 22:52):
I struggle with a bona fide use case for searching on doseNumber that couldn't be addressed with positive integer.
Grahame Grieve (Oct 23 2018 at 22:53):
I don't understand. do you mean, 'storing a positive integer' or 'searching using > or <"?
Joginder Madra (Oct 23 2018 at 23:31):
the latter...searching for > or <. It hasn't been a use case that has been brought forward.
Grahame Grieve (Oct 23 2018 at 23:35):
thx, I think that makes sense. So the resolution is one of two things:
- change doseSequence to just a string, document that it's often an integer, and have a single search parameter of type token
- leave doseSequence as is, and figure out how whether we can squeeze documentation of token search on number into the spec for R4.
Tricky cause option #2 is FHIR-I decision, option 1 is PH decision... I think I prefer #1, not just on procedural grounds, but it's PH decision
Lloyd McKenzie (Oct 23 2018 at 23:57):
And #2 is a pretty tight squeeze.
Bryn Rhodes (Oct 24 2018 at 01:42):
@Grahame Grieve , QDM doesn't define a dose number, and QI-Core doesn't use the element (doseSequence in STU3). There are quality measures that look for specific doses, but they do so by date (because they're typically looking for an expected span of time between doses).
Craig Newman (Nov 01 2018 at 20:59):
The PH WG has voted to remove the search parameters from ImmunizationRecommendation to sync them up with Immunization and ImmunizationEvaluation where these elements don't appear in a search parameter. We don't think there are any use cases for doing searches like this. The WG does want to keep options for both positive Integer and string dose values. I will be committing this change before the deadline tonight.
Last updated: Apr 12 2022 at 19:14 UTC
