Fix $validate fatal 5003 on Bundles with resource-less entries

[Brendan Kowitz (brendankowitz)]

Description

$validate silently fails for any Bundle containing an entry with no resource child — e.g. a transaction DELETE entry that carries only a request — when the Bundle also contains a Reference. It returns HTTP 200 with a fatal issue in the body, so the failure is invisible to status-code and exception telemetry. Observed live: service 5.0.22 → All OK; 5.0.53 → fatal 5003.

Root cause. Hl7.Fhir.Base changed ScopedNode.BundledResources() between 5.11.4 and 5.11.5:

// 5.11.4 (SAFE)
let resource = e.Children("resource").FirstOrDefault() as ScopedNode

// 5.11.5+ (BUGGY)
entry.Children("resource").First().ToScopedNode()
// ...plus a .Single() in the versioned-entry branch

The .First() is unguarded, so resolving a reference forces the bundle cache to build and throws InvalidOperationException: Sequence contains no elements. The legacy validator (Hl7.Fhir.Validation.Legacy) converts that into a fatal OperationOutcome issue with details code 5003, "Internal logic failure: Sequence contains no elements".

Why the pin didn't protect us. Directory.Packages.props already set Hl7FhirVersion=5.11.4, but that was only partially effective. Microsoft.Health.Fhir.Core and the shared Microsoft.Health.Fhir.Api carry a direct PackageReference to Hl7.Fhir.Base, so CPM pinned them. The version-specific R4/R4B/R5/Stu3.Api projects do not — they only ProjectReference Microsoft.Health.Fhir.Ignixa, which pulled Ignixa.Extensions.FirelySdk5 → Hl7.Fhir.Base >= 5.13.1. With no direct reference there is nothing for CPM to pin, so transitive highest-wins applied and a single Hl7.Fhir.Base.dll at 5.13.1 landed in the output, *.Web shipping artifacts included.

(A direct PackageReference pins per project, not transitively — adding it only to *.Api would still leave each *.Web leaf on 5.13.1. Verified empirically.)

The fix. Ignixa.Extensions.FirelySdk5 0.6.74 lowers its declared floor to 5.11.4, so the existing pin becomes effective again — no NU1605 suppression, no downgrade conflict. The 0.6.x line renames three serialization members, so IgnixaImportResourceParser is updated to match:

Meta.LastUpdated              ->  Meta.LastUpdatedOffset   (Meta auto-materializes, so
                                                            `??= new MetaJsonNode()` drops out)
ResourceJsonNode.MutableNode  ->  ToSourceNavigator().Meta<JsonNode>()
ReferenceJsonNode             ->  read "reference" off the raw JsonObject

5 files changed:

file	change
Directory.Packages.props	IgnixaPackageVersion 0.0.163 → 0.6.74
IgnixaImportResourceParser.cs	three API renames, no behavioural change
ProfileValidatorTests.cs	unit-level regression test
Bundle-TransactionWithResourcelessEntry.json	the breaking payload, as a reusable sample
BundleEdgeCaseTests.cs	E2E regression test

Related issues

Addresses AB#206224.

Testing

Two regression tests, at both layers.

Unit — ProfileValidatorTests.GivenABundleWithAnEntryThatHasNoResource_WhenValidating_ThenNoInternalLogicFailureIsReported, driving the existing public seam ProfileValidator.TryValidate(ITypedElement, string).

E2E — BundleEdgeCaseTests.GivenABundleWithAnEntryThatHasNoResource_WhenValidated_ThenNoInternalLogicFailureIsReturned, POSTing the Bundle to Bundle/$validate through the real HTTP pipeline. This layer matters specifically because the defect surfaces inside a 200 response body — an E2E assertion is what actually reflects what a caller observes. It lives with the other bundle-shape edge cases and carries the Bundle category trait.

The breaking payload is checked in as a reusable sample, TestFiles/Normative/Bundle-TransactionWithResourcelessEntry.json, following the existing bundle-sample convention rather than being inlined as an escaped string. Normative is the fallback folder for every FHIR version, so one file serves STU3, R4, R4B and R5.

Both tests use the same shape: a Patient carrying a managingOrganization reference (which forces the bundle cache to build), the referenced Organization, and an entry with only a request (DELETE) and no resource.

Both assert the absence of the crash, not the absence of all issues — ordinary validation warnings and errors remain allowed, so neither test becomes brittle. Both live in shared test projects and compile for STU3, R4, R4B and R5.

Proven to fail on the defect and pass on the fix:

• Before the bump (Hl7.Fhir.Base/5.13.1): the unit test fails on all four FHIR versions — Assert.DoesNotContain() Failure: Filter matched in collection. The E2E sample file was verified by loading it through Samples.GetJson and running it against the real ProfileValidator pinned to 5.13.1, producing exactly:

  Loaded sample, 1321 chars
  [Fatal/Exception] details='Internal logic failure: Sequence contains no elements'
  

• After the bump: Microsoft.Health.Fhir.R4.Web and the R4 test project both resolve Hl7.Fhir.Base/5.11.4, output dll 5.11.4+3605c91f, and:

suite	result
new unit test — STU3 / R4 / R4B / R5	passed
E2E project build — STU3 / R4 / R4B / R5	0 errors
ImportResourceParserParityTests	35 passed, 0 failed
all Import + Ignixa tests (R4)	52 passed, 0 failed
Microsoft.Health.Fhir.R4.Core.UnitTests (full)	1748 total, 0 failed, 1 skipped
Microsoft.Health.Fhir.R4B.Api.UnitTests (full)	1441 passed, 0 failed

The E2E test itself requires a deployed server (or a data store for the in-proc fixture), so it runs in CI rather than locally — but its sample file and assertion were verified end-to-end against the validator in both the defective and fixed configurations, as shown above.

The parser migration is covered by the existing parity suite, which asserts equivalence with the Firely parser — including the missing-meta case (GivenMissingMetaAndInvalidVersion_WhenParsedOnIncrementalLoad_ThenBothProvidersResetVersion), which is what makes dropping the MetaJsonNode initialisation safe.

FHIR Team Checklist

• Update the title of the PR to be succinct and less than 65 characters
• Add a milestone to the PR for the sprint that it is merged (i.e. add S47)
• Tag the PR with the type of update: Bug, Build, Dependencies, Enhancement, New-Feature or Documentation
• Tag the PR with Open source, Azure API for FHIR (CosmosDB or common code) or Azure Healthcare APIs (SQL or common code) to specify where this change is intended to be released.
• Tag the PR with Schema Version backward compatible or Schema Version backward incompatible or Schema Version unchanged if this adds or updates Sql script which is/is not backward compatible with the code.
• When changing or adding behavior, if your code modifies the system design or changes design assumptions, please create and include an ADR.
• CI is green before merge
• Review squash-merge requirements

Semver Change (docs)

Patch

Notes

• The unguarded .First()/.Single() is still present upstream in FirelyTeam/firely-net-sdk develop, so upgrading forward does not help — the test guards against drifting back onto an affected version.
• Only Hl7.Fhir.Base ≤ 5.11.4 is safe. v5.11.5, v5.11.7, v5.12.0 and v5.13.x all contain the unguarded call.
• This overlaps with the larger Ignixa 0.6.x adoption in Implement incremental Ignixa SDK adoption and FHIRPath seam #5776; this PR is the minimal subset needed to ship the fix to main now, and makes the same functional edits to IgnixaImportResourceParser as that branch.

[Robert Johnson (LTA-Thinking)]

Can we add a test that covers the issue the customer ran into? A bundle being validated with resource entries that contained references shouldn't report validation errors.

[Brendan Kowitz (brendankowitz)]

I believe it was this { "request": { "method": "DELETE", "url": "Observation/no-such-id" } } hitting the unguarded entry.Children("resource").First().ToScopedNode() on https://github.com/FirelyTeam/firely-net-sdk/pull/3099/changes#diff-872a636c2e24971aa1d68c2aac5ba903d2b34b3f82f738ce74e534bbd8a86ec5R238-R239

[Brendan Kowitz (brendankowitz)]

I'll add the breaking payload to the bundle e2e tests too

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.92%. Comparing base (8a49535) to head (87b5388).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5791      +/-   ##
==========================================
- Coverage   78.93%   78.92%   -0.02%     
==========================================
  Files        1016     1016              
  Lines       36940    36910      -30     
  Branches     5619     5616       -3     
==========================================
- Hits        29158    29130      -28     
+ Misses       6403     6398       -5     
- Partials     1379     1382       +3     

see 10 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.