FHIR Chat · Why do IGs redefine search parameters from the base spec? · implementers

Stream: implementers

Topic: Why do IGs redefine search parameters from the base spec?

Lee Surprenant (Jun 22 2020 at 20:36):

I'm seeing some search parameter conflicts across IGs and I'm wondering if it would be possible for IGs to reference core spec search parameters instead of re-defining them.
For example, consider an IG that is trying to declare Organization.name to be searchable.
The base specification already defines a search parameter for this: http://hl7.org/fhir/SearchParameter/Organization-name
This has an expression like: Organization.name | Organization.alias

Lee Surprenant (Jun 22 2020 at 20:37):

Now US Core comes along and defines their own search parameter for this field: http://hl7.org/fhir/us/core/SearchParameter/us-core-organization-name

Lee Surprenant (Jun 22 2020 at 20:38):

with the same search parameter type and the same code

Lee Surprenant (Jun 22 2020 at 20:38):

but, interestingly, their expression is just Organization.name

Lee Surprenant (Jun 22 2020 at 20:38):

then PDEX Plan-Net comes along and defines their own search parameter for this field: http://hl7.org/fhir/us/davinci-pdex-plan-net/SearchParameter/organization-name

Lee Surprenant (Jun 22 2020 at 20:39):

which is once again back to Organization.name | Organization.alias

Lee Surprenant (Jun 22 2020 at 20:40):

I understand that IGs want to say which search parameters are required/optional/excluded in their CapabilityStatement, but is it possible for them to reference the base specification's search parameters instead of defining their own flavor of the same thing?

Eric Haas (Jun 22 2020 at 20:59):

in the case of US Core we have refined the SP with a bunch of conformance language to say which mods and comparatos are supported and whether ANDs or ORs or Chains are supported. This , along with the CapStatement, fully specifies the expectations for a server. One way they could conflict with one and another is if IG B has a looser conformance expectation than IG A. In that case the server would go stick with the stricter conformance.

Lee Surprenant (Jun 22 2020 at 21:05):

Are those customizations in the SearchParameter definitions themselves or just verbiage around how search should work in general?

Lee Surprenant (Jun 22 2020 at 21:06):

for example, i wouldn't expect ANDs, ORs, or Chains to be defined in the SearchParamter itself

Lee Surprenant (Jun 22 2020 at 21:11):

interesting, i guess it IS in the SearchParameter definition for US Core:

NOTE: This US Core SearchParameter definition extends the usage context of capabilitystatement-expectation extension to formally express implementer expectations for these elements:
- multipleAnd
- multipleOr
- modifier
- comparator
- chain

Lloyd McKenzie (Jun 22 2020 at 22:14):

Re-defining SearchParameters to constrain stuff like chaining is expected

Lloyd McKenzie (Jun 22 2020 at 22:15):

Typically, real system CapabilityStatements shouldn't point to the base FHIR SearchParameters. They should point to custom derived SearchParameters that define exactly what capabilities that particular system has.

Grahame Grieve (Jun 23 2020 at 21:48):

the us core search parameter says it is derived from the base search parameter. So you know that it's still the same search parameter

Grahame Grieve (Jun 23 2020 at 21:50):

I see that the pdex one isn't right.

Grahame Grieve (Jun 23 2020 at 21:51):

given the definition of derivedFrom, I think the IG publisher should create an error if the expression , type, base, or component is different

Paul Bastide (Jun 29 2020 at 20:12):

Note, my team found https://www.hl7.org/fhir/us/core/SearchParameter-us-core-procedure-date.html which redefines the base search spec. It's a bit problematic when it doesn't reference an existing field. I opened https://jira.hl7.org/browse/FHIR-27887. FYA...

Lee Surprenant (Jul 31 2020 at 16:09):

Grahame Grieve said:

given the definition of derivedFrom, I think the IG publisher should create an error if the expression , type, base, or component is different

Not sure if this is something thats needed or not, but I think it would have helped to prevent the above error (and at least one more) in that version of US Core.
However, I did a little experimenting on my side and noticed that it might be tricky to get this kind of check just right.

Lee Surprenant (Jul 31 2020 at 16:24):

For example, the base spec defines some search parameters across a bunch of resources (like date):
AllergyIntolerance.recordedDate | CarePlan.period | CareTeam.period | ClinicalImpression.date | Composition.date | Consent.dateTime | DiagnosticReport.effective | Encounter.period | EpisodeOfCare.period | FamilyMemberHistory.date | Flag.period | Immunization.occurrence | List.date | Observation.effective | Procedure.performed | (RiskAssessment.occurrence as dateTime) | SupplyRequest.authoredOn

Then, IGs like US Core redefine those SearchParameters for codes like date on a per-resource basis.
So, if you want to treat those as "matching" you need to do something hacky like assume the structure of the search expression, split on | and compare the relevant subsection.

Lee Surprenant (Jul 31 2020 at 16:37):

I wrote a little code that does that and it identified 3 remaining discrepencies between US Core and FHIR R4 (although I don't think these ones are too bad):

   SearchParameter with code 'onset-date' already exists with a different expression;
replacing url='http://hl7.org/fhir/SearchParameter/Condition-onset-date' and expression='Condition.onset.as(dateTime) | Condition.onset.as(Period)' with url='http://hl7.org/fhir/us/core/SearchParameter/us-core-condition-onset-date' and expression='Condition.onset.as(dateTime)'

   SearchParameter with code 'name' already exists with a different expression;
replacing url='http://hl7.org/fhir/SearchParameter/Organization-name' and expression='Organization.name | Organization.alias' with url='http://hl7.org/fhir/us/core/SearchParameter/us-core-organization-name' and expression='Organization.name'

   SearchParameter with code 'name' already exists with a different expression;
replacing url='http://hl7.org/fhir/SearchParameter/Location-name' and expression='Location.name | Location.alias' with url='http://hl7.org/fhir/us/core/SearchParameter/us-core-location-name' and expression='Location.name'

Lee Surprenant (Jul 31 2020 at 16:38):

@Eric Haas assuming these aren't purposeful, shall I open an issue for them?

Lee Surprenant (Jul 31 2020 at 16:40):

summary:
Condition.onset.as(dateTime) | Condition.onset.as(Period) vs
Condition.onset.as(dateTime)

Organization.name | Organization.alias vs
Organization.name

Location.name | Location.alias vs
Location.name

Eric Haas (Jul 31 2020 at 17:35):

You can make a tracker but be aware that the context for the US Core Search Parameters is stated in the IG:

"NOTE: These search parameters SHALL NOT be interpreted on their own as requirements for server: This section lists the search parameters definitions that are used within the capability statement to define the search capabilities expectations for the US Core Server. This is not a list of search requirements for the client or server."

in short basically to be able to computationally show what the conformance expectations for individual search parameters are...

They are all generated using a script and so can update those although I don't know what .alias means nor how that would be interpreted by conformance testing.

Grahame Grieve (Jul 31 2020 at 20:23):

I actually use the FHIRPath parser to parse them and look inside their structure

Lee Surprenant (Aug 03 2020 at 18:19):

I opened FHIR#28181 on US Core for the above discrepencies.
I can't tell from Grahame's comment whether its something that IG publisher is already checking or if it will in some future release, but IMHO it would be good to clean these up.

Ruth berge (Mar 23 2021 at 02:48):

I'm following on this issue although my question is slightly different. My FHIR server specifies a search parameter with expression": "Coverage.payor" for a base of Coverage. The Carin Blue Button specifies the exact same expression and path and description. The differences are with the name, url, version, contact information and jurisdiction. Other parameters are also mostly duplicates but may include a new derived from element. Should both search parameters be created in the system? If the search parameter already exists and is duplicate in certain key elements (and which ones are those?), then do we ignore it?

Lloyd McKenzie (Mar 23 2021 at 03:09):

Normally, IGs redefine search parameters so they can make clear expectations around support for particular comparators or modifiers. They also reference the base search parameter so you know it's the same thing, just slightly more constrained. There's no good reason for an IG to redefine something that already exists without both referencing it and somehow constraining it.

Ruth berge (Mar 23 2021 at 16:36):

That means that if the search parameter already exists and has the same - expression, xpath, definition and has no addition modifiers for searching like eq etc - then there is no reason to add it again? The url is the only item defined to require uniqueness so I am trying to identify which elements are used in creating the search.

Lloyd McKenzie (Mar 23 2021 at 17:44):

Correct - if you're not doing anything new, no reason to create a derivation

Last updated: Apr 12 2022 at 19:14 UTC