SUSHI prioritizes FHIR Core over Extensions package, contradicting Grahame's guidance

[mechanik-daniel]

Bug: SUSHI prioritizes FHIR Core over Extensions package, contradicting official FHIR guidance

Summary

SUSHI's current implicit package loading order gives FHIR Core packages higher priority than Extensions packages, which contradicts the official guidance from Grahame Grieve in the FHIR chat. This causes Extensions package definitions to be overridden by Core package definitions during resolution.

Expected Behavior

According to FHIR chat guidance from Grahame Grieve, when resolving extensions that exist in both the FHIR Core package and the Extensions package, tools should prefer the Extensions package definitions over the Core package definitions.

Key exchange from the chat:

Chris Moesel: "Should tools prefer the extension in the release or the extension in the hl7.fhir.uv.extensions package?"
Grahame Grieve: "(b) prefer the extension package definitions"

Actual Behavior

SUSHI currently loads packages in this order:

1. Automatic dependencies (Extensions, Terminology, Tools) - lowest priority
2. User-configured dependencies - medium priority
3. FHIR Core package - highest priority

This means Core definitions override Extensions definitions, which is the opposite of the intended behavior.

Root Cause

In src/utils/Processing.ts lines 370-372, the comments state:

// Load automatic dependencies first so they have lowest priority in resolution
await loadAutomaticDependencies(fhirVersionInfo.version, dependencies, defs);
// Then load configured dependencies, with FHIR core last so it has highest priority in resolution
await loadConfiguredDependencies(dependencies, fhirVersionInfo.version, config.filePath, defs);

Combined with the byLoadOrder(false) sort in FHIRDefinitions.ts (reverse load order), this gives precedence to packages loaded last (Core) over packages loaded first (Extensions).

Reproduction Case

The language extension binding demonstrates this issue:

• Extensions package (hl7.fhir.uv.extensions.r4): Defines binding description as "IETF language tag"
• Core package (hl7.fhir.r4.core): Defines binding description as "A human language."
• Current result: Core wins, showing "A human language."
• Expected result: Extensions should win, showing "IETF language tag"

Proposed Solution

Modify the loading order to treat automatic/implicit packages as a special exception that should have higher priority than Core, while preserving the normal expectation that Core has highest priority over regular user packages.

Recommended approach:

1. Load automatic dependencies (Extensions, Terminology, Tools) first
2. Load user-configured dependencies second
3. Load FHIR Core package third
4. Re-load automatic dependencies last (highest priority)

This targeted solution ensures that:

• ✅ Automatic packages (Extensions, etc.) get precedence over Core per FHIR guidance
• ✅ Core still maintains precedence over regular user packages (preserving existing expectations)
• ✅ User packages maintain their current priority relative to each other
• ✅ Minimal disruption to existing behavior for non-implicit packages

Alternative approach:
Modify the resolution sorting in FHIRDefinitions.ts to add special precedence rules that explicitly prioritize automatic packages over Core, regardless of load order.

FHIR Chat Reference

Full thread: https://chat.fhir.org/#narrow/stream/179239-tooling/topic/New.20Implicit.20Package/near/325318949

Environment

• SUSHI version: 3.16.5
• FHIR version: R4
• Packages involved: hl7.fhir.r4.core vs hl7.fhir.uv.extensions.r4

[cmoesel]

Thank you for filing this. I think the reason we haven't changed this in SUSHI yet is that we never actually got to a clear resolution (at least not in that thread). If you look further down, you'll see this exchange:

Chris Moesel: "Was there a final ruling on rules for resolution? For extensions that were published w/ R4, what definition wins -- the original version published in R4, or the latest version published in the extensions package?"
Grahame Grieve (after quoting "Was there a final ruling on rules for resolution?"): "no, that's why I haven't done it for the other versions yet; will need discussion in committee"

There is no further update on that in the thread. So... the only thing that was determined for sure was that the extensions package has priority for R5 -- which happens automatically because R5 doesn't actually include any extensions in its package. The question of priority over FHIR R4 core was not yet resolved at that time and still needed discussion.

So... I think this requires further research to determine if that decision has yet been made for FHIR R4. I'll ask in the thread.

[cmoesel]

Grahame has just confirmed that it should be latest. In your solution, you suggest this load order:

1. Load automatic dependencies (Extensions, Terminology, Tools) first
2. Load user-configured dependencies second
3. Load FHIR Core package third
4. Re-load automatic dependencies last (highest priority)

Is there a reason you suggested loading and reloading the automatic dependencies? Why not just do this:

1. Load user-configured dependencies
2. Load FHIR Core package second
3. Load automatic dependencies last (highest priority)

[mechanik-daniel]

Thanks you for confirming this with Grahame, it's good to have a final ruling on this.
My thinking was that with the current order, user dependencies override the extension package, and that actually makes sense so I didn't want to break it. But thinking about it again, my suggestion did not solve this issue at all.

So, it should be either -
a. Extension package overrides all (easiest to implement per your suggestion, risk of breaking some edge cases)
b. Prioritize at the resource-level rather than package-level, e.g. Extension package resources only override resources that exist in Core, but if a resource exists in user package and extension package only (no Core conflict) then user wins. Might be too complicated and unjustified.

In FUME (more specifically, fhir-package-explorer) we have implemented b, but to be honest I don't know if there's a real use case where this actually matters :)

[cmoesel]

I'm not sure we need to worry about user packages overriding extensions from the extensions pack. All of the extensions in the extensions pack (except 2) are in the FHIR core namespace http://hl7.org/fhir/. I don't think it's legal for a user package to redefine anything in that namespace. (The two non-core extensions are in the http://fhir-registry.smarthealthit.org/, so maybe we'd need to allow for a SMART package to override them, but I'm not sure if that's plausible either.)

I'm less sure about the other automatic dependencies (e.g., terminology, tools), but I'd guess that most things in those should not be redefined in user packages either.

The thing we do want to be sure we support is users overriding automatic dependencies with a different version of the same dependency. For example, right now extensions pack 5.2.0 is loaded automatically, but if a user specifically calls out extensions pack 5.1.0 as a dependency, then we should load that instead. SUSHI does this today, but I'll need to make sure that still works if we change load order.

I'll look into it.

[mechanik-daniel]

While you are looking at it, there's a caveat you should be aware of.
While the diff from the extension package is to be preferred over Core in R4, the snapshot isn't because it was generated using R5.

One big difference this makes is that the extension package snapshots have the Extension.id profiled to the id datatype, while in R4 it should be string juat like any Element.id.

This can be solved by regenerating the snapshot using R4 instead of trusting the provided one...

I don't know if this was done on purpose or not and if there are any other differences affected by this, just a heads up (and one more thing you may want to discuss Grahame with...)

[cmoesel]

Oh. That's interesting. I hadn't noticed that before, but I see it now. I'm not sure if that will affect any of the SUSHI processing or not. We don't have our own snapshot generator, so regenerating snapshots isn't really an option for SUSHI. I may have to just see what happens.

Since you found the issue, I'd recommend you go ahead and report it on Zulip. I think the best place would be the FHIR-cross-version-issues channel. Both Grahame and Gino should see it there and be able to provide some insight (and/or correct it).

[cmoesel]

OK. Check out #1605 for a fix to this issue.

[cmoesel]

@mechanik-daniel - SUSHI 3.17.0 now loads the extension pack last, giving it the highest priority in resource resolution.