Skip to content
3

@miragon/rules/message-name-naming โ€‹

Reports a message whose name does not follow the project's naming scheme.

Examples โ€‹

Both models start with the same message start event. Only the name of its message differs.

message-name-naming/invalid.bpmn

Invalid model: a message name off the naming scheme

Valid model: a message name on the naming scheme

1 finding
  • message_orderReceived Message name <Order received> must match <camelCase>

Invalid: the message name Order received is off the default camelCase scheme

Valid: the same message named orderReceived

The same, as XML. ๐Ÿ‘Ž wrong:

xml
<bpmn:message id="message_orderReceived" name="Order received" />

๐Ÿ‘ right:

xml
<bpmn:message id="message_orderReceived" name="orderReceived" />

Why โ€‹

A message name is a contract between the model and everything that talks to it. The engine correlates an incoming message by exactly this string, so the developer of the sending service has to spell it the same way, and an operator reading a failed correlation in Cockpit or Operate has to recognise which message was meant. A scheme such as billing.paymentReceived says which domain owns the message. Without one the scheme lives in a wiki page nobody checks, and a sender that writes PaymentReceived against a model that says payment-received fails only at runtime.

Why this matters for agentic BPMN โ€‹

An agent that adds a message event has to invent the message name. With no stated scheme it reuses the event label or copies whatever shape it saw last, and the model deploys cleanly while the correlation never matches.

Typical AI artifact without this rule: a message named Payment received, copied from the label of its start event.

What this rule guarantees: every message name follows one configured prefix, separator and case, so a tool can generate a name that passes from the same .bpmnlintrc.

Scope โ€‹

The rule looks at the name of every bpmn:Message and reports on the message itself.

It leaves these alone:

  • A message without a name. Nothing can correlate it, which is the engine's finding, not a naming one.
  • An expression (=โ€ฆ in FEEL, ${โ€ฆ} or #{โ€ฆ} in JUEL). The engine resolves it at runtime, so there is no fixed value to check.
  • The label of the event or task that references the message.
  • Signal, error and escalation names.

A bpmn:Message is a root element without a shape of its own, so a modeler has no place on the canvas to mark the finding. The CLI and CI output list it by the message's ID.

Configuration โ€‹

Every option is optional. Without any, the rule checks the default scheme: camelCase segments joined by a dot.

OptionDefaultEffect
prefixnoneFixed text every name starts with, followed by the separator.
separator.Joins the prefix and every segment.
casecamelCaseShape of every segment: camelCase, PascalCase, snake_case, kebab-case or any.
segmentsone or moreExact number of segments after the prefix. Any value but a positive integer is ignored.

An unknown case falls back to PascalCase, the same way element-id-naming does. A dot inside the prefix does not count as a segment: { "prefix": "com.acme.billing", "segments": 1 } accepts com.acme.billing.paymentReceived.

ConfigurationPassesReported
nonepaymentReceived, billing.paymentReceivedPayment received
{ "prefix": "billing" }billing.paymentReceivedpaymentReceived, billing.PaymentReceived
{ "segments": 2 }billing.paymentReceived, shipping.paymentReceivedpaymentReceived, billing.invoice.paymentReceived
{ "prefix": "billing", "separator": "/", "case": "kebab-case" }billing/payment-receivedbilling/paymentReceived

Several services โ€‹

One .bpmnlintrc often covers several services, each with its own lead (billing.โ€ฆ, shipping.โ€ฆ). Two ways to check that:

  • { "segments": 2 } in the shared .bpmnlintrc fixes the shape <service>.<name> for every service. It does not know the service names, so a typo such as biling.paymentReceived passes.
  • One .bpmnlintrc per service, each with its own prefix, checks the service name exactly. Run bpmnlint once per service, for example npx bpmnlint --config services/billing/.bpmnlintrc "services/billing/**/*.bpmn".

A tool that creates BPMN reads the same options through the exported naming helpers. It builds the name from the prefix and a name it was given, never a guessed service, and checks the result:

ts
import { naming } from '@miragon/bpmnlint-plugin-rules';

const scheme = new naming.ValueNamingScheme({ segments: 2 });

scheme.matches('billing.paymentReceived'); // true
scheme.describe(); // '<camelCase>.<camelCase>'

Further reading โ€‹