{"id":15563,"library":"camunda-schema-bundler","title":"Camunda OpenAPI Schema Bundler","description":"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.","status":"active","version":"1.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/camunda/camunda-schema-bundler","tags":["javascript","camunda","openapi","bundler","schema","typescript"],"install":[{"cmd":"npm install camunda-schema-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add camunda-schema-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add camunda-schema-bundler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment for the npm package.","package":"node","optional":false}],"imports":[{"note":"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.","wrong":"const bundle = require('camunda-schema-bundler');","symbol":"bundle","correct":"import { bundle } from 'camunda-schema-bundler';"},{"note":"Use `type` import for `BundleOptions` to get type safety for the `bundle` function's configuration object. This package ships with TypeScript types.","symbol":"BundleOptions","correct":"import type { BundleOptions } from 'camunda-schema-bundler';"},{"note":"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.","symbol":"cli","correct":"import { cli } from 'camunda-schema-bundler';"}],"quickstart":{"code":"import { bundle } from 'camunda-schema-bundler';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\n\nasync function runBundler() {\n  const outputDir = path.join(process.cwd(), 'bundled-spec');\n  await fs.mkdir(outputDir, { recursive: true });\n\n  console.log('Starting Camunda schema bundling...');\n  try {\n    await bundle({\n      fetch: true, // Fetch the latest spec from GitHub (default: main branch)\n      outputSpec: path.join(outputDir, 'rest-api.bundle.json'),\n      outputMetadata: path.join(outputDir, 'spec-metadata.json'),\n      outputEndpointMap: path.join(outputDir, 'endpoint-map.json'),\n      ref: process.env.CAMUNDA_SCHEMA_REF ?? 'main', // Use 'main' or specify a tag/branch like 'stable/8.8'\n      repoUrl: process.env.CAMUNDA_SCHEMA_REPO ?? 'https://github.com/camunda/camunda-platform-7-rest-api',\n    });\n    console.log(`Bundling completed successfully. Output files generated in ${outputDir}`);\n  } catch (error) {\n    console.error('Error during bundling:', error);\n    process.exit(1);\n  }\n}\n\nrunBundler();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your Node.js environment is updated to version 18 or newer. Use `nvm use 18` or update your system Node.js installation.","message":"The package requires Node.js version 18 or higher. Running with older Node.js versions will result in runtime errors or failures.","severity":"breaking","affected_versions":"<1.0.0 (engines field added/enforced)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.3.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 18 or higher. For example, using `nvm install 18 && nvm use 18`.","cause":"The package's `engines` constraint prevents it from running on Node.js versions older than 18.","error":"Error: Node.js v16.x.x is not supported. Please use Node.js v18 or higher."},{"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.","cause":"Attempting to use CommonJS `require()` syntax in an ES Module environment when `camunda-schema-bundler` is an ESM-first library.","error":"ReferenceError: require is not defined in ES module scope"},{"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.","cause":"The specified `--ref` (or `ref` in programmatic options) for fetching the upstream OpenAPI specification does not exist in the repository.","error":"Error: Not found: https://github.com/camunda/camunda-platform-7-rest-api/tree/invalid-branch"}],"ecosystem":"npm"}