API Conventions

The intended public shape is type-first:

• Patient is the generated TypeScript model
• PatientSchema is the runtime validator

Preferred import patterns

Import concrete resources from resource entry points:

import { PatientSchema, type Patient } from "fhir-zod/r4/Patient";

Import shared datatypes from the version entry point when needed:

import { HumanNameSchema, type HumanName } from "fhir-zod/r4";

Import root helpers from the package root:

import { configureFhirString } from "fhir-zod";

Rules to keep

• Keep the FHIR release explicit in every import path.
• Use the exported TypeScript model as the main application-facing type.
• Use the exported Zod schema at runtime boundaries.
• Prefer resource entry points for concrete resources to keep imports obvious.

Imports to avoid

Do not import generated internal schema symbols:

// Avoid
import { PatientSchemaInternal } from "fhir-zod/r4/Patient";

Do not import from generated source paths in application code:

// Avoid
import { PatientSchema } from "../src/r4/Patient/Patient";

Do not mix releases in a single flow unless you are translating deliberately:

import type { Patient as R4Patient } from "fhir-zod/r4/Patient";
import type { Patient as R5Patient } from "fhir-zod/r5/Patient";