From 9bd2ed9b1667a4fb10896f44a343855e58ffce97 Mon Sep 17 00:00:00 2001 From: Andreas Riepl Date: Mon, 24 Aug 2026 16:07:45 +0200 Subject: [PATCH 1/2] docs: explain required moddleExtensions for engine rules --- README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c4892ac..1d3937d 100644 --- a/README.md +++ b/README.md @@ -111,8 +111,14 @@ Deploying to a Camunda engine? Add its deployability layer (bundled — no separ | Camunda 7 | `plugin:camunda-compat/camunda-platform-7-24` | | Camunda 8 (Zeebe) | `plugin:camunda-compat/camunda-cloud-8-10` | -These rules read engine properties, so point bpmnlint at the matching moddle extension in your -`.bpmnlintrc`: +These rules read engine-specific properties (`zeebe:*` for Camunda 8, `camunda:*` for Camunda 7), so +bpmnlint has to parse them with the matching moddle extension. Wire it into your `.bpmnlintrc` +alongside the engine layer: + +| Engine | Add to `moddleExtensions` | +| ----------------- | --------------------------------------------------------- | +| Camunda 8 (Zeebe) | `"zeebe": "zeebe-bpmn-moddle/resources/zeebe.json"` | +| Camunda 7 | `"camunda": "camunda-bpmn-moddle/resources/camunda.json"` | ```jsonc { @@ -121,9 +127,12 @@ These rules read engine properties, so point bpmnlint at the matching moddle ext } ``` -For Camunda 7, use `"camunda": "camunda-bpmn-moddle/resources/camunda.json"`. Prefer to skip the -wiring? The programmatic `getDefaultLintConfig({ engine })` below sets up both the layer and its -moddle extension for you. +**This line is not optional.** Without it the parser doesn't recognize the engine namespace, so those +properties are invisible to the rules — they then report false findings (for example a service task +flagged as missing its `zeebe:taskDefinition` even though it has one). A modeler loads the moddle +already; it's the bare `npx bpmnlint` CLI that needs this line. Prefer to skip the wiring? The +programmatic `getDefaultLintConfig({ engine })` below sets up both the layer and its moddle extension +for you. ## Programmatic use From d8003ca4867c0631995ce8190eb3d668e1725b49 Mon Sep 17 00:00:00 2001 From: Andreas Riepl Date: Mon, 24 Aug 2026 16:10:14 +0200 Subject: [PATCH 2/2] docs: split engine rules into complete C7 and C8 config examples --- README.md | 48 ++++++++++++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 1d3937d..1b8121f 100644 --- a/README.md +++ b/README.md @@ -104,36 +104,44 @@ npx bpmnlint 'models/**/*.bpmn' ## Camunda engine rules Deploying to a Camunda engine? Add its deployability layer (bundled — no separate install) to your -`extends`: +`extends`. These rules read engine-specific properties, so bpmnlint must also parse them with the +matching moddle extension — pick the config for your engine below. -| Engine | Add to `extends` | -| ----------------- | --------------------------------------------- | -| Camunda 7 | `plugin:camunda-compat/camunda-platform-7-24` | -| Camunda 8 (Zeebe) | `plugin:camunda-compat/camunda-cloud-8-10` | +**The `moddleExtensions` line is not optional.** Without it the parser doesn't recognize the engine +namespace, so those properties are invisible to the rules — they then report false findings (for +example a service task flagged as missing its task definition even though it has one). A modeler loads +the moddle already; it's the bare `npx bpmnlint` CLI that needs this line. Prefer to skip the wiring? +The programmatic `getDefaultLintConfig({ engine })` below sets up both the layer and its moddle +extension for you. -These rules read engine-specific properties (`zeebe:*` for Camunda 8, `camunda:*` for Camunda 7), so -bpmnlint has to parse them with the matching moddle extension. Wire it into your `.bpmnlintrc` -alongside the engine layer: +### Camunda 7 -| Engine | Add to `moddleExtensions` | -| ----------------- | --------------------------------------------------------- | -| Camunda 8 (Zeebe) | `"zeebe": "zeebe-bpmn-moddle/resources/zeebe.json"` | -| Camunda 7 | `"camunda": "camunda-bpmn-moddle/resources/camunda.json"` | +```jsonc +// .bpmnlintrc +{ + "extends": [ + "bpmnlint:recommended", + "plugin:@miragon/rules/recommended-for-automation", + "plugin:camunda-compat/camunda-platform-7-24", + ], + "moddleExtensions": { "camunda": "camunda-bpmn-moddle/resources/camunda.json" }, +} +``` + +### Camunda 8 (Zeebe) ```jsonc +// .bpmnlintrc { - "extends": ["bpmnlint:recommended", "plugin:camunda-compat/camunda-cloud-8-10"], + "extends": [ + "bpmnlint:recommended", + "plugin:@miragon/rules/recommended-for-automation", + "plugin:camunda-compat/camunda-cloud-8-10", + ], "moddleExtensions": { "zeebe": "zeebe-bpmn-moddle/resources/zeebe.json" }, } ``` -**This line is not optional.** Without it the parser doesn't recognize the engine namespace, so those -properties are invisible to the rules — they then report false findings (for example a service task -flagged as missing its `zeebe:taskDefinition` even though it has one). A modeler loads the moddle -already; it's the bare `npx bpmnlint` CLI that needs this line. Prefer to skip the wiring? The -programmatic `getDefaultLintConfig({ engine })` below sets up both the layer and its moddle extension -for you. - ## Programmatic use Building a linter in code — a modeler, a CI script, an agent loop? Skip `.bpmnlintrc` and use the