fhir-openapi-translator 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+type FhirVersion = "r4" | "r4b" | "r5";
+declare const FHIR_VERSIONS: readonly FhirVersion[];
+declare const FHIR_VERSION_NUMBERS: Record<FhirVersion, string>;
+type OpenApiVersion = "3.0.3" | "3.1.0";
+type SourceBackend = "schema-json" | "structure-def";
+interface TrimOptions {
+    /**
+     * Replace the Narrative type (human-readable HTML in `Resource.text`) with a
+     * generic object. Shrinks generated models that never render narratives.
+     */
+    excludeNarrative?: boolean;
+    /**
+     * Stub out schema definitions first reached deeper than this many hops from
+     * a requested resource with a generic object. Bounds the size of the
+     * dependency closure for codegen targets that struggle with large graphs.
+     */
+    maxDepth?: number;
+    /**
+     * Replace required-binding enums on code fields with plain strings (the
+     * allowed codes are appended to the description). Codegen'd models then
+     * tolerate servers that return codes outside the strict ValueSet — a common
+     * reality with legacy data. `resourceType` discriminators keep their enum.
+     */
+    noEnums?: boolean;
+}
+/** An IG package resolved to profiles + terminology (see ig/package.ts). */
+interface IgContextLike {
+    name: string;
+    version: string;
+    fhirVersion: FhirVersion;
+    profiles: unknown[];
+    profilesMissingSnapshot: string[];
+    resolveValueSet: (valueSetUrl: string) => string[] | undefined;
+}
+/** A parsed CapabilityStatement (see capability.ts). */
+interface CapabilityLike {
+    fhirVersion?: string;
+    resources: {
+        type: string;
+        interactions: Set<string>;
+        searchParamCodes: Set<string>;
+        operations: Set<string>;
+    }[];
+}
+interface GenerateOptions {
+    /**
+     * FHIR resource names, e.g. ["Patient", "Observation"]. Optional when a
+     * `capability` statement is given (its declared resources are used); when
+     * both are set, generation is narrowed to the requested resources.
+     */
+    resources?: string[];
+    fhirVersion: FhirVersion;
+    /**
+     * A parsed CapabilityStatement restricting generation to one server's
+     * declared support (resources, interactions, search params, operations).
+     * Use `loadCapabilityStatement` / `parseCapabilityStatement` to build it.
+     */
+    capability?: CapabilityLike;
+    /**
+     * IG package to apply profiles from: a local path (`.tgz` or unpacked
+     * directory) loaded synchronously, or a pre-resolved IgContext (use the
+     * async `loadIg` for registry coordinates). Required when `profiles` is set.
+     */
+    ig?: string | IgContextLike;
+    /**
+     * Profile ids, names, or canonical URLs to apply to their base resources.
+     * Each profiled resource's schemas/paths reference the named profile schema.
+     */
+    profiles?: string[];
+    /** Target OpenAPI version. Default: "3.0.3" (widest codegen support). */
+    openApiVersion?: OpenApiVersion;
+    /** Definition source backend. Default: "schema-json". */
+    source?: SourceBackend;
+    /**
+     * Also emit the standard FHIR operations applicable to the requested
+     * resources ($everything, $validate, ...) from the official
+     * OperationDefinitions. Default: false.
+     */
+    operations?: boolean;
+    /** Server base URL for the `servers` entry. Omitted when not given. */
+    baseUrl?: string;
+    /** Override the generated `info.title`. */
+    title?: string;
+    trim?: TrimOptions;
+}
+/** A generated OpenAPI document (3.0.3 or 3.1.0) as a plain object. */
+type OpenApiDocument = {
+    [key: string]: unknown;
+};
+
+/** Lists the resource type names available for a FHIR version. */
+declare function listResources(fhirVersion: FhirVersion, source?: SourceBackend): string[];
+/**
+ * Generates an OpenAPI document covering the requested FHIR resources: their
+ * full schema dependency closure plus the standard FHIR RESTful interactions.
+ */
+declare function generateOpenApi(options: GenerateOptions): OpenApiDocument;
+
+/** FHIR RESTful interaction codes (CapabilityStatement.rest.resource.interaction). */
+type FhirInteraction = "read" | "vread" | "update" | "patch" | "delete" | "history-instance" | "history-type" | "create" | "search-type";
+
+/**
+ * Loads and parses a FHIR CapabilityStatement (a server's `/metadata`) into a
+ * per-resource description of what the server actually supports, so a spec can
+ * be generated to match exactly one server's surface rather than the full
+ * standard interaction set.
+ */
+interface ResourceCapability {
+    type: string;
+    interactions: Set<FhirInteraction>;
+    /** Search parameter codes the server declares for this resource. */
+    searchParamCodes: Set<string>;
+    /** Operation codes and canonical URLs the server declares for this resource. */
+    operations: Set<string>;
+}
+interface Capability {
+    /** FHIR version string from the statement, e.g. "4.0.1" (may be undefined). */
+    fhirVersion?: string;
+    resources: ResourceCapability[];
+}
+interface LoadCapabilityOptions {
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Loads a CapabilityStatement from a local JSON file or an http(s) URL. A URL
+ * that does not already end in `/metadata` has it appended, so a base server
+ * URL works directly.
+ */
+declare function loadCapabilityStatement(input: string, options?: LoadCapabilityOptions): Promise<Capability>;
+declare function parseCapabilityStatement(json: unknown): Capability;
+
+interface MinElementType {
+    code: string;
+    targetProfile?: string[];
+    fhirType?: string;
+}
+interface MinElement {
+    path: string;
+    min: number;
+    max: string;
+    short?: string;
+    definition?: string;
+    contentReference?: string;
+    types?: MinElementType[];
+    binding?: {
+        strength: string;
+        valueSet: string;
+        codes?: string[];
+    };
+    /**
+     * Value the element is fixed to by a profile (`fixed[x]`), normalized to a
+     * JSON value. Only populated for profiles loaded from an IG package; the
+     * vendored base definitions do not carry it.
+     */
+    fixed?: unknown;
+    /** Profile `mustSupport` flag (surfaced in descriptions, not enforced). */
+    mustSupport?: boolean;
+    /**
+     * Human labels for profile constraints this tool does not enforce in
+     * OpenAPI (e.g. "pattern", "slicing"), surfaced in the property description
+     * and `x-fhir-constraints-omitted`. IG profiles only.
+     */
+    omittedConstraints?: string[];
+}
+interface MinStructureDefinition {
+    name: string;
+    url: string;
+    kind: "resource" | "complex-type" | "primitive-type";
+    type: string;
+    abstract: boolean;
+    baseDefinition?: string;
+    elements: MinElement[];
+}
+
+type ValueSetResolver = (valueSetUrl: string) => string[] | undefined;
+
+interface IgProfile {
+    /** Versionless canonical URL. */
+    url: string;
+    id?: string;
+    name: string;
+    type: string;
+    definition: MinStructureDefinition;
+}
+interface IgContext {
+    name: string;
+    version: string;
+    fhirVersion: FhirVersion;
+    profiles: IgProfile[];
+    /** Names/URLs of constraint profiles that lack a snapshot (cannot be applied). */
+    profilesMissingSnapshot: string[];
+    resolveValueSet: ValueSetResolver;
+}
+interface LoadIgOptions {
+    /** Resolve core bindings (e.g. administrative-gender) not defined in the IG. */
+    coreValueSetFallback?: ValueSetResolver;
+    /** Base directory for the registry download cache. Defaults to ~/.fhir-oas. */
+    cacheDir?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resolves the `--ig` input to an IgContext. Accepts a path to a package
+ * tarball (`.tgz`), a path to an unpacked package directory, or a registry
+ * coordinate (`name` or `name@version`) fetched from packages.fhir.org and
+ * cached locally. Async because registry coordinates hit the network.
+ */
+declare function loadIg(input: string, options?: LoadIgOptions): Promise<IgContext>;
+/**
+ * Synchronous IG loader for local inputs (a `.tgz` or an unpacked directory).
+ * Registry coordinates require the async {@link loadIg} because they fetch
+ * over the network.
+ */
+declare function loadIgSync(input: string, options?: LoadIgOptions): IgContext;
+
+interface MergeOptions {
+    /** Overwrite conflicting entries instead of failing. */
+    force?: boolean;
+}
+interface MergeConflict {
+    /** e.g. "components.schemas.Patient" or "paths./Patient/{id}" */
+    location: string;
+}
+declare class MergeConflictError extends Error {
+    readonly conflicts: MergeConflict[];
+    constructor(conflicts: MergeConflict[]);
+}
+/**
+ * Merges a generated OpenAPI document into existing YAML text, preserving the
+ * existing file's comments, anchors, and key order. Generated entries are
+ * added alongside existing content; an existing entry with different content
+ * is a conflict (all conflicts are reported; nothing is written unless every
+ * conflict is resolved by `force`). Identical entries are left untouched, so
+ * re-running the generator is idempotent.
+ */
+declare function mergeIntoYaml(generated: OpenApiDocument, existingText: string, options?: MergeOptions): string;
+interface SpecDiff {
+    /** Entries the file lacks (dot paths), e.g. "components.schemas.Patient". */
+    missing: string[];
+    /** Entries present in the file but differing from generation. */
+    changed: string[];
+    /** True when the file already contains exactly what generation produces. */
+    inSync: boolean;
+}
+/**
+ * Compares existing spec text against a generated document without writing
+ * anything — the CI drift guard behind `fhir-oas check`. The file is in sync
+ * when a merge would be a no-op: nothing to add, nothing conflicting.
+ */
+declare function diffAgainstYaml(generated: OpenApiDocument, existingText: string): SpecDiff;
+/** Serializes a generated document to YAML text. */
+declare function stringifyDocument(generated: OpenApiDocument): string;
+
+export { type Capability, type CapabilityLike, FHIR_VERSIONS, FHIR_VERSION_NUMBERS, type FhirVersion, type GenerateOptions, type IgContext, type IgContextLike, type IgProfile, type MergeConflict, MergeConflictError, type MergeOptions, type OpenApiDocument, type OpenApiVersion, type ResourceCapability, type SourceBackend, type SpecDiff, type TrimOptions, diffAgainstYaml, generateOpenApi, listResources, loadCapabilityStatement, loadIg, loadIgSync, mergeIntoYaml, parseCapabilityStatement, stringifyDocument };

package/dist/index.js

@@ -0,0 +1,29 @@
+import {
+  FHIR_VERSIONS,
+  FHIR_VERSION_NUMBERS,
+  MergeConflictError,
+  diffAgainstYaml,
+  generateOpenApi,
+  listResources,
+  loadCapabilityStatement,
+  loadIg,
+  loadIgSync,
+  mergeIntoYaml,
+  parseCapabilityStatement,
+  stringifyDocument
+} from "./chunk-G3DCRADV.js";
+export {
+  FHIR_VERSIONS,
+  FHIR_VERSION_NUMBERS,
+  MergeConflictError,
+  diffAgainstYaml,
+  generateOpenApi,
+  listResources,
+  loadCapabilityStatement,
+  loadIg,
+  loadIgSync,
+  mergeIntoYaml,
+  parseCapabilityStatement,
+  stringifyDocument
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/REFERENCE.md

@@ -0,0 +1,200 @@
+# fhir-openapi-translator — Reference
+
+Full CLI, library API, codegen recipes, and limitations. For a quick start see the [README](../README.md).
+
+## Contents
+
+- [CLI](#cli)
+- [Library API](#library-api)
+- [Codegen recipes](#codegen-recipes)
+- [Viewing generated specs](#viewing-generated-specs)
+- [What this is for — and what it is not](#what-this-is-for--and-what-it-is-not)
+- [Profiles: what `--profile` applies](#profiles-what---profile-applies)
+- [Assumptions and known limitations](#assumptions-and-known-limitations)
+- [Development](#development)
+
+## CLI
+
+```sh
+# Generate a spec for Patient and Observation on FHIR R4, as YAML to stdout
+fhir-oas generate Patient Observation --fhir-version r4
+
+# Write JSON, target OpenAPI 3.1
+fhir-oas generate Patient -f r5 --format json --openapi-version 3.1 -o patient.json
+
+# Merge into an existing spec, keeping its comments and key order
+fhir-oas generate Questionnaire -f r4 --merge-into api.yaml
+
+# Embed a server URL and trim the output
+fhir-oas generate Patient -f r4 --base-url https://fhir.example.org/r4 \
+  --exclude-narrative --max-depth 3
+
+# List the resource types available for a version
+fhir-oas list --fhir-version r4b
+
+# CI drift guard: fail when api.yaml no longer matches generation
+fhir-oas check Patient Observation -f r4 --file api.yaml
+
+# Lenient models: replace binding enums with plain strings
+fhir-oas generate Patient -f r4 --no-enums
+
+# Include the standard operations (GET /Patient/{id}/$everything, POST /Patient/$validate, ...)
+fhir-oas generate Patient -f r4 --operations
+
+# Apply a profile from an Implementation Guide package
+fhir-oas generate Patient -f r4 --ig ./hl7.fhir.us.core-5.0.1.tgz --profile us-core-patient
+fhir-oas generate Patient -f r4 --ig hl7.fhir.us.core@5.0.1 --profile us-core-patient  # fetched + cached
+
+# List the profiles in an IG package
+fhir-oas list --ig ./hl7.fhir.us.core-5.0.1.tgz
+
+# Match a specific server's declared surface (resources, interactions, search params, operations)
+fhir-oas generate -f r4 --capability https://server.example.org/fhir   # appends /metadata
+fhir-oas generate -f r4 --capability ./metadata.json                    # or a saved statement
+```
+
+`fhir-oas generate --help` shows all options, including `--source` (definition backend: `schema-json` default, or `structure-def`), `--title`, and `--force` (overwrite conflicting entries when merging).
+
+## Library API
+
+```ts
+import { generateOpenApi, listResources, mergeIntoYaml } from "fhir-openapi-translator";
+
+const doc = generateOpenApi({
+  resources: ["Patient", "Observation"],
+  fhirVersion: "r4",
+  openApiVersion: "3.0.3",       // default
+  baseUrl: "https://fhir.example.org/r4",
+  trim: { excludeNarrative: true, maxDepth: 3 },
+});
+
+listResources("r5");             // ["Account", "ActivityDefinition", ...]
+
+// Merge into existing YAML text, preserving comments and formatting
+const mergedYaml = mergeIntoYaml(doc, existingYamlText, { force: false });
+```
+
+Profiles from an IG package (`loadIg` is async for registry coordinates; a local path can be passed to `ig` directly):
+
+```ts
+import { generateOpenApi, loadIg } from "fhir-openapi-translator";
+
+const ig = await loadIg("hl7.fhir.us.core@5.0.1");   // or "./us-core.tgz", or a directory
+const doc = generateOpenApi({
+  resources: ["Patient"],
+  fhirVersion: "r4",
+  ig,                                // or ig: "./us-core.tgz" (loaded synchronously)
+  profiles: ["us-core-patient"],
+});
+```
+
+Match a server's CapabilityStatement (`loadCapabilityStatement` is async; `parseCapabilityStatement` takes an already-loaded object):
+
+```ts
+import { generateOpenApi, loadCapabilityStatement } from "fhir-openapi-translator";
+
+const capability = await loadCapabilityStatement("https://server.example.org/fhir");
+const doc = generateOpenApi({ fhirVersion: "r4", capability });  // resources come from the statement
+```
+
+See `GenerateOptions` in the type declarations for the full API surface.
+
+## Codegen recipes
+
+Generated specs are exercised against [openapi-generator](https://github.com/OpenAPITools/openapi-generator) in CI (`typescript-fetch` and `python` targets). Notes that matter in practice:
+
+- **typescript-fetch**: pass `--additional-properties=modelPropertyNaming=original`. FHIR represents extensions on primitive fields as sibling `_field` properties; the generator's default naming strips the underscore and produces colliding class members.
+- Large resources produce large model trees (a Patient R4 spec has ~80 schemas, a full Bundle-of-anything far more). If your generator or build struggles, use `--exclude-narrative` and `--max-depth` to shrink the graph.
+- `Bundle.entry.resource` (`ResourceList`) is narrowed to the resource types you requested. If your server returns other types in bundles (e.g. `_include`d resources you didn't generate), either add those resources to the generation, or treat unknown entries as opaque JSON.
+
+## Viewing generated specs
+
+Swagger UI is fine for a spec covering a handful of resources, but it renders
+every schema in the document eagerly. FHIR's schemas are large and mutually
+recursive, so it degrades sharply as the spec grows. Measured on specs from
+this tool:
+
+| Spec | Swagger UI behaviour |
+|---|---|
+| 2 resources (~73 schemas) | renders fine; models expand promptly |
+| 6 resources (~84 schemas) | renders, but expanding one operation blocks the page for ~90s |
+| 39 resources (~188 schemas) | the **Schemas** section never finished rendering (gave up after 5 minutes) |
+
+[Redoc](https://github.com/Redocly/redoc) renders lazily and copes with these
+specs far better. Prefer it for anything beyond a few resources:
+
+```sh
+npx @redocly/cli preview-docs fhir-r4.openapi.yaml
+```
+
+This is a *viewer* limitation, not a defect in the generated specs — they
+validate against the OpenAPI meta-schemas and feed code generators cleanly at
+any size. If you do need Swagger UI on a large spec, `--exclude-narrative` and
+`--max-depth` shrink the schema graph considerably.
+
+## What this is for — and what it is not
+
+**Intended use**
+
+- Generate typed FHIR models and API clients in any language — especially where no mature FHIR SDK exists (Go, Rust, Kotlin, PHP, C++, ...).
+- Publish an OpenAPI contract to the consumers of your FHIR API, so they integrate against a spec rather than prose.
+- Build typed clients for orchestrator-style FHIR endpoints your services call.
+- Feed API gateways, contract-testing tools, mock servers, and documentation portals that speak OpenAPI.
+- Commit the generated spec next to your service and regenerate on FHIR version bumps; merge mode keeps hand-written spec content intact.
+
+**Not intended for — do not use this as**
+
+- **A FHIR validator.** Passing schema validation does *not* make a resource FHIR-conformant: FHIRPath invariants, terminology bindings, and profile constraints (slicing, must-support, cardinality refinements) are not fully represented in OpenAPI. Validate with a real FHIR validator (HAPI, the official validator, server-side `$validate`).
+- **A full profile / conformance engine.** `--profile` applies the *representable* profile constraints (see the table below), but slicing, extension slices, `pattern[x]`, FHIRPath invariants, and must-support are **not enforced** — they are surfaced as description notes and `x-fhir-constraints-omitted`, not as schema rules.
+- **A replacement for a full FHIR SDK.** HAPI FHIR and Firely offer richer, spec-aware models and conformance tooling than any OpenAPI codegen can; where you need that depth, use them alongside this rather than instead of it.
+- **XML payload handling.** Only the FHIR JSON representation is modeled.
+
+## Profiles: what `--profile` applies
+
+Given `--ig <package> --profile <id>`, the profile snapshot is turned into a schema named after the profile (`USCorePatient`), referenced from the base `/Patient` paths:
+
+| Profile constraint | Schema effect |
+|---|---|
+| `min ≥ 1` | property becomes `required` |
+| `max: "0"` | property omitted |
+| `max: "1"` on a base array | scalar instead of array |
+| required binding, resolvable ValueSet (IG-local, then vendored core; ≤150 codes) | inline `enum` |
+| `fixed[x]` | `const` (3.1) / single-value `enum` (3.0.3) |
+| choice-type narrowing | only the permitted `value[x]` expansions emitted |
+| `pattern[x]`, slicing, invariants, must-support | *not enforced* — noted in `description` + `x-fhir-constraints-omitted` |
+
+The IG package is a local `.tgz` / unpacked directory, or a `name@version` coordinate fetched from `packages.fhir.org` and cached under `~/.fhir-oas/packages`. Profiles must ship a snapshot (differential-only packages error); the package FHIR version must match `--fhir-version`; only the public registry is supported (no auth).
+
+## Assumptions and known limitations
+
+- Output is inherently lossy relative to the FHIR specification (see above); it trades fidelity for reach across language ecosystems.
+- Enums cover *required* bindings whose ValueSet expands to a bounded code list (≤150 codes, no filters); extensible/preferred bindings and open code systems (BCP-47 languages, MIME types) stay plain strings by design.
+- Primitive-extension properties (`_field`) are kept for JSON fidelity; they roughly double the property count of each model.
+- Search parameters are typed as strings (except `_count`), because FHIR search values carry prefixes and modifiers (`ge2021-01-01`, `code:below=...`) that stricter types would reject. The FHIR type is preserved in `x-fhir-search-type`.
+- Operations are resource-scoped only: system-level operations (`GET /$export`-style, `$convert`, ...), `POST /_search`, batch/transaction semantics, and conditional headers beyond `If-Match` are not modeled. Multi-part operation parameters collapse to a generic `Parameters` body.
+- `--capability` reflects a server's *declared* surface: resource types the FHIR version doesn't define are skipped, and declared operations are emitted only when they map to a known OperationDefinition (system-level interactions like transaction/batch are not modeled). It restricts what's generated; it does not verify the server actually behaves as declared.
+- The two definition backends can differ cosmetically (e.g. naming of deeply nested backbone elements, primitive regex patterns); `schema-json` is the default and the reference.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm test          # vitest; validates generated specs against the OpenAPI meta-schemas
+npm run build     # tsup → dist/
+```
+
+Vendored FHIR definitions live in `definitions/` as gzipped JSON. To refresh them from their upstream npm packages, run:
+
+```sh
+node scripts/update-definitions.mjs
+```
+
+The README demo (`docs/demo.gif`) is regenerated by `scripts/make-demo.mjs`. It
+drives a real generation plus Swagger UI in headless Chromium, so it needs
+dev-only tooling that is deliberately kept out of `package.json`:
+
+```sh
+npm install --no-save playwright swagger-ui-dist gifenc pngjs
+npm run build && node scripts/make-demo.mjs
+```

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "fhir-openapi-translator",
+  "version": "0.1.0",
+  "description": "Generate an OpenAPI (Swagger) spec for any FHIR resource (R4/R4B/R5) — for typed model & client codegen in any language. Supports US Core profiles, operations, and CapabilityStatements.",
+  "keywords": [
+    "fhir",
+    "fhir-to-openapi",
+    "openapi",
+    "swagger",
+    "hl7",
+    "hl7-fhir",
+    "codegen",
+    "code-generation",
+    "fhir-codegen",
+    "us-core",
+    "structuredefinition",
+    "capabilitystatement",
+    "healthcare",
+    "healthcare-interoperability",
+    "openapi-generator",
+    "fhir-r4",
+    "fhir-r5"
+  ],
+  "license": "MIT",
+  "author": "krishgok",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krishgok/fhir-openapi-translator.git"
+  },
+  "homepage": "https://github.com/krishgok/fhir-openapi-translator#readme",
+  "bugs": {
+    "url": "https://github.com/krishgok/fhir-openapi-translator/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "fhir-oas": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "definitions",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src test",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run build && npm run test"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@seriousme/openapi-schema-validator": "^2.9.0",
+    "@types/node": "^22.9.0",
+    "eslint": "^9.14.0",
+    "openapi-types": "^12.1.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.13.0",
+    "vitest": "^2.1.4"
+  }
+}