fhir-openapi-translator 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-17
+
+Search parameters gain derived metadata and a way to emit fewer of them.
+
+No API or CLI breakage — every 0.1.1 invocation behaves as before. Generated
+output does change, though, so **a committed spec will show drift**: on an R4
+`Observation`, schemas and paths are byte-identical, 6 of 38 search parameters
+gain `x-fhir-search-values`/`x-fhir-search-prefixes` and a fuller description,
+and 4 more have trailing whitespace trimmed from HL7's description text.
+Regenerate committed specs, or `fhir-oas check` will fail in CI.
+
+### Added
+
+- `--search-params` limits which resource-specific search parameters are
+  emitted: a preset (`all`, `minimal`, `none`), an explicit code list
+  (`code,date,subject`), or per-resource (`Patient:name,birthdate`). Unknown
+  codes are an error rather than being silently dropped. Combines with
+  `--capability` by intersection. The common result parameters (`_id`,
+  `_count`, ...) are always emitted. `minimal` is tiered — common parameter
+  names first, then parameters addressing a top-level element directly, then
+  everything — so no resource that defines a search parameter is left with
+  none, while a median resource keeps 4. Presets can be tuned with `+code` and
+  `-code` (`minimal,+based-on`, `all,-note`), because no fixed rule can know
+  that `Observation.based-on`, `CarePlan.goal` or
+  `MedicationStatement.adherence` matter for their resource.
+- `fhir-oas --version` (and `-V`) prints the installed version. It is read from
+  `package.json` at runtime rather than inlined at build time, so the CLI
+  cannot report a version the package does not have.
+- `./package.json` is now a subpath export. Reaching for it previously raised
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`, which some bundlers and
+  version-introspection scripts trip over.
+- `x-fhir-search-values` on token search parameters bound to a required
+  ValueSet, and `x-fhir-search-prefixes` on `number`/`date`/`quantity`
+  parameters, listing the comparison prefixes (`eq`, `ne`, `gt`, `lt`, `ge`,
+  `le`, `sa`, `eb`, `ap`) their values may carry. Both are metadata rather than
+  schema constraints: an `enum` would reject the comma-OR, `system|code` and
+  `:modifier` forms that FHIR search permits.
+
+### Changed
+
+- Search parameter descriptions are now derived from the definitions rather
+  than passed through from HL7's prose, which is not uniform — `Encounter-status`
+  spelled its codes out while `Observation-status` did not, though both are
+  token parameters over a required binding. Every parameter of a given kind now
+  reads the same way, and reports the codes its own FHIR version defines.
+- Search parameters shared across resources carry a union expression
+  (`Patient.gender | Person.gender | ...`); the branch matching the resource
+  being generated is now resolved, so `MedicationRequest.status` and
+  `MedicationDispense.status` each report their own code list. Previously such
+  parameters were left unenumerated entirely.
+
+## [0.1.1] - 2026-09-13
+
+Three correctness fixes. Specs generated with 0.1.0 should be regenerated:
+all three produced silently wrong output rather than errors.
+
+### Fixed
+
+- **Every schema was missing its `id` property.** The OpenAPI emitter stripped
+  the JSON Schema `id`/`$id` keywords everywhere, including inside `properties`
+  maps where `id` is an ordinary FHIR element name. 660 of 679 R4 definitions
+  declare one, so nearly every generated model lacked its resource id.
+- **Binding enums were absent on R4B and R5.** Enum generation read inline
+  enums from the official `fhir.schema.json`, but HL7 stopped inlining them
+  after R4 (R4 has 246 occurrences; R4B has 27 and R5 has 26). Required-binding
+  codes are now resolved from the vendored definitions on every version, so
+  `--no-enums` is once again the only thing that turns them off.
+- **Profiles failed to generate against real IG packages.** A `contentReference`
+  written in the absolute canonical form that IG snapshot generators emit
+  (`http://hl7.org/fhir/StructureDefinition/Observation#Observation.referenceRange`)
+  was parsed as though it were the core `#Observation.referenceRange` short
+  form, producing a mangled schema name and aborting generation. US Core Blood
+  Pressure, among others, could not be generated at all.
+
+### Documentation
+
+- Corrected the `fixed[x]` → `const` claim. Real IGs usually pin values at
+  paths _inside_ a datatype or slice (`Observation.category.coding.code`).
+  Those datatypes are emitted once as shared schemas and referenced by `$ref`,
+  so such constraints cannot be represented and are **not** applied. Only fixed
+  values on elements a profile emits as their own property become a `const`.
+
+### Testing
+
+- Added `claims.test.ts`: one assertion block per README capability claim,
+  across every FHIR version, OpenAPI target and backend it claims to support.
+- Added `fidelity.test.ts`: field-level checks that use the vendored FHIR
+  definitions as an oracle instead of hand-written expectations. Covers 45
+  resources drawn from the Foundation, Base, Clinical, Financial and
+  Specialized modules, in R4/R4B/R5, down to backbone depth — cardinality,
+  requiredness, primitive JSON types, choice expansion, `_field` primitive
+  extension siblings, and `$ref` resolution.
+
+All three bugs above shared a cause: coverage that confirmed expectations at a
+single point of a multi-point matrix. Enums were asserted only on R4, profiles
+only on `us-core-patient`, and `id` never at all.
+
+## [0.1.0] - 2026-09-12
+
+Initial release.

package/README.md

@@ -2,6 +2,8 @@
 
 **Turn any FHIR resource into an OpenAPI spec — and generate typed models in any language.**
 
+[![npm version](https://img.shields.io/npm/v/fhir-openapi-translator.svg)](https://www.npmjs.com/package/fhir-openapi-translator)
+[![npm downloads](https://img.shields.io/npm/dm/fhir-openapi-translator.svg)](https://www.npmjs.com/package/fhir-openapi-translator)
 [![CI](https://github.com/krishgok/fhir-openapi-translator/actions/workflows/ci.yml/badge.svg)](https://github.com/krishgok/fhir-openapi-translator/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](https://nodejs.org)
@@ -14,9 +16,12 @@ HAPI FHIR and Firely give Java/.NET teams great FHIR models. Everyone else — G
 ## Install
 
 ```sh
-npm install fhir-openapi-translator     # library + `fhir-oas` CLI
+npm install -g fhir-openapi-translator   # `fhir-oas` on your PATH
+npm install fhir-openapi-translator      # or as a library dependency
 ```
 
+Or run it without installing: `npx fhir-oas generate Patient --fhir-version r4`
+
 Node.js ≥ 20. FHIR definitions ship with the package — no network, no server.
 
 ## Quick start
@@ -45,6 +50,9 @@ fhir-oas generate Patient -f r4 --operations
 # Apply an Implementation Guide profile (e.g. US Core)
 fhir-oas generate Patient -f r4 --ig hl7.fhir.us.core@5.0.1 --profile us-core-patient
 
+# Emit only the search parameters your deployment indexes (38 -> 9 here)
+fhir-oas generate Observation -f r4 --search-params minimal,+based-on
+
 # Match one server's declared surface (reads its /metadata)
 fhir-oas generate -f r4 --capability https://server.example.org/fhir
 
@@ -71,16 +79,17 @@ const doc = generateOpenApi({ resources: ["Patient"], fhirVersion: "r4" });
 - **Custom operations** from the official OperationDefinitions.
 - **Profiles / IGs** — apply US Core-style constraints from any IG package.
 - **CapabilityStatement-driven** — generate exactly what a server supports.
+- **Search parameters, documented and tunable** — accepted codes and comparison prefixes per FHIR version; emit only the ones your deployment indexes.
 - **Merge mode & drift guard** — coexist with hand-written specs, catch drift in CI.
 
 ## Where it fits
 
-|  | fhir-openapi-translator | HAPI / Firely |
-|---|:---:|:---:|
-| Output | OpenAPI (→ any language) | Java / .NET models |
-| Runtime needed | none (offline CLI) | a running server / SDK |
-| US Core / IG profiles | ✅ | ✅ |
-| Per-resource, codegen-tuned specs | ✅ | — |
+|                                   | fhir-openapi-translator  |     HAPI / Firely      |
+| --------------------------------- | :----------------------: | :--------------------: |
+| Output                            | OpenAPI (→ any language) |   Java / .NET models   |
+| Runtime needed                    |    none (offline CLI)    | a running server / SDK |
+| US Core / IG profiles             |            ✅            |           ✅           |
+| Per-resource, codegen-tuned specs |            ✅            |           —            |
 
 **Complements a FHIR SDK, doesn't replace it.** Keep HAPI or Firely for server-side models and conformance — this produces the OpenAPI contract around them: for consumers in any language, and for the tooling you already run (gateways, mock servers, contract tests).
 

package/dist/{chunk-G3DCRADV.js → chunk-RRAIF3A2.js}

@@ -326,7 +326,8 @@ function buildElementTree(sd) {
   return root;
 }
 function contentReferenceName(reference, sd, rootName) {
-  const path3 = reference.replace(/^#/, "");
+  const hash = reference.lastIndexOf("#");
+  const path3 = hash >= 0 ? reference.slice(hash + 1) : reference;
   const [root, ...rest] = path3.split(".");
   if (rest.length === 0) return root ?? path3;
   const prefix = root === (sd.type ?? sd.name) ? rootName : root ?? "";
@@ -495,6 +496,148 @@ function applyProfile(context, requested, registry) {
   return { schemaName, resourceType: profile.type, url: profile.url };
 }
 
+// src/searchParams.ts
+var SEARCH_PREFIXES = ["eq", "ne", "gt", "lt", "ge", "le", "sa", "eb", "ap"];
+var PREFIXABLE_TYPES = /* @__PURE__ */ new Set(["number", "date", "quantity"]);
+function prefixesFor(searchParamType) {
+  return PREFIXABLE_TYPES.has(searchParamType) ? SEARCH_PREFIXES : void 0;
+}
+function requiredBindingCodes(fhirVersion) {
+  const index = /* @__PURE__ */ new Map();
+  for (const sd of loadStructureDefinitions(fhirVersion)) {
+    for (const el of sd.elements) {
+      if (el.binding?.strength === "required" && el.binding.codes?.length) {
+        index.set(el.path, el.binding.codes);
+      }
+    }
+  }
+  return index;
+}
+var bindingCache = /* @__PURE__ */ new Map();
+function searchParamCodes(fhirVersion, resource, type, expression) {
+  if (type !== "token" || !expression) return void 0;
+  const branch = expression.split("|").map((part) => part.trim()).find((part) => part.startsWith(`${resource}.`) || !expression.includes("|"));
+  if (!branch || !/^[A-Za-z]+(?:\.[A-Za-z]+)+$/.test(branch)) return void 0;
+  if (branch.split(".")[0] !== resource) return void 0;
+  let index = bindingCache.get(fhirVersion);
+  if (!index) {
+    index = requiredBindingCodes(fhirVersion);
+    bindingCache.set(fhirVersion, index);
+  }
+  return index.get(branch);
+}
+var COMMON_CODES = /* @__PURE__ */ new Set([
+  "identifier",
+  "status",
+  "patient",
+  "subject",
+  "encounter",
+  "code",
+  "category",
+  "date",
+  "type",
+  "url",
+  "name"
+]);
+function directElementBranch(resource, expression) {
+  if (!expression) return void 0;
+  const branch = expression.split("|").map((part) => part.trim()).find((part) => part.startsWith(`${resource}.`));
+  return branch && /^[A-Za-z]+\.[A-Za-z]+$/.test(branch) ? branch : void 0;
+}
+function minimalCodes(resource, available) {
+  const common = available.filter((sp) => COMMON_CODES.has(sp.code));
+  if (common.length > 0) return new Set(common.map((sp) => sp.code));
+  const direct = available.filter((sp) => directElementBranch(resource, sp.expression));
+  if (direct.length > 0) return new Set(direct.map((sp) => sp.code));
+  return new Set(available.map((sp) => sp.code));
+}
+var PRESETS = /* @__PURE__ */ new Set(["all", "minimal", "none"]);
+function parseOne(value) {
+  const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+  if (parts.length === 0) throw new Error(`--search-params: empty selection in "${value}"`);
+  const add = /* @__PURE__ */ new Set();
+  const remove = /* @__PURE__ */ new Set();
+  const literal = /* @__PURE__ */ new Set();
+  let preset;
+  for (const [index, part] of parts.entries()) {
+    if (part.startsWith("+") || part.startsWith("-")) {
+      const code = part.slice(1);
+      if (!code) throw new Error(`--search-params: "${part}" names no parameter`);
+      (part.startsWith("+") ? add : remove).add(code);
+      continue;
+    }
+    const lower = part.toLowerCase();
+    if (PRESETS.has(lower)) {
+      if (index !== 0) {
+        throw new Error(
+          `--search-params: preset "${part}" must come first in "${value}" (e.g. "minimal,+${parts[0]}").`
+        );
+      }
+      preset = lower;
+      continue;
+    }
+    literal.add(part);
+  }
+  if (preset && literal.size > 0) {
+    throw new Error(
+      `--search-params: "${value}" mixes the preset "${preset}" with bare codes ${[...literal].map((c) => `"${c}"`).join(", ")}. Prefix them with + to add to the preset, or drop the preset to list codes exactly.`
+    );
+  }
+  const rule = { base: preset ?? literal };
+  if (add.size > 0) rule.add = add;
+  if (remove.size > 0) rule.remove = remove;
+  return rule;
+}
+function parseSearchParamSpec(specs) {
+  const selection = {};
+  const byResource = /* @__PURE__ */ new Map();
+  for (const spec of specs) {
+    const colon = spec.indexOf(":");
+    if (colon > 0 && /^[A-Z][A-Za-z]*$/.test(spec.slice(0, colon))) {
+      const resource = spec.slice(0, colon);
+      if (byResource.has(resource)) {
+        throw new Error(`--search-params: ${resource} given more than once`);
+      }
+      byResource.set(resource, parseOne(spec.slice(colon + 1)));
+      continue;
+    }
+    if (selection.default !== void 0) {
+      throw new Error(
+        `--search-params: more than one unscoped selection ("${spec}"). Scope them per resource (Patient:name,birthdate) or pass a single list.`
+      );
+    }
+    selection.default = parseOne(spec);
+  }
+  if (byResource.size > 0) selection.byResource = byResource;
+  return selection;
+}
+function resolveSearchParamCodes(selection, fhirVersion, resource) {
+  const rule = selection?.byResource?.get(resource) ?? selection?.default;
+  if (rule === void 0) return void 0;
+  if (rule.base === "all" && !rule.add && !rule.remove) return void 0;
+  const available = loadSearchParameters(fhirVersion).filter((sp) => sp.base.includes(resource));
+  const codes = new Set(available.map((sp) => sp.code));
+  const named = [
+    ...typeof rule.base === "string" ? [] : rule.base,
+    ...rule.add ?? [],
+    ...rule.remove ?? []
+  ];
+  const unknown = named.filter((code) => !codes.has(code));
+  if (unknown.length > 0) {
+    throw new Error(
+      `--search-params: ${resource} has no search parameter ${unknown.map((c) => `"${c}"`).join(", ")} in ${fhirVersion.toUpperCase()}. Run "fhir-oas generate ${resource} -f ${fhirVersion}" to see the available codes.`
+    );
+  }
+  let selected;
+  if (rule.base === "all") selected = new Set(codes);
+  else if (rule.base === "none") selected = /* @__PURE__ */ new Set();
+  else if (rule.base === "minimal") selected = minimalCodes(resource, available);
+  else selected = new Set(rule.base);
+  for (const code of rule.add ?? []) selected.add(code);
+  for (const code of rule.remove ?? []) selected.delete(code);
+  return selected;
+}
+
 // src/backends/schemaJson.ts
 function buildRegistryFromSchemaJson(fhirVersion) {
   const schema = loadFhirSchema(fhirVersion);
@@ -508,8 +651,44 @@ function buildRegistryFromSchemaJson(fhirVersion) {
       return props?.resourceType !== void 0 && "const" in (props.resourceType ?? {});
     }).map(([name]) => name);
   }
+  applyBindingEnums(definitions, fhirVersion);
   return { fhirVersion, definitions, resourceNames };
 }
+var lowerFirst = (s) => s.charAt(0).toLowerCase() + s.slice(1);
+function elementPathFor(definitionName, property) {
+  const [root, ...backbones] = definitionName.split("_");
+  return [root, ...backbones.map(lowerFirst), property].join(".");
+}
+function bindingCodeIndex(fhirVersion) {
+  const index = /* @__PURE__ */ new Map();
+  for (const sd of loadStructureDefinitions(fhirVersion)) {
+    for (const el of sd.elements) {
+      if (el.binding?.strength === "required" && el.binding.codes?.length) {
+        index.set(el.path, el.binding.codes);
+      }
+    }
+  }
+  return index;
+}
+function applyBindingEnums(definitions, fhirVersion) {
+  const codesByPath = bindingCodeIndex(fhirVersion);
+  const isCodeRef = (node) => !!node && node.$ref === "#/definitions/code";
+  for (const [name, definition] of definitions) {
+    const properties = definition.properties;
+    if (!properties) continue;
+    for (const [property, schema] of Object.entries(properties)) {
+      const codes = codesByPath.get(elementPathFor(name, property));
+      if (!codes) continue;
+      const description = schema.description;
+      const withDescription = (node) => description ? { description, ...node } : node;
+      if (isCodeRef(schema)) {
+        properties[property] = withDescription({ enum: [...codes] });
+      } else if (schema.type === "array" && isCodeRef(schema.items)) {
+        properties[property] = withDescription({ type: "array", items: { enum: [...codes] } });
+      }
+    }
+  }
+}
 
 // src/backends/structureDefinition.ts
 function buildRegistryFromStructureDefinitions(fhirVersion) {
@@ -593,9 +772,22 @@ function convertNode(node, target, options) {
     switch (key) {
       case "$schema":
       case "$comment":
+      // Draft-04/06 schema keywords. These are only keywords at schema-node
+      // level: inside `properties` the same names are FHIR element names, and
+      // nearly every FHIR element has an `id`. See the "properties" case.
       case "id":
       case "$id":
         break;
+      case "properties": {
+        const converted = {};
+        for (const [propertyName, propertySchema] of Object.entries(
+          value ?? {}
+        )) {
+          converted[propertyName] = convertNode(propertySchema, target, options);
+        }
+        out.properties = converted;
+        break;
+      }
       case "$ref":
         out.$ref = typeof value === "string" && value.startsWith(DEFINITIONS_REF) ? COMPONENTS_REF + value.slice(DEFINITIONS_REF.length) : value;
         break;
@@ -870,16 +1062,41 @@ function commonSearchParameterComponents() {
   }
   return out;
 }
+function isCodeListDescription(description) {
+  return description.includes("|") && /^[A-Za-z0-9\-.\s|+]+$/.test(description);
+}
+function describeSearchParameter(description, codes, prefixes) {
+  let base = description.trim();
+  if (codes?.length && isCodeListDescription(base)) base = "";
+  const notes = [];
+  if (codes?.length) notes.push(`Accepted values: ${codes.join(" | ")}.`);
+  if (prefixes?.length) {
+    notes.push(`Values may carry a comparison prefix (${prefixes.join(", ")}), e.g. ge2021-01-01.`);
+  }
+  if (notes.length === 0) return base;
+  if (base.length === 0) return notes.join(" ");
+  const separator = base.includes("\n") ? "\n\n" : /[.?!]$/.test(base) ? " " : ". ";
+  return `${base}${separator}${notes.join(" ")}`;
+}
 function resourceSearchParameters(fhirVersion, resource, only) {
-  return loadSearchParameters(fhirVersion).filter((sp) => sp.base.includes(resource) && (!only || only.has(sp.code))).sort((a, b) => a.code.localeCompare(b.code)).map((sp) => ({
-    name: sp.code,
-    in: "query",
-    required: false,
-    description: sp.description,
-    // FHIR search values carry prefixes and modifiers, so all are strings.
-    schema: { type: "string" },
-    "x-fhir-search-type": sp.type
-  }));
+  return loadSearchParameters(fhirVersion).filter((sp) => sp.base.includes(resource) && (!only || only.has(sp.code))).sort((a, b) => a.code.localeCompare(b.code)).map((sp) => {
+    const codes = searchParamCodes(fhirVersion, resource, sp.type, sp.expression);
+    const prefixes = prefixesFor(sp.type);
+    return {
+      name: sp.code,
+      in: "query",
+      required: false,
+      description: describeSearchParameter(sp.description ?? "", codes, prefixes),
+      // FHIR search values carry prefixes and modifiers, so all are strings.
+      // The accepted values are advertised via x-fhir-search-values rather
+      // than `enum`, which would reject the comma-OR (`status=final,amended`),
+      // system|code and `:modifier` forms that FHIR search permits.
+      schema: { type: "string" },
+      "x-fhir-search-type": sp.type,
+      ...codes?.length ? { "x-fhir-search-values": codes } : {},
+      ...prefixes?.length ? { "x-fhir-search-prefixes": prefixes } : {}
+    };
+  });
 }
 var historyParameters = () => [
   { $ref: `${PARAMETERS}_count` },
@@ -1165,11 +1382,13 @@ function generateOpenApi(options) {
   const paths = {};
   for (const resource of resources) {
     const cap = capabilityByResource.get(resource);
+    const selected = resolveSearchParamCodes(options.searchParams, options.fhirVersion, resource);
+    const searchParamCodes2 = cap?.searchParamCodes && selected ? new Set([...selected].filter((code) => cap.searchParamCodes.has(code))) : selected ?? cap?.searchParamCodes;
     Object.assign(
       paths,
       buildResourcePaths(options.fhirVersion, resource, schemaFor(resource), {
         interactions: cap?.interactions,
-        searchParamCodes: cap?.searchParamCodes
+        searchParamCodes: searchParamCodes2
       })
     );
   }
@@ -1417,6 +1636,7 @@ export {
   loadIg,
   loadIgSync,
   buildCoreValueSetFallback,
+  parseSearchParamSpec,
   listResources,
   generateOpenApi,
   loadCapabilityStatement,
@@ -1426,4 +1646,4 @@ export {
   diffAgainstYaml,
   stringifyDocument
 };
-//# sourceMappingURL=chunk-G3DCRADV.js.map
+//# sourceMappingURL=chunk-RRAIF3A2.js.map