FHIR Implementation Guide
Adopt FHIR R4 for ABDM and NHCX with profiles, bundles, validation, and implementation tools.
FHIR gives ABDM and NHCX a common data structure for health records and claim data. Use this guide before you build or validate an NHCX FHIR bundle. Then use Requests and Responses for use case payload rules.
Scope
This guide summarizes the NRCES guidance for FHIR adoption in ABDM and NHCX.
It covers FHIR concepts, bundle structure, profile use, validation, and tools.
The source applies to FHIR R4 version 4.0.1.
Key FHIR concepts
| Concept | Use |
|---|---|
| Resource | Model one health or claim data unit. |
| Bundle | Send multiple resources as 1 package. |
| Profile | Constrain a base FHIR resource for a context. |
| Extension | Add a data element when the base resource lacks it. |
| Terminology | Use standard code systems and value sets. |
| Validation | Check structure, cardinality, codes, invariants, and profile rules. |
| Interoperability | Exchange data with a common format and protocol. |
Resource categories
| Category | Examples |
|---|---|
| Clinical | Allergy, Condition, Procedure |
| Administrative | Practitioner, CareTeam, Device, Organization |
| Financial | Claim, Coverage, PaymentNotice |
Data types
| Type | Use |
|---|---|
| Simple type | Store one value, such as Boolean, integer, string, or date. |
| Complex type | Store a structured value, such as Address, HumanName, or Identifier. |
| Metadata type | Describe metadata for a resource. |
| Special type | Model healthcare details, such as Dosage, Reference, or Meta. |
Exchange paradigms
FHIR supports REST APIs, documents, messages, and services. Choose the paradigm that matches the workflow. NHCX uses FHIR bundles inside encrypted protocol payloads.
Bundle structure
Use a bundle to package related resources for exchange. Set the bundle type from the use case.
| Bundle type | Primary use | Structure |
|---|---|---|
document | ABDM clinical artefact | First entry is Composition; other entries support the document. |
collection | NHCX claim workflow | Entries contain claim, patient, coverage, diagnosis, and related resources. |
A bundle must include these key elements.
| Element | Rule |
|---|---|
Bundle.type | Set the processing purpose, such as document or collection. |
Bundle.timestamp | Set the creation date and time. |
Bundle.identifier | Set a unique identifier for traceability. |
Bundle.entry.fullUrl | Set the resource reference URL. |
Bundle.entry.resource | Add the actual FHIR resource. |
Implementation guides
A FHIR Implementation Guide tells you how to apply FHIR for a defined context. It can define profiles, extensions, value sets, examples, and narrative guidance. Use the applicable NRCES guide for ABDM or NHCX.
| Guide area | Count or scope |
|---|---|
| ABDM clinical artefacts | 7 clinical artefacts |
| ABDM billing artefacts | 1 billing artefact |
| ABDM core profiles | 38 profiles |
| ABDM terminology | 42 value sets |
| ABDM examples | 92 examples |
| NHCX health claim artefacts | 6 artefacts |
| NHCX core profiles | 11 profiles |
| NHCX terminology | 10 code systems and 17 value sets |
| NHCX examples | 51 examples |
Read a profile
| Profile area | How to use it |
|---|---|
| Statistics and references | Review the human-readable summary of profile changes. |
| Differential view | Review only the elements changed from the base resource. |
| Mandatory element | Include each element with cardinality 1..1 or 1..*. |
| Must Support | Process the element when it appears. |
Validation checks
Validate each resource before encryption. Check each item in this table.
| Check | What the validator checks |
|---|---|
| Structure | The resource has no extra or unknown elements. |
| Cardinality | Each element meets its minimum and maximum count. |
| Value domain | Each value matches its data type and allowed code. |
| Binding | Each Coding or CodeableConcept uses the required system and code. |
| Invariant | Each constraint and co-occurrence rule passes. |
| Profile | The resource conforms to the selected profile. |
| Business rule | The system applies reference, duplicate, and authorization checks. |
Java tooling
The source recommends HAPI FHIR for Java implementations. Use these HAPI FHIR modules for FHIR R4 work.
| Module | Use |
|---|---|
hapi-fhir-structures-r4 | Create and manipulate FHIR R4 resources. |
hapi-fhir-validation | Validate resources against rules and profiles. |
hapi-fhir-validation-resources-r4 | Load predefined R4 validation resources and profiles. |
Validation process
Load the package
Download the package.tgz file from the ABDM FHIR Implementation Guide.
Add it to the application class path, such as src/main/resources.
Use it for ABDM and NHCX profile and terminology validation.
Set the validation support chain
Add core FHIR structure definitions.
Add FHIR vocabulary resources, such as ValueSet and CodeSystem.
Add terminology support, cache support, and package support.
Register the validator
Register the HAPI FHIR validator module. Validate each resource before encryption. Review each error and warning.
Use the CLI when needed
Run the HL7 FHIR Validator CLI with the selected implementation guide.
java -jar path/to/validator_cli.jar file-name.json -ig ndhm.in#ig-versionUse the GUI validator when needed
Open https://validator.fhir.org.
Select the Options tab.
Add the ndhm.in implementation guide.
Choose the latest version.
Paste the resource and select Validate.
NHCX bundle reference
Use current /v1 endpoint paths from Requests and Responses.
| Use case | Flow | Bundle |
|---|---|---|
| Coverage Eligibility request | Provider to NHCX to payer | CoverageEligibilityRequestBundle |
| Coverage Eligibility response | Payer to NHCX to provider | CoverageEligibilityResponseBundle |
| Preauthorization request | Provider to NHCX to payer | ClaimBundle |
| Preauthorization response | Payer to NHCX to provider | ClaimResponseBundle |
| Predetermination request | Provider to NHCX to payer | ClaimBundle |
| Predetermination response | Payer to NHCX to provider | ClaimResponseBundle |
| Claim request | Provider to NHCX to payer | ClaimBundle |
| Claim response | Payer to NHCX to provider | ClaimResponseBundle |
| Request additional attachments | Payer to NHCX to provider | TaskBundle |
| Send attachments | Provider to NHCX to payer | TaskBundle |
| Payment request | Payer to NHCX to provider | TaskBundle |
| Payment response | Provider to NHCX to payer | TaskBundle |
| Status check | Provider or payer to NHCX | None |
| Reprocess request | Provider to NHCX to payer | TaskBundle |
| Reprocess response | Payer to NHCX to provider | TaskBundle |
| Search request | NHA to NHCX to payer | TaskBundle |
| Search response | Payer to NHCX to NHA | TaskBundle |
Reference tools
| Area | Tool or library |
|---|---|
| FHIR standard | HL7 FHIR R4 index |
| ABDM guide | ABDM FHIR Implementation Guide |
| NHCX guide | NHCX profiles in the ABDM FHIR Implementation Guide |
| Java | HAPI FHIR |
| .NET | Firely .NET SDK |
| JavaScript | FHIR Kit Models |
| Validator | HL7 FHIR Validator CLI |
| Schema | JSON Schema |
Sources
- fhir-implementation-guide-abdm-nhcx.md (NHCX sandbox portal)