VN Core Deep Dive

Bundles and validation: where profiles meet real exchange data

A single profile describes one resource. Real systems exchange records, claims, prescriptions, lab results, and clinical documents. VN Core uses Bundles, examples, 5 CapabilityStatements, and 4 OperationDefinitions to turn constraints into end-to-end integration contracts.

TL;DR

Bundles are the natural test cases of an IG. Individual resources may validate while the reference graph still fails.
Read examples before writing adapters. Examples show how references, fullUrl, profile declarations, identifiers, and terminology work together.
Validation has multiple layers. Passing JSON parsing is not enough; validate base FHIR, profiles, terminology, references, and workflow rules.
CapabilityStatement is the API contract. It states which resources, search parameters, and operations a server/client must support.

1. Why read Bundles after Profiles

Many integration defects do not appear when each resource is validated in isolation. Patient, Coverage, and Claim may all validate individually while Claim references the wrong Coverage. A Composition may validate while a document Bundle fails to place Composition as the first entry. An Observation may validate structurally while using a code outside the use-case ValueSet. Bundles expose those system-level failures.

In VN Core, Bundles also explain Vietnam workflows. An outpatient BHYT package is not just a Claim; it needs Patient, Encounter, Coverage, Organization, Practitioner, diagnosis, procedure/service, and related cost data. An IPS summary is not only Composition; it needs sections and clinical resources referenced from the document.

2. Bundle types in VN Core

Document Bundle

A clinical document package with Composition as the first entry; suitable for EMR summaries, IPS, and personal health records.

VNCoreBundleIPS, Composition, DocumentReference

Transaction Bundle

Multiple resources submitted in one request with defined processing behavior; useful for synchronized create/update workflows.

Bundle.type = transaction

BHYT submission Bundle

Claim/Coverage/EOB and logical-model data used to bridge Vietnamese output-data workflows.

ExampleBHYTSubmissionOutpatient

Health credential Bundle

Health-record or credential packages for citizen apps or future VNeID-facing integrations.

ExampleBundleHealthCredential

3. Five validation layers

FHIR base

Does the resource satisfy R4 schema, datatype, base cardinality, and base invariants?

VN Core profile

Does the payload declare `meta.profile` and pass the right VN Core StructureDefinition version?

Terminology

Does each code use the correct `system + code + version`, ValueSet, and binding strength?

Reference graph

Do Bundle references point to valid resources and expected profiles?

Operation/business rule

Do workflow rules such as validate BHYT claim, generate IPS summary, or reverse submission return the expected outcome?

4. CapabilityStatement and OperationDefinition

CapabilityStatement answers what a FHIR system in VN Core scope must support: resources, profiles, search parameters, interactions, and operations. Vendors should read it before claiming that a server supports VN Core.

OperationDefinition describes operations beyond ordinary CRUD. In VN Core v0.6.0, operations such as vn-validate-bhyt-claim, vn-submit-bhyt-claim, vn-reverse-bhyt-claim, and vn-generate-ips-summary express workflows that cannot be described with only GET/POST/PUT on single resources.

Validation order for a production payload
1. Validate each resource against FHIR R4 base
2. Validate meta.profile against VN Core package version
3. Validate terminology bindings and identifier systems
4. Validate Bundle reference graph and fullUrl consistency
5. Run operation/business-rule validation for the workflow

5. Pre-go-live checklist

Every resource in the Bundle declares the correct `meta.profile` for the VN Core version being claimed.

Bundle `fullUrl` values are stable; internal references resolve correctly and do not depend on arbitrary ordering.

Document Bundles place Composition as the first entry and include the required sections/references.

Transaction Bundles are tested for idempotency, entry-level failures, and rollback/compensation behavior.

Terminology validation runs with the correct package and code-system versions.

The system CapabilityStatement is checked against actual API behavior, not only product documentation.

OperationOutcome responses are logged and returned with enough detail for integrators to fix payloads without guessing.

VNCoreBundle in the IG BHYT submission example VNCoreBundleIPS VN Core Server CapabilityStatement

VN Core Deep Dive Series

Move from overview to the IG in the right order.

These four pages orient readers before opening the normative IG: understand the artifact map, read Profiles, govern terminology, then validate Bundles and workflow payloads.

Artifact map

Profiles, terminology, capability, operations, examples, and package boundary.

How to read a Profile

Differential, snapshot, Must Support, slicing, binding, and extensions.

Terminology

CodeSystems, ValueSets, ConceptMaps, NamingSystems, and Coding.display.