Vitalis

The Pulse of Data Integrity.

Vitalis (vitalis-fhir) is a high-performance, open-source TypeScript library providing strict, clinical-grade FHIR R4 validation powered by Zod. Works in both frontend and backend environments — React, Vue, Angular, Next.js, Node.js, and Edge/Serverless.

Why Vitalis?

In medicine, Vitalis refers to that which is necessary for life. In healthcare tech, data integrity is the lifeblood of the system.

• Clinical-Grade Strictness: Enforces exact R4 enums, required cardinality (1..1), and official FHIR dateTime regex formats.
• Strict + Extension Hybrid: No .passthrough(). Noise is stripped; valid hospital custom data via FHIR extension is preserved.
• Choice Element Validation: Enforces [x] constraints (e.g., medication[x]) with Zod superRefine.
• Zero-Hallucination Boundary: Guarantees AI agents reason over pure, clean FHIR resources.
• Full Type Inference: Zod schemas export inferred TypeScript types — no manual interfaces needed.
• Isomorphic: Dual ESM + CJS output. Works everywhere — browser, Node.js, Edge functions.
• Regional Support: Out-of-the-box support for Saudi Arabia (KSA-Core / NPHIES) with dedicated identity validation (National ID, Iqama).

Installation

Beta Release — APIs are stable but may evolve. Use in production at your own discretion.

npm install vitalis-fhir@beta zod

Supported Resources (R4) - Phase 1 Complete (30)

| Domain | Resources | |---|---| | Clinical | Observation, Condition, AllergyIntolerance, Procedure, ClinicalImpression, FamilyMemberHistory, RiskAssessment | | Pharmacy | Medication, MedicationRequest, MedicationDispense, MedicationAdministration, MedicationStatement | | Diagnostics | DiagnosticReport, Specimen, ImagingStudy | | Demographics | Patient, Practitioner, Organization, PractitionerRole, RelatedPerson | | Care Planning | CarePlan, Goal, ServiceRequest | | Admin/Preventive | Immunization, Encounter, Composition, DocumentReference, Location, Coverage, Appointment |

Usage

Basic Validation (Works on Frontend & Backend)

import { ObservationSchema } from 'vitalis-fhir/r4';

const result = ObservationSchema.safeParse(emrPayload);

if (!result.success) {
  console.error('Validation Failed:', result.error.format());
} else {
  const observation = result.data; // Fully typed FHIR Observation
}

React (Frontend) — Validate before submitting a form

import { ConditionSchema } from 'vitalis-fhir/r4';

function onSubmit(formData: unknown) {
  const result = ConditionSchema.safeParse(formData);
  if (!result.success) {
    setErrors(result.error.format());
    return;
  }
  await api.post('/conditions', result.data);
}

Node.js (Backend) — Validate incoming EMR webhooks

import { MedicationRequestSchema } from 'vitalis-fhir/r4';

app.post('/webhook', (req, res) => {
  const result = MedicationRequestSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json(result.error.format());
  }
  await processOrder(result.data); // Clean, typed FHIR MedicationRequest
});

MedicationRequest — medication[x] Choice Validation

// ❌ Fails — must have exactly ONE of the two
MedicationRequestSchema.safeParse({ ..., medicationCodeableConcept: {...}, medicationReference: {...} });

// ✅ Passes
MedicationRequestSchema.safeParse({ ..., medicationCodeableConcept: { coding: [...] } });

Custom Hospital Data via FHIR Extensions

AllergyIntoleranceSchema.safeParse({
  resourceType: 'AllergyIntolerance',
  patient: { reference: 'Patient/123' },
  // Hospital custom data must be in 'extension' — validated & preserved
  extension: [{ url: 'https://my-hospital.org/custom-field', valueString: 'value' }]
});

Regional Support

Saudi Arabia (KSA-Core / NPHIES)

Vitalis includes a dedicated module for the Saudi region, aligning with NPHIES requirements.

import { KSA } from 'vitalis-fhir/r4';

// Validates National ID (starts with 1) and Iqama (starts with 2)
const result = KSA.SaudiPatientSchema.safeParse({
  resourceType: 'Patient',
  identifier: [{ system: KSA.SaudiSystems.NationalID, value: '1023456789' }],
  ...
});

Included Saudi Helpers:

• SaudiNationalIdSchema / SaudiIqamaIdSchema
• SaudiPractitionerSchema (MOH / SCHS Licenses)
• SaudiNationalityExtensionSchema
• SaudiReligionExtensionSchema

Architecture

Strict Validation Philosophy:

• Unknown fields outside the schema are stripped — no data injection from malformed EMR payloads.
• All dateTime fields enforce the official FHIR regex.
• meta and text (Narrative) are included as optional on all resources per the FHIR DomainResource spec.

Build:

• Dual ESM (.mjs) + CommonJS (.cjs) output via Vite.
• zod is a peer dependency — not bundled, keeping the package small.

Compliance & Security

HIPAA & Data Integrity

Vitalis is built for high-stakes healthcare environments. It is a pure validator (stateless, zero-persistence) designed to enforce the Data Integrity requirements of HIPAA by ensuring PHI adheres strictly to FHIR R4 standards before reaching your database.

Clinical-Grade DateTime

Unlike generic validators, we enforce the official FHIR R4 Regex for all temporal fields, preventing malformed dates from corrupting clinical datasets.

Security Warning (XSS)

The FHIR Narrative (text.div) field is validated as a string. If you render this content in a UI, you must sanitize it using a tool like DOMPurify to prevent XSS attacks.

Disclaimer

Vitalis-FHIR is an independent open-source project and is not affiliated with, sponsored by, or endorsed by any healthcare vendor or standards body.