Skip to content
3

@miragon/rules/element-id-naming โ€‹

Reports an element whose ID does not follow the project's naming convention.

Examples โ€‹

element-id-naming/invalid.bpmn

Invalid model: IDs off the naming convention

Valid model: IDs on the naming convention

5 findings
  • OrderReceived Element id must match the naming convention <startEvent_camelCase>
  • ReviewOrder Element id must match the naming convention <serviceTask_camelCase>
  • OrderReviewed Element id must match the naming convention <endEvent_camelCase>
  • ReceivedToReview Element id must match the naming convention <flow_camelCase>
  • ReviewToReviewed Element id must match the naming convention <flow_camelCase>

Invalid: readable labels, but IDs with no type prefix (ReviewOrder, not serviceTask_reviewOrder)

Valid: the same model with <typePrefix>_<Name> IDs

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

xml
<bpmn:serviceTask id="Activity_0049ryx" name="Claim membership" />
<bpmn:serviceTask id="serviceTask_ClaimMembership" name="Claim membership" />
<bpmn:serviceTask id="task_claimMembership" name="Claim membership" />

๐Ÿ‘ right:

xml
<bpmn:serviceTask id="serviceTask_claimMembership" name="Claim membership" />

Why โ€‹

Wherever an element ID surfaces (a test assertion, an incident in monitoring, a generated constant, a diff) someone has to read it and know what it points at. A naming convention makes that instant: the prefix says what type the element is, the name says what it does, so a developer or a business stakeholder recognises the step without opening the model. Without one the same ID is just a string.

serviceTask_claimMembership     what it is, and what it does
Activity_0049ryx                neither

Why this matters for agentic BPMN โ€‹

An agent navigates a model by its IDs: to identify an element, describe a change, or apply a targeted edit, it needs IDs that are structured and categorisable. Without a prefix convention the IDs are arbitrary strings that carry no type information a machine can key off.

Typical AI artifact without this rule: a mix of Activity_1, task_claim and ServiceTask_Claim for elements of the same kind: no shared shape an agent can rely on to tell a gateway from a task from a flow.

What this rule guarantees: every ID follows one <typePrefix>_<Name> convention, so both a reviewer and an agent can read an element's type and purpose straight off its ID and address it unambiguously.

Default convention โ€‹

A camelCase element-type prefix plus a camelCase name.

Element typePrefix
bpmn:StartEventstartEvent_
bpmn:EndEventendEvent_
bpmn:BoundaryEvent, bpmn:IntermediateCatchEvent, bpmn:IntermediateThrowEventevent_
bpmn:ServiceTaskserviceTask_
bpmn:UserTaskuserTask_
bpmn:SendTask / ReceiveTask / ManualTask / ScriptTasksendTask_, โ€ฆ
bpmn:BusinessRuleTaskbusinessRuleTask_
bpmn:Tasktask_
bpmn:CallActivitycallActivity_
bpmn:SubProcesssubProcess_
bpmn:Gateway (every kind)gateway_
bpmn:SequenceFlowflow_
bpmn:MessageFlowmessageFlow_
bpmn:Collaborationcollaboration_
bpmn:Participantparticipant_
bpmn:Lanelane_
bpmn:DataObjectReferencedataObject_
bpmn:DataStoreReferencedataStore_
bpmn:TextAnnotationtextAnnotation_
bpmn:Groupgroup_
bpmn:Association, bpmn:DataInputAssociation, bpmn:DataOutputAssociationassociation_

Types are resolved by exact $type first, then by inheritance, so bpmn:Transaction and bpmn:AdHocSubProcess pick up the sub-process convention, and every gateway kind picks up gateway_, without being listed. Because the exact $type wins over the inheritance fallback, switching a concrete type off with false (or overriding it) also stops it from inheriting a base convention โ€” and the concrete task types each need their own entry, since the default map lists them individually rather than only bpmn:Task.

Some types are intentionally left out. bpmn:Process is not covered: a process ID is a public contract (the deployment key, and what a call activity references), not a diagram-internal identifier. Elements no modeler ever shows (bpmn:LaneSet, bpmn:DataObject, bpmn:Category, bpmn:CategoryValue, bpmn:Property) are skipped because nobody reads their IDs. Message, signal, error and escalation definitions are left to the engine, as in no-generated-ids. Any other type not in the table is skipped too, so an exotic element nobody configured never produces a report.

Event-definition qualifiers โ€‹

An event id may optionally name its event definition โ€” messageStartEvent_membershipRequested instead of startEvent_membershipRequested. The accepted set is derived from the element's own<bpmn:*EventDefinition> children, so a qualifier that matches passes and a qualifier that lies is reported. The qualifier is the definition name lowercased (bpmn:TimerEventDefinition โ†’ timer): message, timer, signal, conditional, escalation, error, link, terminate, compensate. It is prepended to whatever prefix the type resolves to (startEvent_ โ†’ timerStartEvent_, a custom boundaryEvent_ โ†’ messageBoundaryEvent_).

eventDefinitionQualifier controls this:

modeaccepted for a message start event with prefix startEvent_
optional (default)startEvent_โ€ฆ or messageStartEvent_โ€ฆ
requiredmessageStartEvent_โ€ฆ only (plain prefix when no definition)
offstartEvent_โ€ฆ only
๐Ÿ‘ startEvent_membershipRequested         always valid
๐Ÿ‘ messageStartEvent_membershipRequested  it IS a message start event
๐Ÿ‘Ž timerStartEvent_membershipRequested    no timer event definition

The default optional only widens what passes, so enabling the rule never rejects an id that was valid before. A lying qualifier gets its own message โ€” Element id claims a timer event, but this element has no timer event definition โ€” separate from the plain wrong-prefix / wrong-case one.

Configuration โ€‹

json
{
  "rules": {
    "@miragon/rules/element-id-naming": [
      "error",
      {
        "prefixes": {
          "bpmn:SequenceFlow": "Flow_",
          "bpmn:ScriptTask": false
        },
        "case": "snake_case",
        "eventDefinitionQualifier": "optional"
      }
    ]
  }
}
  • prefixes: merged over the defaults, so you only state what differs. false switches a type off entirely.
  • case: the shape of the part after the prefix: camelCase (default), PascalCase, snake_case, kebab-case or any.
  • eventDefinitionQualifier: whether an event id may name its event definition โ€” optional (default), required or off. See Event-definition qualifiers.

For ID generators โ€‹

A tool that generates IDs can resolve the same convention the rule checks, from the same config:

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

const convention = new naming.ElementIdConvention(config);

convention.prefixOf(element); // 'startEvent_', or null when the type is not checked
convention.prefixesFor(element); // every accepted prefix, e.g. ['startEvent_', 'messageStartEvent_']
convention.case; // the case the name part must follow, e.g. { label: 'camelCase', pattern }
convention.qualifier; // 'off' | 'optional' | 'required'

Further reading โ€‹