Camunda OpenAPI Schema Bundler

1.7.0 · active · verified Tue Apr 21

The camunda-schema-bundler is a utility designed to process and normalize the multi-file Camunda OpenAPI specification into a single, clean JSON file suitable for code generation. It addresses several common issues encountered with naive OpenAPI bundling, such as resolving path-local `$ref`s, ensuring all component schemas are included, correcting URI-encoded references (e.g., `%24like` instead of `$like`), and preventing inline duplicates of schemas by converting them to proper `#/components/schemas/...` references. Beyond the bundled spec, it also extracts structured metadata and an endpoint map, tracing operations back to their source files. The current stable version is 1.7.0, with minor releases occurring frequently, typically monthly, to introduce features like support for `x-semantic-provider` and `x-deprecated-enum-members`, and to fix bugs. It serves as a crucial pre-processing step for official Camunda SDKs in various languages, including TypeScript, C#, and Python.

Common errors

```
Error: Node.js v16.x.x is not supported. Please use Node.js v18 or higher.
```
cause The package's `engines` constraint prevents it from running on Node.js versions older than 18.

fix Upgrade your Node.js environment to version 18 or higher. For example, using `nvm install 18 && nvm use 18`.
```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use CommonJS `require()` syntax in an ES Module environment when `camunda-schema-bundler` is an ESM-first library.

fix Change your import statements to use ES Module syntax: `import { bundle } from 'camunda-schema-bundler';` Ensure your `package.json` has `"type": "module"` or your file uses `.mjs` extension.
```
Error: Not found: https://github.com/camunda/camunda-platform-7-rest-api/tree/invalid-branch
```
cause The specified `--ref` (or `ref` in programmatic options) for fetching the upstream OpenAPI specification does not exist in the repository.

fix Verify the Git branch, tag, or SHA provided for `--ref` (or `ref`) is correct and exists in the target GitHub repository. Common issues include typos or using a deprecated branch name.

Warnings

breaking The package requires Node.js version 18 or higher. Running with older Node.js versions will result in runtime errors or failures.
Fix: Ensure your Node.js environment is updated to version 18 or newer. Use `nvm use 18` or update your system Node.js installation.
gotcha Older versions (prior to v1.3.3) had a bug (`fix deduplication leading to collapsed schemas`) that could result in incorrect or collapsed schemas in the bundled output, potentially leading to data loss or incorrect interpretations by downstream generators.
Fix: Upgrade to `camunda-schema-bundler` version 1.3.3 or newer to ensure correct schema deduplication and bundling logic. This is a critical fix for data integrity.
gotcha When bundling for generators that expect path-local dereferenced schemas (e.g., C# / Microsoft.OpenApi), you must enable the `--deref-path-local` CLI option or its programmatic equivalent in the `bundle` function to avoid unresolvable references.
Fix: If generating code for C# or other strict OpenAPI parsers, ensure you use the `--deref-path-local` CLI flag or set `derefPathLocal: true` in the `BundleOptions` when calling `bundle` programmatically.

Install

npm install camunda-schema-bundler npm
yarn add camunda-schema-bundler yarn
pnpm add camunda-schema-bundler pnpm

Imports

bundle
wrong:
```
const bundle = require('camunda-schema-bundler');
```
correct:
```
import { bundle } from 'camunda-schema-bundler';
```
The library primarily uses ESM. While CommonJS `require` might work with transpilers, direct ESM import is recommended. The `bundle` function is the main programmatic entry point for processing the schema.
BundleOptions
```
import type { BundleOptions } from 'camunda-schema-bundler';
```
Use `type` import for `BundleOptions` to get type safety for the `bundle` function's configuration object. This package ships with TypeScript types.
cli
```
import { cli } from 'camunda-schema-bundler';
```
While often used via the installed `camunda-schema-bundler` command, the CLI entry point can also be imported programmatically for integration into custom scripts or testing, though direct `bundle` function call is usually preferred for programmatic tasks.

Quickstart

This quickstart demonstrates programmatically invoking the `bundle` function to fetch the latest Camunda OpenAPI specification, process it, and output the bundled spec, metadata, and endpoint map files to a specified directory.

import { bundle } from 'camunda-schema-bundler';
import * as fs from 'node:fs/promises';
import * as path from 'node:path';

async function runBundler() {
  const outputDir = path.join(process.cwd(), 'bundled-spec');
  await fs.mkdir(outputDir, { recursive: true });

  console.log('Starting Camunda schema bundling...');
  try {
    await bundle({
      fetch: true, // Fetch the latest spec from GitHub (default: main branch)
      outputSpec: path.join(outputDir, 'rest-api.bundle.json'),
      outputMetadata: path.join(outputDir, 'spec-metadata.json'),
      outputEndpointMap: path.join(outputDir, 'endpoint-map.json'),
      ref: process.env.CAMUNDA_SCHEMA_REF ?? 'main', // Use 'main' or specify a tag/branch like 'stable/8.8'
      repoUrl: process.env.CAMUNDA_SCHEMA_REPO ?? 'https://github.com/camunda/camunda-platform-7-rest-api',
    });
    console.log(`Bundling completed successfully. Output files generated in ${outputDir}`);
  } catch (error) {
    console.error('Error during bundling:', error);
    process.exit(1);
  }
}

runBundler();

view raw JSON →