@peerbits/fhir-validator 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * fhir-validator — structural, cardinality, and reference validation for
+ * FHIR R4 resources. Explicitly NOT a full conformance engine — see
+ * docs/KNOWN_LIMITATIONS.md and developer handover spec.
+ */
+export declare const VERSION = "1.0.1";
+export { validate, getNestedValue, validateProfileConstraints, hasCircularReference } from "./validate.js";
+export type { ValidationIssue, ValidationResult, ValidationSeverity, ProfileConstraints, BindingStrength, ValidateOptions, } from "./types.js";
+export { validateCoding, validateCodeableConcept } from "./coding.js";
+export { validateReference, extractReferenceType, ALLOWED_REFERENCE_TARGETS } from "./reference-rules.js";
+export { validatePatient } from "./base-definitions/patient.js";
+export { validateObservation } from "./base-definitions/observation.js";
+export { validateEncounter } from "./base-definitions/encounter.js";
+export { validateCondition } from "./base-definitions/condition.js";
+export { validateCoverage } from "./base-definitions/coverage.js";
+export { validateClaim } from "./base-definitions/claim.js";
+export { validateClaimResponse } from "./base-definitions/claim-response.js";
+export { USCorePatientProfile } from "./profiles/us-core-patient.js";
+export { USCoreObservationVitalsProfile } from "./profiles/us-core-observation-vitals.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * fhir-validator — structural, cardinality, and reference validation for
+ * FHIR R4 resources. Explicitly NOT a full conformance engine — see
+ * docs/KNOWN_LIMITATIONS.md and developer handover spec.
+ */
+export const VERSION = "1.0.1";
+// Main API
+export { validate, getNestedValue, validateProfileConstraints, hasCircularReference } from "./validate.js";
+// Coding & Reference Helpers
+export { validateCoding, validateCodeableConcept } from "./coding.js";
+export { validateReference, extractReferenceType, ALLOWED_REFERENCE_TARGETS } from "./reference-rules.js";
+// Base Resource Validators
+export { validatePatient } from "./base-definitions/patient.js";
+export { validateObservation } from "./base-definitions/observation.js";
+export { validateEncounter } from "./base-definitions/encounter.js";
+export { validateCondition } from "./base-definitions/condition.js";
+export { validateCoverage } from "./base-definitions/coverage.js";
+export { validateClaim } from "./base-definitions/claim.js";
+export { validateClaimResponse } from "./base-definitions/claim-response.js";
+// Illustrative Profiles
+export { USCorePatientProfile } from "./profiles/us-core-patient.js";
+export { USCoreObservationVitalsProfile } from "./profiles/us-core-observation-vitals.js";

package/dist/profiles/us-core-observation-vitals.d.ts

@@ -0,0 +1,11 @@
+import { ProfileConstraints } from "../types.js";
+/**
+ * ILLUSTRATIVE ONLY — not a certified reproduction of the real US Core
+ * Vital Signs profile. See handover doc §6 FR5 and §13.
+ *
+ * This profile demonstrates the ProfileConstraints mechanism by enforcing:
+ * - Presence of category containing vital-signs coding
+ * - Mandatory subject referencing Patient
+ * - Effective date/time or period
+ */
+export declare const USCoreObservationVitalsProfile: ProfileConstraints;

package/dist/profiles/us-core-observation-vitals.js

@@ -0,0 +1,22 @@
+/**
+ * ILLUSTRATIVE ONLY — not a certified reproduction of the real US Core
+ * Vital Signs profile. See handover doc §6 FR5 and §13.
+ *
+ * This profile demonstrates the ProfileConstraints mechanism by enforcing:
+ * - Presence of category containing vital-signs coding
+ * - Mandatory subject referencing Patient
+ * - Effective date/time or period
+ */
+export const USCoreObservationVitalsProfile = {
+    name: "us-core-observation-vitals",
+    resourceType: "Observation",
+    url: "http://hl7.org/fhir/us/core/StructureDefinition/us-core-vital-signs",
+    requiredElements: ["status", "category", "code", "subject"],
+    cardinalityOverrides: {
+        category: { min: 1 },
+    },
+    fixedValues: {
+        "category[0].coding[0].system": "http://terminology.hl7.org/CodeSystem/observation-category",
+        "category[0].coding[0].code": "vital-signs",
+    },
+};

package/dist/profiles/us-core-patient.d.ts

@@ -0,0 +1,10 @@
+import { ProfileConstraints } from "../types.js";
+/**
+ * ILLUSTRATIVE ONLY — not a certified reproduction of the real US Core
+ * Patient StructureDefinition. See handover doc §6 FR5 and §13.
+ *
+ * This profile demonstrates the ProfileConstraints mechanism by requiring
+ * elements (such as `identifier`, `name`, `gender`) that the base FHIR R4
+ * specification leaves optional.
+ */
+export declare const USCorePatientProfile: ProfileConstraints;

package/dist/profiles/us-core-patient.js

@@ -0,0 +1,21 @@
+/**
+ * ILLUSTRATIVE ONLY — not a certified reproduction of the real US Core
+ * Patient StructureDefinition. See handover doc §6 FR5 and §13.
+ *
+ * This profile demonstrates the ProfileConstraints mechanism by requiring
+ * elements (such as `identifier`, `name`, `gender`) that the base FHIR R4
+ * specification leaves optional.
+ */
+export const USCorePatientProfile = {
+    name: "us-core-patient",
+    resourceType: "Patient",
+    url: "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
+    requiredElements: ["identifier", "name", "gender"],
+    cardinalityOverrides: {
+        identifier: { min: 1 },
+        name: { min: 1 },
+    },
+    bindingStrength: {
+        gender: "required",
+    },
+};

package/dist/reference-rules.d.ts

@@ -0,0 +1,14 @@
+import { ValidationIssue } from "./types.js";
+/**
+ * Maps field paths to their allowed target FHIR resource types per FHIR R4 base spec.
+ */
+export declare const ALLOWED_REFERENCE_TARGETS: Record<string, string[]>;
+/**
+ * Extracts target resource type from a Reference object.
+ * Looks at explicit `type` field, or parses relative/absolute URL in `reference`.
+ */
+export declare function extractReferenceType(referenceObj: Record<string, unknown>): string | null;
+/**
+ * Validates a FHIR Reference element against allowed target resource types.
+ */
+export declare function validateReference(reference: unknown, path: string, allowedTypes?: string[]): ValidationIssue[];

package/dist/reference-rules.js

@@ -0,0 +1,139 @@
+/**
+ * Maps field paths to their allowed target FHIR resource types per FHIR R4 base spec.
+ */
+export const ALLOWED_REFERENCE_TARGETS = {
+    // Patient
+    "Patient.generalPractitioner": ["Organization", "Practitioner", "PractitionerRole"],
+    "Patient.managingOrganization": ["Organization"],
+    "Patient.link.other": ["Patient", "RelatedPerson"],
+    // Observation
+    "Observation.subject": ["Patient", "Group", "Device", "Location"],
+    "Observation.focus": ["Resource"],
+    "Observation.encounter": ["Encounter"],
+    "Observation.performer": ["Practitioner", "PractitionerRole", "Organization", "CareTeam", "Patient", "RelatedPerson"],
+    "Observation.specimen": ["Specimen"],
+    "Observation.device": ["Device", "DeviceMetric"],
+    "Observation.hasMember": ["Observation", "QuestionnaireResponse", "MolecularSequence"],
+    "Observation.derivedFrom": ["DocumentReference", "ImagingStudy", "Media", "QuestionnaireResponse", "Observation", "MolecularSequence"],
+    // Encounter
+    "Encounter.subject": ["Patient", "Group"],
+    "Encounter.episodeOfCare": ["EpisodeOfCare"],
+    "Encounter.basedOn": ["ServiceRequest"],
+    "Encounter.participant.individual": ["Practitioner", "PractitionerRole", "RelatedPerson"],
+    "Encounter.appointment": ["Appointment"],
+    "Encounter.reasonReference": ["Condition", "Procedure", "Observation", "ImmunizationRecommendation"],
+    "Encounter.diagnosis.condition": ["Condition", "Procedure"],
+    "Encounter.location.location": ["Location"],
+    "Encounter.serviceProvider": ["Organization"],
+    "Encounter.partOf": ["Encounter"],
+    // Condition
+    "Condition.subject": ["Patient", "Group"],
+    "Condition.encounter": ["Encounter"],
+    "Condition.recorder": ["Practitioner", "PractitionerRole", "Patient", "RelatedPerson"],
+    "Condition.asserter": ["Practitioner", "PractitionerRole", "Patient", "RelatedPerson"],
+    "Condition.stage.assessment": ["ClinicalImpression", "DiagnosticReport", "Observation"],
+    "Condition.evidence.detail": ["Resource"],
+    // Coverage
+    "Coverage.policyHolder": ["Patient", "RelatedPerson", "Organization"],
+    "Coverage.subscriber": ["Patient", "RelatedPerson"],
+    "Coverage.beneficiary": ["Patient"],
+    "Coverage.payor": ["Organization", "Patient", "RelatedPerson"],
+    "Coverage.contract": ["Contract"],
+    // Claim
+    "Claim.patient": ["Patient"],
+    "Claim.enterer": ["Practitioner", "PractitionerRole"],
+    "Claim.insurer": ["Organization"],
+    "Claim.provider": ["Practitioner", "PractitionerRole", "Organization"],
+    "Claim.facility": ["Location"],
+    "Claim.prescription": ["MedicationRequest", "VisionPrescription"],
+    "Claim.originalPrescription": ["MedicationRequest"],
+    "Claim.payee.party": ["Practitioner", "PractitionerRole", "Organization", "Patient", "RelatedPerson"],
+    "Claim.referral": ["ServiceRequest"],
+    "Claim.careTeam.provider": ["Practitioner", "PractitionerRole", "Organization"],
+    "Claim.supportingInfo.valueReference": ["Resource"],
+    "Claim.diagnosis.diagnosisReference": ["Condition"],
+    "Claim.procedure.procedureReference": ["Procedure"],
+    "Claim.insurance.coverage": ["Coverage"],
+    "Claim.insurance.claimResponse": ["ClaimResponse"],
+    "Claim.item.locationReference": ["Location"],
+    "Claim.item.encounter": ["Encounter"],
+    // ClaimResponse
+    "ClaimResponse.patient": ["Patient"],
+    "ClaimResponse.insurer": ["Organization"],
+    "ClaimResponse.requestor": ["Practitioner", "PractitionerRole", "Organization"],
+    "ClaimResponse.request": ["Claim"],
+    "ClaimResponse.insurance.coverage": ["Coverage"],
+    "ClaimResponse.insurance.claimResponse": ["ClaimResponse"],
+};
+/**
+ * Extracts target resource type from a Reference object.
+ * Looks at explicit `type` field, or parses relative/absolute URL in `reference`.
+ */
+export function extractReferenceType(referenceObj) {
+    if (typeof referenceObj.type === "string" && referenceObj.type.trim()) {
+        return referenceObj.type.trim();
+    }
+    if (typeof referenceObj.reference === "string") {
+        const ref = referenceObj.reference.trim();
+        // Pattern: [ResourceType]/[id] or http[s]://.../[ResourceType]/[id]
+        const match = ref.match(/(?:^|\/)([A-Z][A-Za-z0-9]+)\/[A-Za-z0-9\-._~]+$/);
+        if (match && match[1]) {
+            return match[1];
+        }
+    }
+    return null;
+}
+/**
+ * Validates a FHIR Reference element against allowed target resource types.
+ */
+export function validateReference(reference, path, allowedTypes) {
+    const issues = [];
+    if (!reference || typeof reference !== "object" || Array.isArray(reference)) {
+        issues.push({
+            severity: "error",
+            path,
+            code: "invalid-structure",
+            message: `Expected '${path}' to be a Reference object, got ${Array.isArray(reference) ? "array" : typeof reference}.`,
+        });
+        return issues;
+    }
+    const ref = reference;
+    if (ref.reference !== undefined && typeof ref.reference !== "string") {
+        issues.push({
+            severity: "error",
+            path: `${path}.reference`,
+            code: "invalid-type",
+            message: `Expected '${path}.reference' to be a string, got ${typeof ref.reference}.`,
+        });
+    }
+    if (ref.type !== undefined && typeof ref.type !== "string") {
+        issues.push({
+            severity: "error",
+            path: `${path}.type`,
+            code: "invalid-type",
+            message: `Expected '${path}.type' to be a string URI/type, got ${typeof ref.type}.`,
+        });
+    }
+    if (ref.display !== undefined && typeof ref.display !== "string") {
+        issues.push({
+            severity: "error",
+            path: `${path}.display`,
+            code: "invalid-type",
+            message: `Expected '${path}.display' to be a string, got ${typeof ref.display}.`,
+        });
+    }
+    // Target type checking
+    const targets = allowedTypes ?? ALLOWED_REFERENCE_TARGETS[path];
+    if (targets && targets.length > 0 && !targets.includes("Resource")) {
+        const detectedType = extractReferenceType(ref);
+        if (detectedType && !targets.includes(detectedType)) {
+            issues.push({
+                severity: "error",
+                path,
+                code: "invalid-reference-type",
+                message: `Reference at '${path}' targets disallowed resource type '${detectedType}'. Allowed types: ${targets.join(", ")}.`,
+            });
+        }
+    }
+    return issues;
+}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Core validation types and interfaces for fhir-validator.
+ * Mirrors FHIR R4 OperationOutcome.issue structure.
+ */
+export type ValidationSeverity = "error" | "warning" | "information";
+export interface ValidationIssue {
+    /** Severity level: 'error' (fails validation), 'warning', or 'information' */
+    severity: ValidationSeverity;
+    /** Dot-separated or JSON pointer-like field path (e.g. 'Patient.gender', 'Observation.subject') */
+    path: string;
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable explanation of the issue */
+    message: string;
+}
+export interface ValidationResult {
+    /** True if no issues with severity 'error' exist */
+    valid: boolean;
+    /** List of all validation issues encountered */
+    issues: ValidationIssue[];
+}
+export type BindingStrength = "required" | "extensible" | "preferred" | "example";
+export interface ProfileConstraints {
+    /** Identifier/name of the profile */
+    name: string;
+    /** Target FHIR resource type this profile applies to */
+    resourceType: string;
+    /** Canonical URL or identifier of the profile */
+    url?: string;
+    /** List of element paths that MUST be present on the resource */
+    requiredElements?: string[];
+    /** Cardinality overrides per field path (e.g. { "name": { min: 1 }, "identifier": { min: 1 } }) */
+    cardinalityOverrides?: Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+    /** Fixed or pattern values required at specific paths */
+    fixedValues?: Record<string, any>;
+    /** Binding strength overrides for coded elements */
+    bindingStrength?: Record<string, BindingStrength>;
+}
+export interface ValidateOptions {
+    /** Optional profile constraints to evaluate on top of base structural rules */
+    profile?: ProfileConstraints;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core validation types and interfaces for fhir-validator.
+ * Mirrors FHIR R4 OperationOutcome.issue structure.
+ */
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,21 @@
+import { ProfileConstraints, ValidateOptions, ValidationIssue, ValidationResult } from "./types.js";
+/**
+ * Detects whether an object contains a circular reference.
+ */
+export declare function hasCircularReference(obj: unknown, seen?: WeakSet<object>): boolean;
+/**
+ * Resolves a property path (e.g. "name", "category[0].coding[0].system") on an object.
+ */
+export declare function getNestedValue(obj: unknown, path: string): unknown;
+/**
+ * Validates profile constraints against a resource.
+ */
+export declare function validateProfileConstraints(resource: Record<string, unknown>, profile: ProfileConstraints, rootPath: string): ValidationIssue[];
+/**
+ * Validates a FHIR R4 resource against base structural rules and optional profile constraints.
+ *
+ * @param resource The FHIR JSON object to validate.
+ * @param options Optional validation parameters (e.g. custom or illustrative profile).
+ * @returns ValidationResult containing `valid` boolean and list of `issues`.
+ */
+export declare function validate(resource: unknown, options?: ValidateOptions): ValidationResult;

package/dist/validate.js

@@ -0,0 +1,201 @@
+import { validatePatient } from "./base-definitions/patient.js";
+import { validateObservation } from "./base-definitions/observation.js";
+import { validateEncounter } from "./base-definitions/encounter.js";
+import { validateCondition } from "./base-definitions/condition.js";
+import { validateCoverage } from "./base-definitions/coverage.js";
+import { validateClaim } from "./base-definitions/claim.js";
+import { validateClaimResponse } from "./base-definitions/claim-response.js";
+const BASE_VALIDATORS = {
+    Patient: validatePatient,
+    Observation: validateObservation,
+    Encounter: validateEncounter,
+    Condition: validateCondition,
+    Coverage: validateCoverage,
+    Claim: validateClaim,
+    ClaimResponse: validateClaimResponse,
+};
+/**
+ * Detects whether an object contains a circular reference.
+ */
+export function hasCircularReference(obj, seen = new WeakSet()) {
+    if (!obj || typeof obj !== "object")
+        return false;
+    if (seen.has(obj))
+        return true;
+    seen.add(obj);
+    for (const key of Object.keys(obj)) {
+        const val = obj[key];
+        if (val && typeof val === "object") {
+            if (hasCircularReference(val, seen))
+                return true;
+        }
+    }
+    seen.delete(obj);
+    return false;
+}
+/**
+ * Resolves a property path (e.g. "name", "category[0].coding[0].system") on an object.
+ */
+export function getNestedValue(obj, path) {
+    if (!obj || typeof obj !== "object")
+        return undefined;
+    // Normalize array access like a[0].b -> a.0.b
+    const normalizedPath = path.replace(/\[(\d+)\]/g, ".$1");
+    const parts = normalizedPath.split(".");
+    let current = obj;
+    for (const part of parts) {
+        if (current === undefined || current === null)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Validates profile constraints against a resource.
+ */
+export function validateProfileConstraints(resource, profile, rootPath) {
+    const issues = [];
+    if (profile.resourceType && profile.resourceType !== resource.resourceType) {
+        issues.push({
+            severity: "error",
+            path: `${rootPath}.resourceType`,
+            code: "profile-mismatch",
+            message: `Profile '${profile.name}' applies to '${profile.resourceType}', but resource is '${String(resource.resourceType)}'.`,
+        });
+        return issues;
+    }
+    // Check required elements
+    if (profile.requiredElements) {
+        for (const elem of profile.requiredElements) {
+            const val = getNestedValue(resource, elem);
+            if (val === undefined || val === null || val === "" || (Array.isArray(val) && val.length === 0)) {
+                issues.push({
+                    severity: "error",
+                    path: `${rootPath}.${elem}`,
+                    code: "profile-required-element",
+                    message: `Profile '${profile.name}' requires element '${elem}' to be present.`,
+                });
+            }
+        }
+    }
+    // Check cardinality overrides
+    if (profile.cardinalityOverrides) {
+        for (const [elem, card] of Object.entries(profile.cardinalityOverrides)) {
+            const val = getNestedValue(resource, elem);
+            if (card.min !== undefined && card.min > 0) {
+                if (val === undefined || val === null) {
+                    issues.push({
+                        severity: "error",
+                        path: `${rootPath}.${elem}`,
+                        code: "profile-cardinality",
+                        message: `Profile '${profile.name}' requires at least ${card.min} item(s) for '${elem}', but none found.`,
+                    });
+                }
+                else if (Array.isArray(val) && val.length < card.min) {
+                    issues.push({
+                        severity: "error",
+                        path: `${rootPath}.${elem}`,
+                        code: "profile-cardinality",
+                        message: `Profile '${profile.name}' requires at least ${card.min} item(s) for '${elem}', found ${val.length}.`,
+                    });
+                }
+            }
+            if (card.max !== undefined && Array.isArray(val) && val.length > card.max) {
+                issues.push({
+                    severity: "error",
+                    path: `${rootPath}.${elem}`,
+                    code: "profile-cardinality",
+                    message: `Profile '${profile.name}' allows at most ${card.max} item(s) for '${elem}', found ${val.length}.`,
+                });
+            }
+        }
+    }
+    // Check fixed values
+    if (profile.fixedValues) {
+        for (const [fixedPath, expectedValue] of Object.entries(profile.fixedValues)) {
+            const actualValue = getNestedValue(resource, fixedPath);
+            if (actualValue !== expectedValue) {
+                issues.push({
+                    severity: "error",
+                    path: `${rootPath}.${fixedPath}`,
+                    code: "profile-fixed-value",
+                    message: `Profile '${profile.name}' requires '${fixedPath}' to equal '${String(expectedValue)}', found '${String(actualValue)}'.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Validates a FHIR R4 resource against base structural rules and optional profile constraints.
+ *
+ * @param resource The FHIR JSON object to validate.
+ * @param options Optional validation parameters (e.g. custom or illustrative profile).
+ * @returns ValidationResult containing `valid` boolean and list of `issues`.
+ */
+export function validate(resource, options) {
+    const issues = [];
+    if (!resource || typeof resource !== "object" || Array.isArray(resource)) {
+        return {
+            valid: false,
+            issues: [
+                {
+                    severity: "error",
+                    path: "resource",
+                    code: "invalid-structure",
+                    message: `Expected resource to be a JSON object, got ${Array.isArray(resource) ? "array" : typeof resource}.`,
+                },
+            ],
+        };
+    }
+    if (hasCircularReference(resource)) {
+        return {
+            valid: false,
+            issues: [
+                {
+                    severity: "error",
+                    path: "resource",
+                    code: "circular-reference",
+                    message: "Resource contains an invalid circular reference.",
+                },
+            ],
+        };
+    }
+    const res = resource;
+    if (typeof res.resourceType !== "string" || !res.resourceType.trim()) {
+        return {
+            valid: false,
+            issues: [
+                {
+                    severity: "error",
+                    path: "resource.resourceType",
+                    code: "missing-resource-type",
+                    message: "Missing or invalid required 'resourceType' string property.",
+                },
+            ],
+        };
+    }
+    const resourceType = res.resourceType.trim();
+    const baseValidator = BASE_VALIDATORS[resourceType];
+    if (!baseValidator) {
+        issues.push({
+            severity: "error",
+            path: `${resourceType}.resourceType`,
+            code: "unsupported-resource-type",
+            message: `Resource type '${resourceType}' is not supported by fhir-validator v1. Supported types: ${Object.keys(BASE_VALIDATORS).join(", ")}.`,
+        });
+    }
+    else {
+        // 1. Run base structural validation
+        issues.push(...baseValidator(res, resourceType));
+    }
+    // 2. Run profile constraints if provided
+    if (options?.profile) {
+        issues.push(...validateProfileConstraints(res, options.profile, resourceType));
+    }
+    const hasErrors = issues.some((i) => i.severity === "error");
+    return {
+        valid: !hasErrors,
+        issues,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peerbits/fhir-validator",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Structural, cardinality, and reference validation for FHIR R4 resources — a fast base-spec validator with a pluggable illustrative-profile mechanism (not a full conformance engine)",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -23,7 +23,8 @@
     "build": "tsc -p tsconfig.json",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",