babelfhir-ts 1.5.18 → 1.5.20

package/README.md

@@ -46,59 +46,42 @@
 - **Type-safe extension handling** with proper slicing and nested extension support
 - **Random data builders** for testing and development (when class generation is enabled)
 - **Zero manual mapping**—consume any FHIR package or Implementation Guide directly from registries
-- **Fast and lightweight**—minimal runtime deps; only `fhirpath` is required for validators
-- **Type-safe FHIR client** — generated client extends [`@babelfhir-ts/client-r4`](https://www.npmjs.com/package/@babelfhir-ts/client-r4) / [`client-r4b`](https://www.npmjs.com/package/@babelfhir-ts/client-r4b) / [`client-r5`](https://www.npmjs.com/package/@babelfhir-ts/client-r5) with profile-specific methods (e.g., `.usCorePatient()`, `.pASClaim()`) on top of base resource accessors
+- **Fast and lightweight**—the CLI pulls no FHIRPath engine of its own; generated packages declare `fhirpath` as a *peer* dependency (`>=4.9.1 <6`), so the host app owns the version
+- **Type-safe FHIR client** — generated client extends [`@babelfhir-ts/client-r4`](https://www.npmjs.com/package/@babelfhir-ts/client-r4) / [`client-r4b`](https://www.npmjs.com/package/@babelfhir-ts/client-r4b) / [`client-r5`](https://www.npmjs.com/package/@babelfhir-ts/client-r5) with profile-specific methods (e.g., `.uSCorePatientProfile()`, `.pASClaim()`) on top of base resource accessors
 - **Install any FHIR profile as a node module**—use `babelfhir-ts install` to add Implementation Guides directly to your project
 
 <!-- PARITY-BADGES:START - Do not remove or modify this section -->
 ## Continuous Validation
 
-Every pull request runs two independent CI pipelines that validate generated code against real-world FHIR Implementation Guides. For each IG, the pipeline:
+Every push to `develop` and `main` runs the parity pipeline, which validates generated code against real-world FHIR Implementation Guides. (Pull requests run the faster `CI` workflow: typecheck, unit tests, and generated-artifact drift checks.) For each IG, the pipeline:
 
 1. Downloads the FHIR package from a registry
 2. Generates TypeScript interfaces, validators, and classes
 3. Compiles the output with `tsc` (zero errors required)
 4. Generates `empty()` and `random()` test resources for every profile
-5. Validates those resources against two external FHIR validators
-
-### Tested Implementation Guides (30 packages)
-
-| Category | Implementation Guide | Package | FHIR |
-|---|---|---|---|
-| US | US Core | `hl7.fhir.us.core@8.0.0` | R4 |
-| US | QI-Core | `hl7.fhir.us.qicore@6.0.0` | R4 |
-| US | mCODE | `hl7.fhir.us.mcode@4.0.0` | R4 |
-| US | SDOH Clinical Care | `hl7.fhir.us.sdoh-clinicalcare@2.2.0` | R4 |
-| US | NDH (National Directory) | `hl7.fhir.us.ndh@1.0.0` | R4 |
-| US | CARIN BB | `hl7.fhir.us.carin-bb@2.1.0` | R4 |
-| US | CQF Measures | `hl7.fhir.us.cqfmeasures@4.0.0` | R4 |
-| US | Physical Activity | `hl7.fhir.us.physical-activity@1.0.0` | R4 |
-| DaVinci | PAS | `hl7.fhir.us.davinci-pas@2.0.1` | R4 |
-| DaVinci | CDex | `hl7.fhir.us.davinci-cdex@2.1.0` | R4 |
-| DaVinci | PDex | `hl7.fhir.us.davinci-pdex@2.1.0` | R4 |
-| DaVinci | DTR | `hl7.fhir.us.davinci-dtr@2.1.0` | R4 |
-| DaVinci | Alerts | `hl7.fhir.us.davinci-alerts@1.0.0` | R4 |
-| DaVinci | DEQM | `hl7.fhir.us.davinci-deqm@4.0.0` | R4 |
-| DaVinci | Drug Formulary | `hl7.fhir.us.davinci-drug-formulary@2.1.0` | R4 |
-| Universal | IPS | `hl7.fhir.uv.ips@2.0.0` | R4 |
-| Universal | SMART App Launch | `hl7.fhir.uv.smart-app-launch@2.2.0` | R4 |
-| Universal | SDC (Structured Data Capture) | `hl7.fhir.uv.sdc@3.0.0` | R4 |
-| Universal | Genomics Reporting | `hl7.fhir.uv.genomics-reporting@3.0.0` | R4 |
-| Universal | CPG (Clinical Practice Guidelines) | `hl7.fhir.uv.cpg@2.0.0` | R4 |
-| DE | ISiK Basis | `de.gematik.isik-basismodul@4.0.3` | R4 |
-| DE | KBV eRezept | `kbv.ita.erp@1.1.1` | R4 |
-| DE | DE Basisprofil | `de.basisprofil.r4@1.5.0` | R4 |
-| DE | ISiK Medikation | `de.gematik.isik-medikation@4.0.1` | R4 |
-| CH | CH Core (Switzerland) | `ch.fhir.ig.ch-core@5.0.0` | R4 |
-| AU | AU Core (Australia) | `hl7.fhir.au.core@1.0.0` | R4 |
-| IHE | PIXm | `ihe.iti.pixm@3.0.4` | R4 |
-| IHE | MHD | `ihe.iti.mhd@4.2.2` | R4 |
-| R5 | AE Research (R5) | `hl7.fhir.uv.ae-research-ig@1.0.1` | R5 |
-| R5 | eMedicinal Product (R5) | `hl7.fhir.uv.emedicinal-product-info@1.0.0` | R5 |
-
-### Validation with Firely .NET SDK
-
-The first pipeline validates generated resources using the [Firely .NET SDK validator](https://docs.fire.ly/projects/Firely-NET-SDK/). Results are published as live badges:
+5. Validates those resources against two independent external FHIR validators
+
+### Validated Implementation Guides (30)
+
+Every parity run validates **30 real-world IGs** (28 R4, 2 R5). The list is not duplicated here — it is generated from the parity suite's own source of truth into [`parity-matrix.json`](./parity-matrix.json).
+
+Each validated IG is also published as a ready-to-install package — `@max-health-inc/fhir-<name>` — so you do not have to generate it yourself:
+
+**[→ Browse the FHIR IG registry](https://github.com/orgs/Max-Health-Inc/packages?ecosystem=npm&q=fhir-)**
+
+```bash
+# GitHub Packages needs the scope mapped, and a token with read:packages
+echo "@max-health-inc:registry=https://npm.pkg.github.com" >> .npmrc
+npm install @max-health-inc/fhir-us-core
+```
+
+Published by [Max-Health-Inc/fhir-igs](https://github.com/Max-Health-Inc/fhir-igs), which pins a babelfhir-ts version and republishes an IG only when the IG version, the pinned generator, or the generation flags actually change.
+
+### Validation with the Firely SDK Validator
+
+The `firely` job validates generated resources using the [Firely SDK Validator](https://docs.fire.ly/projects/Firely-NET-SDK/validation.html) (`Firely.Fhir.Validation`, v3.x) running on the Firely .NET SDK (`Hl7.Fhir`, v6.x) — two separately versioned packages. Results are published as live badges:
+
+<details><summary>Per-IG results</summary>
 
 ![US Core](https://img.shields.io/endpoint?url=https://max-health-inc.github.io/BabelFHIR-TS/badges/badge-us-core.json)
 ![QI-Core](https://img.shields.io/endpoint?url=https://max-health-inc.github.io/BabelFHIR-TS/badges/badge-qicore.json)
@@ -129,9 +112,13 @@ The first pipeline validates generated resources using the [Firely .NET SDK vali
 ![PIXm](https://img.shields.io/endpoint?url=https://max-health-inc.github.io/BabelFHIR-TS/badges/badge-pixm.json)
 ![MHD](https://img.shields.io/endpoint?url=https://max-health-inc.github.io/BabelFHIR-TS/badges/badge-mhd.json)
 
+</details>
+
 ### Validation with HL7 Java Validator
 
-The second pipeline validates using the [official HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator), the reference implementation for FHIR conformance checking:
+The `hl7` job validates the same artifacts using the [official HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator), the reference implementation for FHIR conformance checking:
+
+<details><summary>Per-IG results</summary>
 
 ![US Core](https://img.shields.io/endpoint?url=https://max-health-inc.github.io/BabelFHIR-TS/badges/badge-hl7-us-core.json)
 ![QI-Core](https://img.shields.io/endpoint?url=https://max-health-inc.github.io/BabelFHIR-TS/badges/badge-hl7-qicore.json)
@@ -162,6 +149,10 @@ The second pipeline validates using the [official HL7 FHIR Validator](https://co
 ![PIXm](https://img.shields.io/endpoint?url=https://max-health-inc.github.io/BabelFHIR-TS/badges/badge-hl7-pixm.json)
 ![MHD](https://img.shields.io/endpoint?url=https://max-health-inc.github.io/BabelFHIR-TS/badges/badge-hl7-mhd.json)
 
+</details>
+
+> External-validator badges cover the 28 R4/R4B IGs. R5 packages are generated and typechecked, but neither external validator publishes R5 badges yet.
+
 > Terminology validation requires a tx server. The pipeline uses `--tx-server https://tx.fhir.org/{r4|r5}` (matching the package's FHIR version) during generation to expand ValueSets and produce valid codes.
 
 📊 **[Full Report](https://max-health-inc.github.io/BabelFHIR-TS/)**
@@ -192,9 +183,9 @@ babelfhir-ts install hl7.fhir.us.core@8.0.0
 ```
 
 ```ts
-import { USCorePatientClass } from "./output/USCorePatientClass";
+import { USCorePatientProfileClass } from "./output/USCorePatientProfileClass";
 
-const patient = USCorePatientClass.random();
+const patient = USCorePatientProfileClass.random();
 const { errors, warnings } = await patient.validate();
 ```
 

package/out/src/generator/core/constants.js

@@ -29,6 +29,27 @@ const packageJson = JSON.parse(require('fs').readFileSync(_pkgPath, 'utf8'));
 // ─── Package metadata ────────────────────────────────────────────────────────
 export const PACKAGE_VERSION = packageJson.version;
 export const USER_AGENT = `BabelFHIR-TS/${PACKAGE_VERSION}`;
+/**
+ * The range this build declares for `name`, from either dependency section.
+ *
+ * Lets the generated-package manifest derive its ranges from what this repo
+ * actually builds and tests against, instead of restating them in a second place
+ * that drifts on every dependency bump.
+ */
+export function ownDependencyRange(name) {
+    return packageJson.dependencies?.[name] ?? packageJson.devDependencies?.[name] ?? '';
+}
+/**
+ * The `@types/fhir` range this build depends on.
+ *
+ * `scripts/generate-fhir-r4-module.js` builds the `fhir-<version>.d.ts` ambient
+ * shims from whatever `@types/fhir` is installed here, so the shims can only
+ * resolve against a version that actually declares the aliased types. Generated
+ * packages therefore derive their own `@types/fhir` range from this one — see
+ * EMITTED_RANGES.fhirTypes in generatedPackageDeps.ts — instead of hardcoding a
+ * second range that silently drifts on every dependency bump.
+ */
+export const FHIR_TYPES_DEPENDENCY_RANGE = ownDependencyRange('@types/fhir');
 // ─── Network defaults ────────────────────────────────────────────────────────
 /** Default fetch timeout for FHIR registry / StructureDefinition lookups (ms) */
 export const FETCH_TIMEOUT_MS = 15_000;
@@ -36,6 +57,25 @@ export const FETCH_TIMEOUT_MS = 15_000;
 export const TX_TIMEOUT_MS = 30_000;
 /** Max filename length for terminology expansion cache files */
 export const MAX_CACHE_FILENAME_LENGTH = 200;
+/**
+ * FHIR package registries in priority order.
+ *
+ * packages.fhir.org is the canonical source; packages.simplifier.net is the
+ * fallback and carries some national IGs the canonical registry does not mirror.
+ * Both speak the npm metadata shape, so `GET <registry>/<packageId>` returns
+ * `dist-tags` and `versions`.
+ */
+/**
+ * Attempts per registry when downloading a package tarball.
+ *
+ * Registry blips are the single largest cause of spurious parity failures: a run
+ * pulls ~30 packages and a lone `fetch failed` aborted the whole generation.
+ */
+export const PACKAGE_DOWNLOAD_ATTEMPTS = 3;
+export const FHIR_REGISTRIES = [
+    'https://packages.fhir.org',
+    'https://packages.simplifier.net',
+];
 // ─── FHIR StructureDefinition URL prefixes ───────────────────────────────────
 export const FHIR_SD_URL_PREFIX = 'http://hl7.org/fhir/StructureDefinition/';
 export const FHIR_SD_URL_PREFIX_HTTPS = 'https://hl7.org/fhir/StructureDefinition/';

package/out/src/generator/core/generatedPackageDeps.js

@@ -9,22 +9,97 @@
  * These ranges describe what the *consumer* of a generated package installs,
  * so they are deliberately wider than this repo's own devDependencies.
  */
+import { FHIR_TYPES_DEPENDENCY_RANGE, ownDependencyRange } from './constants.js';
+/**
+ * `@types/fhir` range emitted into generated packages.
+ *
+ * Derived from this build's own `@types/fhir` dependency, never hardcoded. The
+ * emitted `fhir-<version>.d.ts` shim aliases types out of the installed
+ * `@types/fhir` (e.g. `export type MoneyQuantity = fhir4.MoneyQuantity`), so a
+ * consumer resolving an older version gets TS2694 on a type the shim references
+ * but their copy does not declare — `MoneyQuantity` does not exist at all before
+ * @types/fhir 0.0.42. This repo's own output typecheck cannot catch that,
+ * because `resolveGeneratorTypeRoots()` points `typeRoots` at babelfhir's own
+ * always-present `@types` — so the floor has to be correct by construction.
+ *
+ * A floor rather than an exact pin, and this is the part that used to be wrong:
+ * `^0.0.41` looks like a floor but npm's caret on `0.0.x` resolves to exactly
+ * 0.0.41. Consumers routinely install several generated packages alongside their
+ * own `@types/fhir`, so exact pins across them would conflict or install nested
+ * duplicates — two `fhir` global namespaces. Capped below 0.1.0 because
+ * `@types/fhir` 1.x/3.x restructure the namespaces entirely.
+ */
+function emittedFhirTypesRange() {
+    const floor = FHIR_TYPES_DEPENDENCY_RANGE.replace(/^[^0-9]*/, '');
+    if (!/^0\.0\.\d+$/.test(floor)) {
+        throw new Error(`Cannot derive the emitted @types/fhir range from "${FHIR_TYPES_DEPENDENCY_RANGE}" — ` +
+            `expected a 0.0.x version. Moving off the 0.0.x line needs a new upper bound here.`);
+    }
+    return `>=${floor} <0.1.0`;
+}
+/**
+ * `zod` range emitted as a peer for `--schema zod` output.
+ *
+ * Straight pass-through of this build's own range — no widening. Emitted schemas
+ * are generated against the installed zod, so advertising a broader range than
+ * was tested is the same class of mistake `^0.0.41` was: a manifest claiming
+ * support the artifact beside it does not have.
+ */
+function emittedZodRange() {
+    const range = ownDependencyRange('zod');
+    if (!range) {
+        throw new Error('Cannot derive the emitted zod range — this package declares no zod dependency.');
+    }
+    return range;
+}
 /**
  * Runtime/peer ranges emitted into generated packages.
  *
- * `fhirpath` is a peer so the host decides the version. All of 3.x/4.x/5.x are
- * accepted: generated validators only call `fhirpath.evaluate()` and import
- * `fhirpath/fhir-context/<model>/index.js`, both of which are stable across
- * those majors. The `/index.js` filename is required — fhirpath >= 5 declares
- * an `exports` map, so extensionless deep paths no longer resolve.
+ * `fhirpath` and `zod` are peers so the host owns the version; everything else is
+ * a direct dependency of the generated package.
  */
 export const EMITTED_RANGES = {
-    /** FHIR type declarations backing the emitted `.d.ts` files. */
-    fhirTypes: '^0.0.41',
-    /** FHIRPath engine used by emitted constraint validators. */
-    fhirpath: '^3.0.0 || ^4.0.0 || ^5.0.0',
-    /** Schema runtime for `--schema zod` output. */
-    zod: '^4.0.0',
+    /**
+     * FHIR type declarations backing the emitted `.d.ts` files.
+     *
+     * A getter, not a computed value: emittedFhirTypesRange() throws when the
+     * derivation no longer holds, and evaluating that at module load would take
+     * down every import of this module — `babelfhir-ts --version` included. As a
+     * getter the failure is confined to the code that actually emits a manifest,
+     * which is the only place a wrong range does damage.
+     */
+    get fhirTypes() {
+        return emittedFhirTypesRange();
+    },
+    /**
+     * FHIRPath engine used by emitted constraint validators.
+     *
+     * The floor is 4.9.1, not 3.x. Emitted validators evaluate `constraint.expression`
+     * verbatim from the IG, and fhirpath 3.x cannot parse the `as` alias form that
+     * IGs use freely — `(value as Quantity).value.exists()` throws
+     * `Do not know how to alias as by {"is":"isOp"}`. The emitted `evaluate()` call
+     * is wrapped in try/catch only for expressions containing `resolve()`, so on 3.x
+     * that surfaces as `validate()` rejecting rather than returning errors. 4.9.1 is
+     * the floor this repo set when it unlocked `.as()`/`.ofType()`/`is` (24308d806),
+     * develop shipped on 4.10.x, and CI runs 5.x.
+     *
+     * Capped below 6.0.0: majors do break consumers here. 5.x added an `exports`
+     * map, which is why the emitted import carries an explicit
+     * `/fhir-context/<model>/index.js` filename.
+     */
+    fhirpath: '>=4.9.1 <6.0.0',
+    /**
+     * Schema runtime for `--schema zod` output.
+     *
+     * Passed through from this build's own `zod` range rather than restated, so the
+     * emitted peer is exactly what the generated schemas were produced and tested
+     * against. That range is currently an exact pin (`4.3.6`), which is deliberate:
+     * emitted schemas use `z.looseObject` and `z.infer`, and zod has moved those
+     * across minors before. A host must therefore land on the same version.
+     */
+    get zod() {
+        return emittedZodRange();
+    },
     /**
      * Prefab UI runtime for `--prefab` output.
      *

package/out/src/generator/core/utils.js

@@ -24,6 +24,38 @@ export function capitalize(str) {
         return str;
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
+/**
+ * The property name a choice element takes for one of its permitted types.
+ *
+ * A choice element has no property of its own: FHIR declares one property per
+ * permitted type, named for the type code capitalized (`value[x]` as a
+ * SampledData is `valueSampledData`, as a `code` primitive it is `valueCode`).
+ *
+ * Pass the *type code*, never a profile name. R4 declares
+ * `Coverage.costToBeneficiary.value[x]` as a Quantity profiled to SimpleQuantity,
+ * and the property is `valueQuantity` — `valueSimpleQuantity` does not exist on
+ * any resource, so emitting it produces data every validator rejects.
+ *
+ * @param baseName the choice element's name with `[x]` already removed
+ */
+export function choicePropertyName(baseName, typeCode) {
+    return baseName + capitalize(typeCode);
+}
+/**
+ * The single type a choice element has been narrowed to, or undefined while it
+ * still permits more than one.
+ *
+ * A still-open choice has no one property name, so callers must leave the base
+ * definition's expanded properties in force rather than pick a type.
+ */
+export function narrowedChoiceType(field) {
+    if (field.typeOptions && field.typeOptions.length > 1)
+        return undefined;
+    const type = field.typeOptions?.[0]?.code || field.type;
+    if (!type || type === 'any' || type === 'unknown')
+        return undefined;
+    return type;
+}
 /**
  * Extract base FHIR types from all interface declarations in a file.
  * Handles:
@@ -220,9 +252,16 @@ function caseAwareWriteFile(filePath, content) {
 }
 /**
  * Extracts the base resource name from a baseDefinition URL.
+ *
+ * The version suffix has to go first. A canonical may be pinned
+ * (`http://hl7.org/fhir/StructureDefinition/Base|4.0.1`, as IPS 2.0.1's logical
+ * models write it), and keeping it yielded the base name `Base_4_0_1` after
+ * sanitising. That defeated the `baseResource === 'Base'` check that suppresses
+ * extending the abstract root, so the emitter produced
+ * `export type Document = Base_4_0_1` plus an import of a type nothing generates.
  */
 export function getBaseResource(baseDefinition) {
-    return baseDefinition?.split("/").pop() || "Resource";
+    return stripVersionFromCanonicalUrl(baseDefinition ?? '').split('/').pop() || 'Resource';
 }
 /**
  * Sanitizes a string so it can be used as a valid TypeScript identifier.

package/out/src/generator/emitters/class/classGenerator.js

@@ -4,7 +4,7 @@ import { primitivePlaceholder, generateCodeDefault, makeCodeableConcept, chooseC
 import { generateSliceElement, buildNestedRequirementsObject } from './sliceElementGenerator.js';
 import { COMPLEX_SKELETON_MAP, propKey, buildValueExpression, buildCrossReferencedEntryArray, } from './classGeneratorHelpers.js';
 import { renderClassTemplate } from './classTemplate.js';
-export function generateClass(className, interfaceName, baseResource, requiredFields = [], profileUrl, fieldPatterns = [], forbiddenFields = [], valueSetBindings = {}, fieldOrder = []) {
+export function generateClass(className, interfaceName, baseResource, requiredFields = [], profileUrl, fieldPatterns = [], forbiddenFields = [], valueSetBindings = {}, fieldOrder = [], codeableConceptBindings = []) {
     // Decide whether to emit resourceType. If baseResource points at a known resource or ends with 'Resource'.
     const CORE_RESOURCE_BASES = ctx().coreResourceBases;
     const addResourceType = !!baseResource && CORE_RESOURCE_BASES.has(baseResource);
@@ -572,5 +572,6 @@ export function generateClass(className, interfaceName, baseResource, requiredFi
         profileUrl, constructorMetaProfile, setterMetaProfile,
         randomMetaProfileInit, resourceTypeLine, baseResource,
         fieldPatterns, forbiddenFields, valueSetBindings, fieldOrder,
+        codeableConceptBindings,
     });
 }

package/out/src/generator/emitters/class/classGeneratorHelpers.js

@@ -88,7 +88,7 @@ export function buildCrossReferencedEntryArray(sliceElements) {
     return `(() => { ${decls.join(' ')} return [${rewritten.join(', ')}]; })()`;
 }
 /** Generate the static pattern/forbidden/order/binding metadata properties for a class. */
-export function generatePatternMetadata(fieldPatterns, forbiddenFields, valueSetBindings, fieldOrder = []) {
+export function generatePatternMetadata(fieldPatterns, forbiddenFields, valueSetBindings, fieldOrder = [], codeableConceptBindings = []) {
     const patternMap = {};
     for (const fp of fieldPatterns) {
         patternMap[fp.fieldName] = fp.pattern;
@@ -107,6 +107,13 @@ export function generatePatternMetadata(fieldPatterns, forbiddenFields, valueSet
   /** ValueSet bindings for coded fields - maps field name to ValueSet URL */
   static readonly valueSetBindings: Record<string, string> = ${JSON.stringify(valueSetBindings, null, 2)};
 
+  /**
+   * Bound fields declared as CodeableConcept rather than a code primitive.
+   * enrichResource emits \`{ coding: [...] }\` for these; a bare code string would
+   * be rejected as "must be an Object, not a Primitive property".
+   */
+  protected static readonly _codeableConceptBindings: string[] = ${JSON.stringify(codeableConceptBindings)};
+
   /** Code resolver for ValueSet bindings - returns a random valid code from a ValueSet by URL */
   protected static readonly _codeResolver: ((url: string) => { code: string; system: string; display?: string } | undefined) | undefined = ${hasBindings ? `(() => {
     // Try to load the ValueSetRegistry - it may not exist if no ValueSets were generated

package/out/src/generator/emitters/class/classTemplate.js

@@ -1,7 +1,7 @@
 import { COMPLEX_SKELETON_MAP, generatePatternMetadata } from './classGeneratorHelpers.js';
 /** Render the final class file content from pre-computed template parameters. */
 export function renderClassTemplate(params) {
-    const { interfaceName, className, requiredInitBlock, enableMetaProfile, profileUrl, constructorMetaProfile, setterMetaProfile, randomMetaProfileInit, resourceTypeLine, baseResource, fieldPatterns, forbiddenFields, valueSetBindings, fieldOrder, } = params;
+    const { interfaceName, className, requiredInitBlock, enableMetaProfile, profileUrl, constructorMetaProfile, setterMetaProfile, randomMetaProfileInit, resourceTypeLine, baseResource, fieldPatterns, forbiddenFields, valueSetBindings, fieldOrder, codeableConceptBindings, } = params;
     // Determine which skeleton helpers are actually used in requiredInitBlock
     const usedSkeletons = new Set();
     for (const helper of Object.values(COMPLEX_SKELETON_MAP)) {
@@ -54,7 +54,7 @@ function safeClone<T>(value: T): T {
 }
 
 export class ${className} {
-${generatePatternMetadata(fieldPatterns, forbiddenFields, valueSetBindings, fieldOrder)}
+${generatePatternMetadata(fieldPatterns, forbiddenFields, valueSetBindings, fieldOrder, codeableConceptBindings)}
   constructor(private resource: ${interfaceName}) {
     ${constructorMetaProfile}
   }
@@ -108,7 +108,7 @@ ${generatePatternMetadata(fieldPatterns, forbiddenFields, valueSetBindings, fiel
   // Always include meta.profile with this profile's canonical URL if available & only for resource profiles
   ${randomMetaProfileInit}
   // Enrich the base resource with common fields using centralized enrichment logic
-  enrichResource(base, '${baseResource || ''}', '${profileUrl || ''}', ${className}._fieldPatterns, ${className}._forbiddenFields, ${className}.valueSetBindings, ${className}._codeResolver, ${className}._fieldOrder);
+  enrichResource(base, '${baseResource || ''}', '${profileUrl || ''}', ${className}._fieldPatterns, ${className}._forbiddenFields, ${className}.valueSetBindings, ${className}._codeResolver, ${className}._fieldOrder, ${className}._codeableConceptBindings);
   // Cast through unknown to acknowledge dynamic enrichment
   return { ...(base as unknown as ${interfaceName}), ...overrides };
   }

package/out/src/generator/emitters/class/enrichContextTemplate.js

@@ -16,6 +16,13 @@ export interface EnrichContext {
   codeResolver?: (valueSetUrl: string) => { code: string; system: string; display?: string } | undefined;
   fieldOrder: string[];
   isForbidden: (fieldName: string) => boolean;
+  /**
+   * True when a ValueSet-bound field is declared as CodeableConcept rather than a
+   * code primitive. R4 types status as a code, but several R5 product resources
+   * type it as CodeableConcept, and writing a bare string there is rejected with
+   * "must be an Object, not a Primitive property".
+   */
+  isCodeableConceptBinding: (fieldName: string) => boolean;
   resolveBindingCode: (fieldName: string, fallbackSystem?: string, fallbackCode?: string, fallbackDisplay?: string) => { coding: Array<{ system: string; code: string; display?: string }>; text?: string } | undefined;
   resolveBindingCodePrimitive: (fieldName: string, fallbackCode?: string) => string | undefined;
   getPatternValue: (fieldName: string) => unknown | undefined;
@@ -37,8 +44,11 @@ export function createEnrichContext(
   valueSetBindings: Record<string, string>,
   codeResolver: ((valueSetUrl: string) => { code: string; system: string; display?: string } | undefined) | undefined,
   fieldOrder: string[],
+  codeableConceptBindings: string[] = [],
 ): EnrichContext {
   const isForbidden = (fieldName: string): boolean => forbiddenFields.includes(fieldName);
+  const isCodeableConceptBinding = (fieldName: string): boolean =>
+    codeableConceptBindings.includes(fieldName);
 
   const resolveBindingCode = (fieldName: string, fallbackSystem?: string, fallbackCode?: string, fallbackDisplay?: string) => {
     const bindingUrl = valueSetBindings[fieldName];
@@ -158,7 +168,7 @@ export function createEnrichContext(
   return {
     base, baseResource, profileUrl, fieldPatterns, forbiddenFields,
     valueSetBindings, codeResolver, fieldOrder,
-    isForbidden, resolveBindingCode, resolveBindingCodePrimitive,
+    isForbidden, isCodeableConceptBinding, resolveBindingCode, resolveBindingCodePrimitive,
     getPatternValue, getRawCodeableConceptPattern, mergeCodingPatterns,
     getCompleteCodePatternValue, getPrimitivePattern, applyNestedPatterns,
     getRefRequirements,

package/out/src/generator/emitters/class/enrichCtxTransform.js

@@ -4,6 +4,7 @@
  */
 const CTX_FUNCTIONS = [
     'isForbidden',
+    'isCodeableConceptBinding',
     'resolveBindingCode',
     'resolveBindingCodePrimitive',
     'getPatternValue',

package/out/src/generator/emitters/class/enrichResourceHandlers.js

@@ -500,10 +500,29 @@ export function generateEnrichResourceEnd() {
       }
     }
 
-    // Extension value fallback
+    // Extension value fallback.
+    //
+    // Respect the profile's value[x] type constraint: an Extension SD almost always
+    // narrows value[x] to one type, and emitting valueString regardless was the
+    // largest single source of random()-resource validation failures ("definition
+    // allows for the type CodeableConcept but found type String"). Fall back to
+    // valueString only when the profile leaves value[x] open or names a type the
+    // skeleton factories don't cover.
     if (/Extension/.test(baseResource)) {
       const hasValue = Object.keys(base).some(k => k.startsWith('value'));
-      if (!hasValue) base['valueString'] = 'value';
+      if (!hasValue) {
+        const valueTypes = fieldPatterns?.['_choiceType_value[x]'] as string[] | undefined;
+        const constrainedType = valueTypes && valueTypes.length === 1 ? valueTypes[0] : undefined;
+        const choice = skeletonChoiceValue('value', constrainedType);
+        if (!choice) {
+          base['valueString'] = 'value';
+        } else if (constrainedType === 'CodeableConcept') {
+          // A bound value[x] should carry a code from its ValueSet, not a random one.
+          base.valueCodeableConcept = resolveBindingCode('value[x]') ?? choice[1];
+        } else {
+          base[choice[0]] = choice[1];
+        }
+      }
       if (!('url' in base)) base.url = profileUrl || 'urn:uuid:extension';
     }
 

package/out/src/generator/emitters/class/enrichResourceObservationHandler.js

@@ -175,8 +175,8 @@ export function generateObservationHandler() {
           base.dataAbsentReason = { coding: [{ system: '${TS.DATA_ABSENT}', code: 'unknown' }] };
         } else {
           // Use patterns if available, otherwise derive UCUM unit from observation code
-          let defaultUnit = '1';
-          let defaultCode = '1';
+          const defaultUnit = '1';
+          const defaultCode = '1';
           if (unitPattern === undefined && codePattern === undefined) {
             // Map well-known vital sign LOINC codes to correct UCUM units
             const codeObj = base.code as { coding?: Array<{ code?: string }> } | undefined;
@@ -196,8 +196,8 @@ export function generateObservationHandler() {
             };
             if (loincCode && vitalSignUnits[loincCode]) {
               const vs = vitalSignUnits[loincCode];
-              defaultUnit = vs.unit;
-              defaultCode = vs.code;
+              // No need to update defaultUnit/defaultCode: this branch uses vs.*
+              // directly and only the else branch reads the defaults.
               base.valueQuantity = { value: vs.value, unit: vs.unit, system: '${TS.UCUM}', code: vs.code };
             } else {
               base.valueQuantity = { value: 72, unit: defaultUnit, system: '${TS.UCUM}', code: defaultCode };

package/out/src/generator/emitters/class/enrichResourceTemplate.js

@@ -18,6 +18,9 @@ export type CodeResolver = (valueSetUrl: string) => ResolvedCode | undefined;
  * @param forbiddenFields - Array of field names that are forbidden (max=0) in this profile
  * @param valueSetBindings - Map of field names to ValueSet URLs for coded bindings
  * @param codeResolver - Optional function to resolve a ValueSet URL to a random valid code
+ * @param fieldOrder - FHIR element ordering for the base resource
+ * @param codeableConceptBindings - Bound fields declared as CodeableConcept rather
+ *        than a code primitive, so a resolved code is emitted as a coding object
  */
 export function enrichResource(
   base: Record<string, unknown>,
@@ -27,11 +30,15 @@ export function enrichResource(
   forbiddenFields: string[] = [],
   valueSetBindings: Record<string, string> = {},
   codeResolver?: CodeResolver,
-  fieldOrder: string[] = []
+  fieldOrder: string[] = [],
+  codeableConceptBindings: string[] = []
 ): void {
   try {
     // Helper to check if a field is forbidden
     const isForbidden = (fieldName: string): boolean => forbiddenFields.includes(fieldName);
+
+    // Helper to check whether a bound field is a CodeableConcept rather than a code
+    const isCodeableConceptBinding = (fieldName: string): boolean => codeableConceptBindings.includes(fieldName);
     
     // Helper to resolve a code from ValueSet binding - uses codeResolver if available
     // Returns a CodeableConcept-compatible structure or undefined if not resolvable
@@ -191,13 +198,25 @@ export function enrichResource(
     // Also override generic default 'active' when it's not valid for this resource's ValueSet
     // Skip when status was already set by a fixed pattern above.
     if (statusFixedPattern === undefined && !isForbidden('status')) {
-      const resolved = resolveBindingCodePrimitive('status');
-      if (resolved) {
-        if (!('status' in base)) {
-          base.status = resolved;
-        } else if (base.status === 'active' && resolved !== 'active') {
-          // Generic 'active' default may not be valid for all resource types (e.g., ChargeItem)
-          base.status = resolved;
+      if (isCodeableConceptBinding('status')) {
+        // R5 types status as a CodeableConcept on ClinicalUseDefinition,
+        // MedicinalProductDefinition, PackagedProductDefinition,
+        // RegulatedAuthorization and SubstanceDefinition. Writing the resolved
+        // code as a bare string there fails validation with "The property status
+        // must be an Object, not a Primitive property", so emit the coding shape.
+        const resolvedConcept = resolveBindingCode('status');
+        if (resolvedConcept && (!('status' in base) || typeof base.status !== 'object')) {
+          base.status = resolvedConcept;
+        }
+      } else {
+        const resolved = resolveBindingCodePrimitive('status');
+        if (resolved) {
+          if (!('status' in base)) {
+            base.status = resolved;
+          } else if (base.status === 'active' && resolved !== 'active') {
+            // Generic 'active' default may not be valid for all resource types (e.g., ChargeItem)
+            base.status = resolved;
+          }
         }
       }
     }

package/out/src/generator/emitters/class/fieldPatternExtractor.js

@@ -373,6 +373,9 @@ export async function extractFieldPatternsAndMetadata(patternSources, baseResour
         }))];
     // Collect ValueSet bindings for all fields to expose as static metadata
     const valueSetBindings = {};
+    // Record the declared type alongside, so enrichment emits the right JSON shape
+    // for a bound field rather than assuming every binding sits on a code primitive.
+    const codeableConceptBindingSet = new Set();
     for (const f of candidateRequiredFields) {
         if (f.binding?.uri) {
             // Extract field name from path (e.g., "Observation.status" -> "status")
@@ -383,9 +386,13 @@ export async function extractFieldPatternsAndMetadata(patternSources, baseResour
                 if (!valueSetBindings[fieldName]) {
                     valueSetBindings[fieldName] = f.binding.uri;
                 }
+                if ((f.type || f.baseTypeCode) === 'CodeableConcept') {
+                    codeableConceptBindingSet.add(fieldName);
+                }
             }
         }
     }
+    const codeableConceptBindings = [...codeableConceptBindingSet];
     // Extract FHIR element ordering from the StructureDefinition snapshot.
     // The snapshot lists elements in the canonical FHIR order defined by the spec.
     // We use this to ensure enrichResource reorders fields correctly, rather than
@@ -412,5 +419,5 @@ export async function extractFieldPatternsAndMetadata(patternSources, baseResour
             fieldOrder.push(fieldName);
         }
     }
-    return { fieldPatterns, forbiddenFields, valueSetBindings, fieldOrder };
+    return { fieldPatterns, forbiddenFields, valueSetBindings, codeableConceptBindings, fieldOrder };
 }