n8n-nodes-bpmn-validator

Systematische Prüfung von BPMN-2.0-XML-Dateien in n8n — vollständig offline, ohne Java/Python/xmllint.

Version 0.4 · Alle Prüfschichten des Regelkatalogs V0.1 implementiert (XML, XSD, REF, STR, EVT, GWY, FLW, ACT, DAT, DI, QLT + Custom Rules + Auto-Fix) plus P3: Engine-Profile (Camunda 7/8, Flowable, Activiti) und CI/CD-CLI bpmn-validate

Technische Referenz: OMG BPMN 2.0.2 · Normreferenz: ISO/IEC 19510:2013 (entspricht inhaltlich BPMN 2.0.1).

Prüfschichten (Version 0.1)

| Schicht | Regeln | Status | |---|---|---| | XML-Syntax + Namespaces | BPMN-XML-001…008 | ✅ | | XSD (normative OMG-Schemas, im Paket enthalten) | BPMN-XSD-001…006 | ✅ vollständige libxml2-Validierung via WebAssembly (xmllint-wasm) | | Referenzintegrität | BPMN-REF-001…017 | ✅ | | Struktur/Graph (Erreichbarkeit, Sackgassen, Zyklen-Klassifikation) | BPMN-STR-001…012 | ✅ | | Events | BPMN-EVT-001…022 | ✅ (EVT-004/007 via FLW-010/011) | | Gateways inkl. Event-Based Gateway | BPMN-GWY-001…014 | ✅ | | Flows & Collaboration | BPMN-FLW-001…014 | ✅ (FLW-003→STR-005, FLW-006→GWY-013/ACT-009, FLW-014→REF-005) | | Custom Rules (JSON, deklarativ, kein eval) | CUSTOM-* | ✅ | | Activities/SubProcesses (Event-SubProcess, Compensation, Multi-Instance, Loops, Call Activity, Default Flows) | BPMN-ACT-001…012 | ✅ (ACT-002→EVT-020/022, ACT-004→XSD-003) | | Daten & Data Associations (Flussrichtung, DataObject-/DataStore-Referenzen, ungenutzte Objekte) | BPMN-DAT-001…007 | ✅ (DAT-004→REF-014) | | BPMN DI: Plane/Shape/Edge-Konsistenz, Bounds, Waypoints, Doppeldarstellung; Vollständigkeit nur im Strict-DI-Modus, semanticOnly meldet fehlende Darstellung nie | BPMN-DI-001…010 | ✅ (unaufgelöstes bpmnElement→REF-007) | | Modellierungsqualität (Namen, Pfad-/Tiefen-Schwellenwerte, Platzhalternamen, Parallel-Split ohne Join, lineare Ketten, Doku) — nur WARNING/INFO | BPMN-QLT-001…015 | ✅ (Profil strict oder Layer explizit aktiviert) | | Auto-Fix-Engine: SAFE-Fixes auf DOM-Kopie (z. B. negative DI-Bounds → Betrag), REVIEW nur als Vorschlag, Change Log, Re-Validierung des Ergebnisses, Original bleibt unangetastet | DI-007 SAFE + REVIEW-Vorschläge | ✅ | | Engine-Profile (optional): Camunda 8/Zeebe (zeebe:taskDefinition, Complex Gateway/Transaction/Conditional nicht unterstützt, ignorierte Datenobjekte/Lanes), Camunda 7 / Flowable / Activiti (Implementierungs-/Zuweisungs-Attribute) — greifen nur bei isExecutable="true" | ENGINE-* (source ENGINE_PROFILE, nie OMG/ISO) | ✅ + Statusflag engineCompliant | | CI/CD-CLI bpmn-validate (gleiche Engine wie der Node) | Exit-Codes 0/1/2 | ✅ |

Grundsatz: Übersprungene Prüfungen werden im Output als skipped mit Grund ausgewiesen — niemals als bestanden vorgetäuscht. Schlägt die WASM-Initialisierung fehl, meldet xsd.mode = "unavailable" das ehrlich (keine Pseudo-XSD-Prüfung).

Delegierte Regeln (bewusst nicht doppelt gemeldet): EVT-004/007→FLW-010/011 · FLW-003→STR-005 · FLW-006→GWY-013/ACT-009 · FLW-014→REF-005 · ACT-002→EVT-020/022 · ACT-004→XSD-003 · DAT-004→REF-014 · DI-003/004 bei unaufgelöster Referenz→REF-007. Noch nicht als eigenständige Prüfung umgesetzt: GWY-005-Teilfälle jenseits Message/ReceiveTask-Mix sowie exotische Choreography-/Conversation-Semantik (V1.0-Abgrenzung laut Katalog §26).

Installation

cd C:\n8n\n8n-inst\.n8n\nodes
npm install n8n-nodes-bpmn-validator   # bzw. Pfad zum Paketordner
# n8n neu starten!

Voraussetzungen: Node.js ≥ 20.19, selbstgehostetes n8n. Keine Internetverbindung zur Laufzeit nötig.

Node-Konfiguration

• Input Source: Binary-Property, JSON-Feld oder direktes XML-Textfeld
• Validation Profile: standard | strict | custom (Schichten einzeln wählbar)
• Custom Rules (JSON): Array eigener Regeln, z. B.

[{
  "id": "CUSTOM-001",
  "name": "Tasks benötigen Namen",
  "severity": "ERROR",
  "scope": ["task", "userTask", "serviceTask"],
  "condition": { "field": "name", "operator": "notEmpty" },
  "message": "Jede Aktivität muss eine Bezeichnung besitzen."
}]

Operatoren: exists, notExists, empty, notEmpty, equals, notEquals, contains, notContains, matches, notMatches, in, notIn, greaterThan, lessThan, minLength, maxLength, hasIncoming, hasOutgoing, incomingCount, outgoingCount, forbidden sowie when + require (elementType, mustBePrecededBy, mustBeFollowedBy — z. B. Vier-Augen-Prinzip).

• Options: failOnInvalid (Workflow-Gate), severityOverrides ({"BPMN-EVT-002":"WARNING","BPMN-STR-008":"off"}), HTML-Report als Feld und/oder Binary, Größenlimit.

Output (pro Item)

{
  "valid": false,
  "xmlValid": true, "schemaValid": true, "standardCompliant": false,
  "structurallySound": true, "qualityPassed": true, "customRulesPassed": true,
  "score": 78, "grade": "C",
  "xsd": { "mode": "full", "schemaVersion": "BPMN 2.0.2", "schemas": ["BPMN20.xsd", "…"] },
  "statistics": { "fatal": 0, "errors": 1, "warnings": 1, "info": 0, "byLayer": { } },
  "validation": { "xml": { "status": "ok" }, "semantics": { "status": "findings", "findingCount": 1 } },
  "findings": [ { "ruleId": "BPMN-EVT-001", "severity": "ERROR", "source": "OMG_BPMN_2_0_2",
                  "elementId": "Start_1", "message": "…", "line": 5, "fixType": "NONE" } ],
  "changes": [],
  "file": { "name": "prozess.bpmn", "bytes": 4821, "sha256": "…" },
  "htmlReport": "<!DOCTYPE html>…"
}

Ein einzelner normativer ERROR setzt standardCompliant=false — unabhängig vom Score.

CLI für CI/CD

npx bpmn-validate prozess.bpmn                          # Text-Ausgabe, Exit 1 bei ERROR/FATAL
npx bpmn-validate *.bpmn --profile strict --engine camunda8
npx bpmn-validate prozess.bpmn --json                   # vollständiges JSON-Ergebnis
npx bpmn-validate prozess.bpmn --report-dir reports --fix safe --corrected-dir fixed
npx bpmn-validate prozess.bpmn --fail-on warning        # streng: auch Warnungen brechen den Build

Exit-Codes: 0 bestanden · 1 Schwellenwert verletzt (--fail-on fatal|error|warning|never, Default error) · 2 Bedienungs-/IO-Fehler.

Entwicklung

npm install && npm run build && npm test   # 17 Tests, Fixtures unter test/fixtures/

Fachliche Spezifikation: REGELKATALOG-V0.1.md (136 Regeln) · Architektur: ARCHITEKTUR.md · Projektplan: PROJEKTPLAN.md.

Lizenz

Proprietäre Lizenz (siehe LICENSE): Installation und Betrieb in eigenen n8n-Instanzen erlaubt; die Kennzeichnung „Powered by Thomas Braun" in Berichten und die Copyright-Hinweise dürfen nicht entfernt oder verändert werden (wesentliche Bedingung). Die mitgelieferten OMG-XSD-Schemas unterliegen den Bedingungen der OMG.

Powered by Thomas Braun · © Thomas Braun