1. FHIR & NP Core basics

This chapter is for developers and testers at Nepali health software companies who are new to FHIR, or who know FHIR but not NP Core. If you already build FHIR APIs, skim it and go on to Validate your first Patient.

What is FHIR?#

FHIR (Fast Healthcare Interoperability Resources, pronounced "fire") is an HL7 standard for exchanging health data over ordinary web technology: HTTPS, JSON or XML, and REST.

FHIR breaks health information into small, well-defined building blocks called resources. Each resource has a type and a fixed set of elements:

A resource is a JSON document. This is a minimal (not yet NP Core conformant) Patient:

{
  "resourceType": "Patient",
  "name": [ { "family": "Shrestha", "given": [ "Aarav" ] } ],
  "gender": "male",
  "birthDate": "1990-05-15"
}

The NP Core IG uses FHIR R4 (version 4.0.1). Make sure your libraries and tools target R4, not R4B or R5.

Elements, cardinality and data types#

Every element has a cardinality written min..max:

• 0..1 optional, at most one value
• 1..1 required, exactly one value
• 0..* optional, may repeat (JSON array)
• 1..* required, at least one value

Repeating elements are always JSON arrays, even if you only have one value — "name": [ {...} ], never "name": {...}. Elements have data types: string, date, dateTime, code, Coding, CodeableConcept, Identifier, Reference, Address and so on.

Codes and terminology#

Coded elements use a system (a URI naming the code system) plus a code:

"code": {
  "coding": [ { "system": "http://loinc.org", "code": "8480-6", "display": "Systolic blood pressure" } ]
}

A value set is a list of allowed codes for an element; the profile binds an element to a value set with a strength (required, extensible, preferred or example). You will see binding problems reported in the terminology category.

Identifiers#

An Identifier has a system (a URI for the namespace that issued the number) and a value:

{ "system": "http://fhir.digitalhealth.gov.np/core/NamingSystem/nepal-health-id", "value": "12345678901" }

The system must be exactly the URI given by the IG — one wrong character and the receiver will not recognise the identifier. Chapter 7 lists all Nepali identifier systems.

References#

Resources point to each other with Reference:

"subject": { "reference": "Patient/ExampleNPCorePatient" }

What is an Implementation Guide (IG) and a profile?#

Base FHIR is deliberately flexible: almost every element is optional. A country or programme publishes an Implementation Guide that tightens the rules for its context. The tightened version of a resource is called a profile (technically a StructureDefinition).

The NP Core Implementation Guide (np.core version 1.0.0) is Nepal's national baseline, published by the Ministry of Health and Food Safety. It:

• makes some elements required (for example a Patient SHALL have a Nepal Health ID),
• marks elements as Must Support (if you have the data you SHALL send it),
• defines Nepali identifier systems (Health ID, National ID, NHFR, NHWR, council registrations),
• adds extensions for Nepal-specific data (province/district/local level codes, Bikram Sambat dates, caste/ethnicity),
• defines code systems and value sets (facility types, administrative locations, and more),
• adds rules (invariants) such as "a practitioner needs a council registration or NHWR code".

The IG's canonical base is http://fhir.digitalhealth.gov.np/core. The official documentation is at https://hiecore.mohp.gov.np/ig/en/.

Claiming a profile with meta.profile#

An instance says which profile it conforms to in meta.profile. For a Patient:

{
  "resourceType": "Patient",
  "meta": { "profile": [ "http://fhir.digitalhealth.gov.np/core/StructureDefinition/np-core-patient" ] }
}

The sandbox uses meta.profile to pick the profile automatically. You can also choose the profile yourself in the validator.

NP Core resource profiles#

Conformance language#

The IG uses the usual RFC 2119 words:

• SHALL / SHALL NOT — mandatory. Breaking it means you are not conformant (shows as an error).
• SHOULD / SHOULD NOT — strongly recommended; deviate only with a good reason (often a warning).
• MAY — optional.

Must Support means: a system that produces data SHALL populate the element when it has the data, and a system that consumes data SHALL process it without error. It does not by itself make the element mandatory — required elements are those with minimum cardinality 1. See Conformance requirements in the IG.

What does the sandbox check?#

When you validate a resource, the sandbox runs the official HL7 FHIR validator with the NP Core package loaded. It checks:

1. Base FHIR R4 rules — JSON/XML syntax, element names, data types, base cardinalities.
2. NP Core profile rules — required elements, slices, fixed values, extensions, invariants.
3. Terminology — whether codes come from the bound value sets.

Every issue is then explained in plain language: what it means, why NP Core requires it, how to fix it, and a link to the exact IG page.

Glossary#