Interoperability contracts between health-data partners tend to name the FHIR version, the profile package, and the payload transport. They frequently omit the Bundle-layer validation obligation, and the omission becomes visible only when a rejection has already landed. Naming Bundle validation as an explicit contract term closes the gap before it opens.
Contract language is where the shared expectations become auditable. Related architecture material sits under the FHIR architecture archive for teams drafting long-lived agreements.
The Clauses Worth Including
An interop contract that names Bundle validation typically carries a small set of explicit clauses:
- Sender obligation — every outbound Bundle is validated against the pinned profile package before shipment.
- Receiver obligation — every inbound Bundle is validated on receipt, with the same profile package.
- Package version pinning — both sides pin the exact profile package version and coordinate upgrades.
- Rejection response format — rejections return an
OperationOutcomewith severity, code, and location per issue. - Audit-trail retention — both sides retain validator verdicts for the contract's retention period.
- Escalation path — a named process for issues that recur beyond an agreed threshold.
Each clause corresponds to an operational discipline that would otherwise be implicit. Contracts that leave the disciplines implicit tend to rediscover them during compliance reviews.
The Version-Pinning Discipline
Profile packages evolve, and contracts that reference US Core without pinning a version drift as the maintainer publishes new releases. A well-drafted clause names the package version explicitly and schedules upgrades as coordinated events with both sides shipping the same package on the same date.
This is the single clause that prevents the largest class of avoidable rejections. A quick pass through the site's Bundle JSON check illustrates the structural side of what a pinned package will enforce.
The Rejection Response Discipline
Contracts should name the response format for rejections. Receivers that return prose-only rejections cost the sender interpretation work; receivers that return structured OperationOutcome responses cost the sender only the fix work. The difference compounds over months of operational traffic. For the acceptance-side view of the same issue, vendor Bundle acceptance criteria for health data programs collects the common criteria.
The Audit-Trail Discipline
Contracts should name what the audit trail records and how long it is retained. The clauses that survive compliance review carry Bundle ID, validator version, profile package version, timestamp, verdict, and report reference. For the storage-side detail, audit trails grounded in structural Bundle validation covers the retention model.
The Escalation Path Discipline
Even the best-drafted contract needs an escalation path for issues that recur. Programs that leave escalation implicit end up escalating late. The bilateral review cadence is the common pattern: quarterly meetings that read the aggregate rejection report and adjust the acceptance criteria if drift has appeared.
Contract Language That Ages Well
Contracts that read cleanly two years later share three properties: they name the profile package version, they name the validator response format, and they name the escalation path. Contracts that survive on institutional memory age poorly and become the argument in a future compliance review.
Naming Bundle validation as a contract term is neither adversarial nor administrative overhead. It is the shared language that lets both sides agree on what a valid exchange looks like.
Sources
- HL7 US Core Implementation Guide STU 6.1.0 - HL7 US Core Implementation Guide STU 6.1.0, canonical profile package referenced in interop contracts