@atomic-ehr/codegen 0.0.8 → 0.0.9-canary.20260312182458.1c26a02

package/README.md

@@ -1,7 +1,7 @@
 # Atomic EHR Codegen
 
 [![npm canary](https://img.shields.io/npm/v/@atomic-ehr/codegen/canary.svg?label=canary)](https://www.npmjs.com/package/@atomic-ehr/codegen/v/canary)
-[![npm version](https://badge.fury.io/js/%40atomic-ehr%2Fcodegen.svg)](https://badge.fury.io/js/%40atomic-ehr%2Fcodegen)
+[![npm version](https://img.shields.io/npm/v/@atomic-ehr/codegen.svg)](https://www.npmjs.com/package/@atomic-ehr/codegen)
 [![CI](https://github.com/atomic-ehr/codegen/actions/workflows/ci.yml/badge.svg)](https://github.com/atomic-ehr/codegen/actions/workflows/ci.yml)
 [![SDK Tests](https://github.com/atomic-ehr/codegen/actions/workflows/sdk-tests.yml/badge.svg)](https://github.com/atomic-ehr/codegen/actions/workflows/sdk-tests.yml)
 
@@ -10,6 +10,7 @@
 
 - [Atomic EHR Codegen](#atomic-ehr-codegen)
   - [Features](#features)
+  - [Guides](#guides)
   - [Versions & Release Cycle](#versions--release-cycle)
   - [Installation](#installation)
   - [Quick Start](#quick-start)
@@ -20,31 +21,24 @@
     - [Intermediate - Type Schema](#intermediate---type-schema)
       - [Tree Shaking](#tree-shaking)
         - [Field-Level Tree Shaking](#field-level-tree-shaking)
+      - [Logical Model Promotion](#logical-model-promotion)
     - [Generation](#generation)
       - [1. Writer-Based Generation (Programmatic)](#1-writer-based-generation-programmatic)
       - [2. Mustache Template-Based Generation (Declarative)](#2-mustache-template-based-generation-declarative)
+    - [Profile Classes](#profile-classes)
   - [Support](#support)
-- [Footnotes](#footnotes)
 
 <!-- markdown-toc end -->
 
 A powerful, extensible code generation toolkit for FHIR ([Fast Healthcare Interoperability Resources](https://www.hl7.org/fhir/)) that transforms FHIR specifications into strongly-typed code for multiple programming languages.
 
-Guides:
-
-- **[Writer Generator Guide](docs/guides/writer-generator.md)** - Build custom code generators with the Writer base class
-- **[Mustache Generator Guide](docs/guides/mustache-generator.md)** - Template-based code generation for any language
-- **[TypeSchemaIndex Guide](docs/guides/typeschema-index.md)** - Type Schema structure and utilities
-- **[Testing Generators Guide](docs/guides/testing-generators.md)** - Unit tests, snapshot testing, and best practices
-- **[Contributing Guide](CONTRIBUTING.md)** - Development setup and workflow
-
 ## Features
 
 - [x] **Multi-Package Support** — Load packages from the [FHIR registry](examples/typescript-r4/), [remote TGZ files](examples/typescript-sql-on-fhir/), or a [local folder with custom StructureDefinitions](examples/local-package-folder/)
   - Tested with hl7.fhir.r4.core, US Core, C-CDA, SQL on FHIR, etc.
 - [x] **Resources & Complex Types** — Generates typed definitions with proper inheritance
 - [x] **Value Set Bindings** — Strongly-typed enums from FHIR terminology bindings
-- [x] **Profiles & Extensions** — Factory methods with auto-populated fixed values and required slices ([R4 profiles](examples/typescript-r4/profile-bp.test.ts), [US Core](examples/typescript-us-core/))
+- [x] **Profiles** — Factory methods with auto-populated fixed values and required slices ([R4 profiles](examples/typescript-r4/profile-bp.test.ts), [US Core](examples/typescript-us-core/))
   - Extensions — flat typed accessors (e.g. `setRace()` on US Core Patient), [standalone extension profiles](examples/typescript-r4/extension-profile.test.ts)
   - Slicing — typed get/set accessors with discriminator matching
   - Validation — runtime `validate()` for required fields, fixed values, slice cardinality, enums, references
@@ -52,20 +46,27 @@ Guides:
   - TypeSchema is a universal intermediate representation — add a new language by writing only the final generation stage
   - Built-in generators: TypeScript, Python/Pydantic, C#, and Mustache templates
 - [x] **TypeSchema Transformations**:
-  - [x] Tree Shaking — include only the resources and fields you need; automatically resolves dependencies
-  - [x] Logical Model Promotion — promote FHIR logical models (e.g. CDA ClinicalDocument) to first-class resources
-  - [ ] Renaming — custom naming conventions for generated types, fields, packages, etc.
+  - [x] **Tree Shaking** — include only the resources and fields you need; automatically resolves dependencies
+  - [x] **Logical Model Promotion** — promote FHIR logical models to first-class resources
+  - [ ] Renaming — custom naming conventions for generated types and fields
 - [ ] **Search Builders** — type-safe FHIR search query construction
 - [ ] **Operation Generation** — type-safe FHIR operation calls
 
-| Feature | TypeSchema | TypeScript | Python | C# | Mustache |
-|---|---|---|---|---|---|
-| Resources & Complex Types | yes | yes | yes | yes | template |
-| Value Set Bindings | yes | inline | inline | enum | template |
-| Profiles & Extensions | yes | yes | no | no | no |
-| Tree Shaking | yes | 〃 | 〃 | 〃 | 〃 |
-| Logical Model Promotion | yes | 〃 | 〃 | 〃 | 〃 |
+| Feature                   | TypeScript | Python  | C#   | Mustache |
+|---------------------------|------------|---------|------|----------|
+| Resources & Complex Types | yes        | yes     | yes  | template |
+| Value Set Bindings        | inline     | limited | enum | template |
+| Primitive Extensions      | yes        | no      | no   | no       |
+| Profiles                  | yes        | no      | no   | no       |
+| Profile Validation        | yes        | no      | no   | no       |
 
+## Guides
+
+- **[Writer Generator Guide](docs/guides/writer-generator.md)** - Build custom code generators with the Writer base class
+- **[Mustache Generator Guide](docs/guides/mustache-generator.md)** - Template-based code generation for any language
+- **[TypeSchemaIndex Guide](docs/guides/typeschema-index.md)** - Type Schema structure and utilities
+- **[Testing Generators Guide](docs/guides/testing-generators.md)** - Unit tests, snapshot testing, and best practices
+- **[Contributing Guide](CONTRIBUTING.md)** - Development setup and workflow
 
 ## Versions & Release Cycle
 
@@ -204,7 +205,7 @@ Use the new `localPackage` helper to point the builder at an on-disk FHIR packag
 .localTgzPackage("./packages/my-custom-ig.tgz")
 ```
 
-The example above points Canonical Manager at `./custom-profiles`, installs the HL7 R4 core dependency automatically, and then limits generation to the custom `ExampleNotebook` logical model plus the standard R4 `Patient` resource via tree shaking. The `localTgzPackage` helper registers `.tgz` artifacts that Canonical Manager already knows how to unpack.
+The example above points Canonical Manager at `./custom-profiles` and installs the HL7 R4 core dependency automatically. The `localTgzPackage` helper registers `.tgz` artifacts that Canonical Manager already knows how to unpack.
 
 ### Intermediate - Type Schema
 
@@ -263,7 +264,7 @@ Beyond resource-level filtering, tree shaking supports fine-grained field select
 
 FHIR choice types (like `multipleBirth[x]` which can be boolean or integer) are handled intelligently. Selecting/ignoring the base field affects all variants, while targeting specific variants only affects those types.
 
-##### Logical Promotion
+#### Logical Model Promotion
 
 Some implementation guides expose logical models (logical-kind StructureDefinitions) that are intended to be used like resources in generated SDKs. The code generator supports promoting selected logical models to behave as resources during generation.
 
@@ -291,9 +292,7 @@ For languages with built-in support (TypeScript, Python, C#), extend the `Writer
 
 - **FileSystemWriter**: Base class providing file I/O, directory management, and buffer handling (both disk and in-memory modes)
 - **Writer**: Extends FileSystemWriter with code formatting utilities (indentation, blocks, comments, line management)
-- **Language Writers** (`TypeScript`, `Python`[^py], `CSharp`): Implement language-specific generation logic by traversing TypeSchema index and generating corresponding types, interfaces, or classes
-
-[^py]: For details on [Type Schema: Python SDK for FHIR](https://www.health-samurai.io/articles/type-schema-python-sdk-for-fhir)
+- **Language Writers** (`TypeScript`, `Python`, `CSharp`): Implement language-specific generation logic by traversing TypeSchema index and generating corresponding types, interfaces, or classes (see also: [Type Schema: Python SDK for FHIR](https://www.health-samurai.io/articles/type-schema-python-sdk-for-fhir))
 
 Each language writer maintains full control over output formatting while leveraging high-level abstractions for common code patterns. Writers follow language idioms and best practices, with optimized output for production use.
 
@@ -344,11 +343,11 @@ const obs = bp.toResource();
 **Slicing & Choice Type Flattening:**
 
 ```typescript
-// Simplified getter — discriminator stripped, choice type flattened
-bp.getSystolicBP();    // { value: 120, unit: "mmHg" }
+// Flat getter (default) — discriminator stripped, choice type flattened
+bp.getSystolicBP();        // { value: 120, unit: "mmHg" }
 
 // Raw getter — full FHIR element including discriminator values
-bp.getSystolicBPRaw(); // { code: { coding: [...] }, valueQuantity: { value: 120, ... } }
+bp.getSystolicBP('raw');   // { code: { coding: [...] }, valueQuantity: { value: 120, ... } }
 ```
 
 **Wrapping Existing Resources:**
@@ -373,8 +372,8 @@ See [examples/typescript-r4/](examples/typescript-r4/) for R4 profile tests and
 
 ## Support
 
-- 🐛 [Issue Tracker](https://github.com/atomic-ehr/codegen/issues)
+- [Issue Tracker](https://github.com/atomic-ehr/codegen/issues)
 
 ---
 
-Built with ❤️ by the Atomic Healthcare team
+Built by the Atomic Healthcare team

package/assets/api/writer-generator/python/fhirpy_base_model.py

@@ -1,4 +1,4 @@
-from typing import Any, ClassVar, Type, Union, Optional, Iterator, Tuple, Dict
+from typing import Any, Union, Optional, Iterator, Tuple, Dict
 from pydantic import BaseModel, Field
 from typing import Protocol
 
@@ -8,23 +8,21 @@ class ResourceProtocol(Protocol):
     id: Union[str, None]
 
 
-class ResourceTypeDescriptor:
-    def __get__(self, instance: Optional[BaseModel], owner: Type[BaseModel]) -> str:
-        field = owner.model_fields.get("resource_type")
-        if field is None:
-            raise ValueError("resource_type field not found")
-        if field.default is None:
-            raise ValueError("resource_type field default value is not set")
-        return str(field.default)
-
-
 class FhirpyBaseModel(BaseModel):
     """
-    This class satisfies ResourceProtocol
+    This class satisfies ResourceProtocol.
+    Uses __pydantic_init_subclass__ to set resourceType as a class-level attribute
+    after Pydantic finishes model construction, so that fhirpy can detect it
+    via cls.resourceType for search/fetch operations.
     """
     id: Optional[str] = Field(None, alias="id")
 
-    resourceType: ClassVar[ResourceTypeDescriptor] = ResourceTypeDescriptor()
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+        field = cls.model_fields.get("resource_type") or cls.model_fields.get("resourceType")
+        if field is not None and field.default is not None:
+            type.__setattr__(cls, "resourceType", str(field.default))
 
     def __iter__(self) -> Iterator[Tuple[str, Any]]:  # type: ignore[override]
         data = self.model_dump(mode='json', by_alias=True, exclude_none=True)

package/assets/api/writer-generator/python/fhirpy_base_model_camel_case.py

@@ -10,10 +10,20 @@ class ResourceProtocol(Protocol):
 
 class FhirpyBaseModel(BaseModel):
     """
-    This class satisfies ResourceProtocol
+    This class satisfies ResourceProtocol.
+    Uses __pydantic_init_subclass__ to set resourceType as a class-level attribute
+    after Pydantic finishes model construction, so that fhirpy can detect it
+    via cls.resourceType for search/fetch operations.
     """
     id: Optional[str] = Field(None, alias="id")
 
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+        field = cls.model_fields.get("resource_type") or cls.model_fields.get("resourceType")
+        if field is not None and field.default is not None:
+            type.__setattr__(cls, "resourceType", str(field.default))
+
     def __iter__(self) -> Iterator[Tuple[str, Any]]:  # type: ignore[override]
         data = self.model_dump(mode='json', by_alias=True, exclude_none=True)
         return iter(data.items())

package/assets/api/writer-generator/python/requirements.txt

@@ -1,5 +1,7 @@
-requests>=2.32.0,<3.0.0
-pytest>=8.3.0,<9.0.0
-pydantic>=2.11.0,<3.0.0
+fhirpy>=2.0.0,<3.0.0
 mypy>=1.9.0,<2.0.0
-types-requests>=2.32.0,<3.0.0
+pydantic>=2.11.0,<3.0.0
+pytest>=8.3.0,<9.0.0
+pytest-asyncio>=0.24.0,<1.0.0
+requests>=2.32.0,<3.0.0
+types-requests>=2.32.0,<3.0.0

package/assets/api/writer-generator/typescript/profile-helpers.ts

@@ -0,0 +1,412 @@
+/**
+ * Runtime helpers for generated FHIR profile classes.
+ *
+ * This file is copied verbatim into every generated TypeScript output and
+ * imported by profile modules.  It provides:
+ *
+ * - **Slice helpers** – match, get, set, and default-fill array slices
+ *   defined by a FHIR StructureDefinition.
+ * - **Extension helpers** – read complex (nested) FHIR extensions into
+ *   plain objects.
+ * - **Choice-type helpers** – wrap/unwrap polymorphic `value[x]` fields so
+ *   profile classes can expose a flat API.
+ * - **Validation helpers** – lightweight structural checks that profile
+ *   classes call from their `validate()` method.
+ * - **Misc utilities** – deep-match, deep-merge, path navigation.
+ */
+
+// ---------------------------------------------------------------------------
+// General utilities
+// ---------------------------------------------------------------------------
+
+/** Type guard: `value` is a non-null, non-array plain object. */
+export const isRecord = (value: unknown): value is Record<string, unknown> => {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+};
+
+/**
+ * Walk `path` segments from `root`, creating intermediate objects (or using
+ * the first element of an existing array) as needed.  Returns the leaf object.
+ *
+ * Used by extension setters to reach a nested target inside a resource.
+ *
+ * @example
+ *   ensurePath(resource, ["contact", "telecom"])
+ *   // → resource.contact.telecom (created if absent)
+ */
+export const ensurePath = (root: Record<string, unknown>, path: string[]): Record<string, unknown> => {
+    let current: Record<string, unknown> = root;
+    for (const segment of path) {
+        if (Array.isArray(current[segment])) {
+            const list = current[segment] as unknown[];
+            if (list.length === 0) {
+                list.push({});
+            }
+            current = list[0] as Record<string, unknown>;
+        } else {
+            if (!isRecord(current[segment])) {
+                current[segment] = {};
+            }
+            current = current[segment] as Record<string, unknown>;
+        }
+    }
+    return current;
+};
+
+// ---------------------------------------------------------------------------
+// Deep match / merge
+// ---------------------------------------------------------------------------
+
+/**
+ * Deep-merge `match` into `target`, mutating `target` in place.
+ * Skips prototype-pollution keys.  Used internally by {@link applySliceMatch}.
+ */
+export const mergeMatch = (target: Record<string, unknown>, match: Record<string, unknown>): void => {
+    for (const [key, matchValue] of Object.entries(match)) {
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            continue;
+        }
+        if (isRecord(matchValue)) {
+            if (isRecord(target[key])) {
+                mergeMatch(target[key] as Record<string, unknown>, matchValue);
+            } else {
+                target[key] = { ...matchValue };
+            }
+        } else {
+            target[key] = matchValue;
+        }
+    }
+};
+
+/**
+ * Shallow-clone `input` then deep-merge the slice discriminator values from
+ * `match` on top, returning a complete slice element ready for insertion.
+ *
+ * @example
+ *   applySliceMatch({ text: "hi" }, { coding: { code: "vital-signs", system: "…" } })
+ *   // → { text: "hi", coding: { code: "vital-signs", system: "…" } }
+ */
+export const applySliceMatch = <T extends object>(input: Partial<T>, match: Partial<Record<keyof T, unknown>>): T => {
+    const result = { ...input } as Record<string, unknown>;
+    mergeMatch(result, match);
+    return result as T;
+};
+
+/**
+ * Recursively test whether `value` structurally contains everything in
+ * `match`.  Arrays are matched with "every match item has a corresponding
+ * value item" semantics; objects are matched key-by-key; primitives use `===`.
+ *
+ * This is the core discriminator check used to identify which array element
+ * belongs to a given FHIR slice.
+ */
+export const matchesValue = (value: unknown, match: unknown): boolean => {
+    if (Array.isArray(match)) {
+        if (!Array.isArray(value)) {
+            return false;
+        }
+        return match.every((matchItem) => value.some((item) => matchesValue(item, matchItem)));
+    }
+    if (isRecord(match)) {
+        if (!isRecord(value)) {
+            return false;
+        }
+        for (const [key, matchValue] of Object.entries(match)) {
+            if (!matchesValue((value as Record<string, unknown>)[key], matchValue)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return value === match;
+};
+
+/**
+ * Type guard that discriminates a raw extension input (with an `extension`
+ * array) from a flat-API input object.  Using a custom type guard instead of
+ * a bare `"extension" in args` lets TypeScript narrow *both* branches of the
+ * union — the plain `in` check cannot eliminate a type whose `extension`
+ * property is optional.
+ */
+export const isRawExtensionInput = <TRaw extends object>(input: object): input is TRaw => "extension" in input;
+
+/**
+ * Type guard that tests whether an unknown setter input is a raw Extension
+ * (i.e. an object with a `url` property).  When `url` is provided, also
+ * checks that the extension's URL matches the expected value.
+ */
+export const isExtension = <E extends { url: string }>(input: unknown, url?: string): input is E =>
+    typeof input === "object" && input !== null && "url" in input && (url === undefined || input.url === url);
+
+/**
+ * Read a single typed value field from an Extension, returning `undefined`
+ * when the extension itself is absent or the field is not set.
+ *
+ * This avoids the double-cast `(ext as Record<…>)?.field as T` that would
+ * otherwise be needed for value fields not declared on the base Extension type.
+ */
+export const getExtensionValue = <T>(ext: { url?: string } | undefined, field: string): T | undefined => {
+    if (!ext) return undefined;
+    return (ext as Record<string, unknown>)[field] as T | undefined;
+};
+
+/**
+ * Push an extension onto `target.extension`, creating the array if absent.
+ */
+export const pushExtension = <E extends { url?: string }>(target: { extension?: E[] }, ext: E): void => {
+    (target.extension ??= []).push(ext);
+};
+
+// ---------------------------------------------------------------------------
+// Extension helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a complex (nested) FHIR extension into a plain key/value object.
+ *
+ * Each entry in `config` describes one sub-extension by URL, the name of its
+ * value field (e.g. `"valueString"`), and whether it may repeat.
+ *
+ * @returns A record keyed by sub-extension URL, or `undefined` if the
+ *          extension has no nested children.
+ */
+export const extractComplexExtension = <T = Record<string, unknown>>(
+    extension: { extension?: Array<{ url?: string }> } | undefined,
+    config: Array<{ name: string; valueField: string; isArray: boolean }>,
+): T | undefined => {
+    if (!extension?.extension) return undefined;
+    const result: Record<string, unknown> = {};
+    for (const { name, valueField, isArray } of config) {
+        const subExts = extension.extension.filter((e) => e.url === name);
+        if (isArray) {
+            result[name] = subExts.map((e) => (e as Record<string, unknown>)[valueField]);
+        } else if (subExts[0]) {
+            result[name] = (subExts[0] as Record<string, unknown>)[valueField];
+        }
+    }
+    return result as T;
+};
+
+// ---------------------------------------------------------------------------
+// Slice helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove discriminator keys from a slice element, returning only the
+ * user-supplied portion.  Used by slice getters so callers see a clean object
+ * without the fixed discriminator values baked in.
+ */
+export const stripMatchKeys = <T>(slice: object, matchKeys: string[]): T => {
+    const result = { ...slice } as Record<string, unknown>;
+    for (const key of matchKeys) {
+        delete result[key];
+    }
+    return result as T;
+};
+
+/**
+ * Wrap a flat input object under a choice-type key before inserting into a
+ * slice.  For example, a Quantity value destined for `valueQuantity` is
+ * wrapped as `{ valueQuantity: { ...input } }`.
+ *
+ * No-op when `input` is empty (the slice will contain only discriminator
+ * defaults).
+ */
+export const wrapSliceChoice = <T>(input: object, choiceVariant: string): Partial<T> => {
+    if (Object.keys(input).length === 0) return input as Partial<T>;
+    return { [choiceVariant]: input } as Partial<T>;
+};
+
+/**
+ * Inverse of {@link wrapSliceChoice}: strip discriminator keys, then hoist
+ * the value inside `choiceVariant` up to the top level.
+ *
+ * @example
+ *   unwrapSliceChoice(raw, ["code"], "valueQuantity")
+ *   // removes "code", moves raw.valueQuantity.* to top level
+ */
+export const unwrapSliceChoice = <T>(slice: object, matchKeys: string[], choiceVariant: string): T => {
+    const result = { ...slice } as Record<string, unknown>;
+    for (const key of matchKeys) {
+        delete result[key];
+    }
+    const variantValue = result[choiceVariant];
+    delete result[choiceVariant];
+    if (isRecord(variantValue)) {
+        Object.assign(result, variantValue);
+    }
+    return result as T;
+};
+
+/**
+ * Ensure that every required slice has at least a stub element in the array.
+ * Each `match` is a discriminator pattern; if no existing item satisfies it,
+ * a deep clone of the pattern is appended.
+ *
+ * Called in `createResource` so that required slices are always present even
+ * when the caller omits them.
+ */
+export const ensureSliceDefaults = <T>(items: T[], ...matches: Record<string, unknown>[]): T[] => {
+    for (const match of matches) {
+        if (!items.some((item) => matchesValue(item, match))) {
+            items.push(structuredClone(match) as T);
+        }
+    }
+    return items;
+};
+
+/**
+ * Cast an object literal to a FHIR resource type.  This centralises the single
+ * `as unknown as T` that is unavoidable when constructing a resource from a
+ * plain object (deep inheritance prevents direct structural compatibility).
+ */
+export const buildResource = <T>(obj: object): T => obj as unknown as T;
+
+/**
+ * Add `canonicalUrl` to `resource.meta.profile` if not already present.
+ * Creates `meta` and `profile` when missing.
+ */
+export const ensureProfile = (resource: { meta?: { profile?: string[] } }, canonicalUrl: string): void => {
+    const meta = (resource.meta ??= {});
+    const profiles = (meta.profile ??= []);
+    if (!profiles.includes(canonicalUrl)) profiles.push(canonicalUrl);
+};
+
+/**
+ * Find or insert a slice element in `list`.  If an element matching `match`
+ * already exists it is replaced in place; otherwise `value` is appended.
+ */
+export const setArraySlice = <T>(list: T[], match: Record<string, unknown>, value: T): void => {
+    const index = list.findIndex((item) => matchesValue(item, match));
+    if (index === -1) {
+        list.push(value);
+    } else {
+        list[index] = value;
+    }
+};
+
+/** Return the first element in `list` that satisfies the slice discriminator `match`. */
+export const getArraySlice = <T>(list: readonly T[] | undefined, match: Record<string, unknown>): T | undefined => {
+    if (!list) return undefined;
+    return list.find((item) => matchesValue(item, match));
+};
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+//
+// Each function returns an array of human-readable error strings (empty = ok).
+// Profile classes spread them all into a single array from `validate()`.
+// ---------------------------------------------------------------------------
+
+/** Checks that `field` is present (not `undefined` or `null`). */
+export const validateRequired = (res: object, profileName: string, field: string): string[] => {
+    const rec = res as Record<string, unknown>;
+    return rec[field] === undefined || rec[field] === null
+        ? [`${profileName}: required field '${field}' is missing`]
+        : [];
+};
+
+/** Checks that a must-support field is populated (warning, not error). */
+export const validateMustSupport = (res: object, profileName: string, field: string): string[] => {
+    const rec = res as Record<string, unknown>;
+    return rec[field] === undefined || rec[field] === null
+        ? [`${profileName}: must-support field '${field}' is not populated`]
+        : [];
+};
+
+/** Checks that `field` is absent (profiles may exclude base fields). */
+export const validateExcluded = (res: object, profileName: string, field: string): string[] => {
+    return (res as Record<string, unknown>)[field] !== undefined
+        ? [`${profileName}: field '${field}' must not be present`]
+        : [];
+};
+
+/** Checks that `field` structurally contains the expected fixed value. */
+export const validateFixedValue = (res: object, profileName: string, field: string, expected: unknown): string[] => {
+    return matchesValue((res as Record<string, unknown>)[field], expected)
+        ? []
+        : [`${profileName}: field '${field}' does not match expected fixed value`];
+};
+
+/**
+ * Checks that the number of array elements matching `match` (a slice
+ * discriminator) falls within [`min`, `max`].  Pass `max = 0` for unbounded.
+ */
+export const validateSliceCardinality = (
+    res: object,
+    profileName: string,
+    field: string,
+    match: Record<string, unknown>,
+    sliceName: string,
+    min: number,
+    max: number,
+): string[] => {
+    const items = (res as Record<string, unknown>)[field] as unknown[] | undefined;
+    const count = (items ?? []).filter((item) => matchesValue(item, match)).length;
+    const errors: string[] = [];
+    if (count < min) {
+        errors.push(`${profileName}.${field}: slice '${sliceName}' requires at least ${min} item(s), found ${count}`);
+    }
+    if (max > 0 && count > max) {
+        errors.push(`${profileName}.${field}: slice '${sliceName}' allows at most ${max} item(s), found ${count}`);
+    }
+    return errors;
+};
+
+/**
+ * Checks that at least one of the listed choice-type variants is present.
+ * E.g. `["effectiveDateTime", "effectivePeriod"]`.
+ */
+export const validateChoiceRequired = (res: object, profileName: string, choices: string[]): string[] => {
+    const rec = res as Record<string, unknown>;
+    return choices.some((c) => rec[c] !== undefined)
+        ? []
+        : [`${profileName}: at least one of ${choices.join(", ")} is required`];
+};
+
+/**
+ * Checks that the value of `field` has a code within `allowed`.
+ * Handles plain strings, Coding objects, and CodeableConcept objects.
+ * Skips validation when the field is absent.
+ */
+export const validateEnum = (res: object, profileName: string, field: string, allowed: string[]): string[] => {
+    const value = (res as Record<string, unknown>)[field];
+    if (value === undefined || value === null) return [];
+    if (typeof value === "string") {
+        return allowed.includes(value)
+            ? []
+            : [`${profileName}: field '${field}' value '${value}' is not in allowed values`];
+    }
+    const rec = value as Record<string, unknown>;
+    // Coding
+    if (typeof rec.code === "string" && rec.system !== undefined) {
+        return allowed.includes(rec.code)
+            ? []
+            : [`${profileName}: field '${field}' code '${rec.code}' is not in allowed values`];
+    }
+    // CodeableConcept
+    if (Array.isArray(rec.coding)) {
+        const codes = (rec.coding as Record<string, unknown>[]).map((c) => c.code as string).filter(Boolean);
+        const hasValid = codes.some((c) => allowed.includes(c));
+        return hasValid ? [] : [`${profileName}: field '${field}' has no coding with an allowed code`];
+    }
+    return [];
+};
+
+/**
+ * Checks that a Reference field points to one of the `allowed` resource
+ * types.  Extracts the type from the `reference` string (the part before
+ * the first `/`).  Skips validation when the field or reference is absent.
+ */
+export const validateReference = (res: object, profileName: string, field: string, allowed: string[]): string[] => {
+    const value = (res as Record<string, unknown>)[field];
+    if (value === undefined || value === null) return [];
+    const ref = (value as Record<string, unknown>).reference as string | undefined;
+    if (!ref) return [];
+    const slashIdx = ref.indexOf("/");
+    if (slashIdx === -1) return [];
+    const refType = ref.slice(0, slashIdx);
+    return allowed.includes(refType)
+        ? []
+        : [`${profileName}: field '${field}' references '${refType}' but only ${allowed.join(", ")} are allowed`];
+};