@miragon/bpmnlint-plugin-rules
v0.22.0
Published
A bpmnlint plugin bundling the standard structural rules, Camunda 7/8 deployability rules and Miragon BPMN conventions behind one resolver.
Maintainers
Readme
@miragon/bpmnlint-plugin-rules
A bpmnlint plugin that keeps BPMN diagrams clean: a few Miragon naming and layout conventions, plus the standard structural rules and the Camunda 7 / 8 deployability rules bundled in — so you don't wire up bpmnlint's plugins yourself.
[!WARNING] This plugin has not reached 1.0.0 yet. Until then, any minor release may contain breaking changes — new or stricter rules, renamed options, changed severities. Pin an exact version and check the changelog before you upgrade.

Why
A BPMN diagram can be well-formed and still be wrong — a missing start event, a construct the engine
rejects at deploy, or forty tasks named Activity_0049ryx that no reviewer can read. Linting catches
that automatically, wherever BPMN is written:
- In the modeler — live feedback while you draw, so a mistake is flagged the moment you make it.
- In CI — a merge/deploy gate, so a broken model never ships.
- For AI — agents emit valid-but-off models (machine IDs, orphan nodes, engine-invalid constructs); lint their output and block on error, instead of hoping a human catches it.
Most teams already have these conventions — in a wiki, or in one reviewer's head. This plugin makes them executable.
Install
Install the plugin together with bpmnlint (its peer dependency):
npm install --save-dev @miragon/bpmnlint-plugin-rules bpmnlintUse it (the bpmnlint way)
Add the plugin to your .bpmnlintrc and extend one of its configs, like any other plugin.
bpmnlint:recommended brings the standard structural rules, and the second entry adds the Miragon
layer, here recommended-for-modeling:
{
"extends": [
"bpmnlint:recommended",
"plugin:@miragon/rules/recommended-for-modeling"
]
}It ships three configs — pick one by who's modeling and why:
plugin:@miragon/rules/recommended-for-modeling— for purely business/technical models, and for modeler applications that surface linting to their users. Layout hints only: bpmnlint'sstandard-sizeand the layout rules atwarn, the naming/id rules off — a modeler is never blocked on execution-only conventions.plugin:@miragon/rules/recommended-for-automation— for developers automating processes, locally and in CI, on models wired up to a Camunda engine. Every Miragon rule on but as a non-blockingwarn(standard-sizetoo), so ids and layout get flagged without failing the build.plugin:@miragon/rules/strict— every Miragon rule aterror, engine-agnostic. The gate to opt into when you want findings to fail the build. Not covered by semver: a minor release may add rules or widen what they report. See the semantic versioning policy.
Then lint a diagram:
npx bpmnlint diagram.bpmnRules
The Miragon conventions this plugin adds — each with a docs page and a good/bad example:
| Rule | What it catches |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| @miragon/rules/no-generated-ids | IDs generated rather than chosen (Activity_0049ryx, StartEvent_1) |
| @miragon/rules/element-id-naming | IDs that don't follow the type-prefix + case convention |
| @miragon/rules/worker-topic-naming | A worker topic (C7 external task topic, C8 job type) off the configured scheme |
| @miragon/rules/message-name-naming | A message name off the configured scheme |
| @miragon/rules/flow-through-element | A sequence flow routed through an unrelated shape's body |
| @miragon/rules/flow-connection-side | A sequence flow docked onto the wrong side of a shape |
| @miragon/rules/flow-target-alignment | A flow's target drawn off the row, sloping the main path |
| @miragon/rules/flow-crossing | Two sequence flows whose drawn paths cross each other |
| @miragon/rules/flow-orthogonal | A sequence flow that runs diagonally instead of horizontal and vertical |
| @miragon/rules/boundary-event-marker-overlap | A boundary event drawn over a marker or icon of its host activity |
| @miragon/rules/exclusive-gateway-marker-visible | An exclusive gateway drawn without its X marker |
| @miragon/rules/async-continuations | Camunda 7 save points missing where Camunda recommends them, or redundant |
Turn any of them on individually, the usual way:
{
"extends": [
"bpmnlint:recommended",
"plugin:@miragon/rules/recommended-for-modeling"
],
"rules": {
"@miragon/rules/no-generated-ids": "error",
"@miragon/rules/element-id-naming": "warn"
}
}Structural checks — start/end events, connectivity, element sizing — come from bpmnlint's own
bpmnlint:recommended. The
Miragon set grows over time; see CONTRIBUTING.md to propose a rule.
In CI
Lint every model as a merge gate — bpmnlint exits non-zero on a finding, failing the build:
npx bpmnlint 'models/**/*.bpmn'Camunda engine rules
Deploying to a Camunda engine? Add its deployability layer (bundled — no separate install) to your
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.
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.
Camunda 7
{
"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)
{
"extends": [
"bpmnlint:recommended",
"plugin:@miragon/rules/recommended-for-automation",
"plugin:camunda-compat/camunda-cloud-8-11"
],
"moddleExtensions": {
"zeebe": "zeebe-bpmn-moddle/resources/zeebe.json"
}
}Older engine versions
Both examples name the config for the latest engine version. camunda-compat ships one config per
version, from camunda-platform-7-19 and camunda-cloud-1-0 on: put your engine's version in the
name, for example plugin:camunda-compat/camunda-cloud-8-5. The bpmnlint CLI loads it from the
installed bpmnlint-plugin-camunda-compat.
The bundled resolver, createBundledResolver(), carries only the latest config per engine:
camunda-platform-7-24 and camunda-cloud-8-11. A host that has only the bundle, such as a browser
modeler, lints against these two. In Node, chain bpmnlint's NodeResolver behind the bundle, so the
configs and rules the bundle does not carry load from the installed packages:
import NodeResolver from 'bpmnlint/lib/resolver/node-resolver.js';
import { createBundledResolver } from '@miragon/bpmnlint-plugin-rules';
const bundled = createBundledResolver();
// loads packages from the node_modules of the working directory
const installed = new NodeResolver();
// the bundle first, the installed packages for what it does not carry
function chained(method: 'resolveRule' | 'resolveConfig') {
return (pkg: string, name: string) => {
try {
return bundled[method](pkg, name);
} catch {
return installed[method](pkg, name);
}
};
}
const resolver = {
resolveRule: chained('resolveRule'),
resolveConfig: chained('resolveConfig'),
};Pass this resolver to the Linter in place of createBundledResolver(), with an extends that
names the older config.
Programmatic use
Building a linter in code — a modeler, a CI script, an agent loop? Skip .bpmnlintrc and use the
bundled resolver. It carries every layer (structural + Camunda + Miragon), so there's nothing else
to wire up, and it works offline:
import { BpmnModdle } from 'bpmn-moddle';
import { Linter } from 'bpmnlint';
import {
createBundledResolver,
getDefaultLintConfig,
} from '@miragon/bpmnlint-plugin-rules';
// 'c7' | 'c8', omit for structural-only
const config = getDefaultLintConfig({ engine: 'c8' });
// parse with the config's moddle extensions, or the engine rules
// cannot see the engine properties
const moddle = new BpmnModdle(config.moddleExtensions);
const { rootElement } = await moddle.fromXML(xml);
const linter = new Linter({
config,
resolver: createBundledResolver(),
});
const results = await linter.lint(rootElement);engine picks the Camunda deployability layer + typed moddle; preset picks the Miragon opinion
layer independently — 'modeling' (layout hints only, safe on hand-drawn diagrams) or
'automation' (every Miragon rule at error). When preset is omitted it defaults to
'automation' for an engine-bound config and 'modeling' otherwise. Pass both to decouple them —
e.g. a modeler that wants Camunda 8's typed properties and deployability checks but the relaxed
modeling opinion layer:
getDefaultLintConfig({ engine: 'c8', preset: 'modeling' });Results are keyed by rule; each finding has a category (error | warn). Block on any error — a
CI gate, or the reject signal that sends an AI agent back to fix its output:
const errors = Object.values(results)
.flat()
.filter((finding) => finding.category === 'error');
if (errors.length) process.exit(1);Every rule factory, rule-set and helper is exported from the package root as well.
Alternatives
bpmnlint lints one model at a time, so it is the right fit for anything stylistic or about the correctness of a single diagram. It checks naming conventions, layout, structural soundness, and whether a construct is deployable to a given engine.
However, it cannot answer engine- and automation-specific questions that span a running process, because those depend on more than the diagram in front of it. Whether a call activity passes every variable its child process needs, or whether the technical wiring is correct, is something a model-in-isolation linter simply cannot see. For those cases, and when you want to keep such tests alongside your model in the same build (for example a Gradle task), Miragon/bpmn-to-code and its process testing are the better tool.
Where it is used
Miragon BPMN Modeler — in-editor linting via the programmatic API, flagging issues live while you model.
Claude Code plugin — skills that write a team BPMN style guide, generate the matching
.bpmnlintrc, check models against the guide, and review and fix their layout.
Contributing
See CONTRIBUTING.md.
License
MIT © Miragon GmbH.
