Types & Validation
Stateway lets you declare types, enumerations, and validation rules directly inside your BPMN process definition. The .bpmn file becomes the single source of truth: it describes what the process does and what data it accepts at every step.
These typed constructs (itemDefinition, ioSpecification, typed dataInput/dataOutput) are
parsed only from BPMN 2.0 XML definitions. JSON/YAML process definitions express a subset: declare a
userTask form explicitly via formSchema, and note that activity outputs are not type-validated.
See Processes → Typed I/O & Form Schemas.
Why This Matters
Without types, three problems are common in process automation:
- No structured enumerations. A "loan status" field can hold any string —
"approved","APPROVED","Approved", or a typo. Frontend and backend code must independently agree on valid values. - No declarative validation. Every service calling your API must validate inputs themselves. If a new integration forgets, bad data enters the process silently.
- No cross-instance references. When a renewal process needs data from the original loan, the only option is a service task making an HTTP call — an invisible dependency not visible in the diagram.
Stateway solves all three with standard BPMN 2.0 constructs plus lightweight extensions.
Four Constructs
| Construct | BPMN Element | Purpose |
|---|---|---|
| Inline Types | <bpmn:itemDefinition> | Declare a named type (primitive, object, or enum) once; reference it from multiple places |
| Typed Variables | <bpmn:dataObject> | Attach a type to a process-level variable |
| Activity Contracts | <bpmn:ioSpecification> | Declare what each task reads and writes, with types |
| Cross-Instance Lookup | <bpmn:dataStore> | Read variables from instances of another process, directly in the diagram |
All four constructs are optional and retrocompatible. Existing processes without them continue to work exactly as before.
The Core Principle
Types live inside the BPMN file, embedded in each itemDefinition. When you export a .bpmn, it carries its type definitions with it. Re-importing it into any Stateway environment reproduces the same validation behavior — no external registry, no configuration lookup.
Diagram (BPMN) = process logic + type definitions + validation rules
When to Use Types
| Situation | Recommendation |
|---|---|
| A field has a fixed set of valid values (status, category, decision) | Use an enum itemDefinition |
| A task receives a complex object (applicant, address) | Use an object itemDefinition + dataObject |
| You want the engine to reject bad data at the API boundary | Declare a dataObject and a typed POST /instances variable |
| A process needs data from another running process | Use a DataStore reference |
| A quick internal variable used in one condition | Leave it untyped in variables |
What Happens on Validation Failure
When a variable fails type validation, Stateway does not advance the BPMN token. Instead, it fires a ValidationError event that you can catch with a boundary event on the activity, or let bubble up to put the instance in error state.
See Error Handling for the full picture.
Navigation
- Inline Types — Define types with JSON Schema inside the BPMN
- Data Objects — Attach types to process-level variables
- I/O Specification — Declare typed contracts per activity
- Validation — Where and how validation runs
- Data Stores — Query data from other process instances
- Error Handling — Handle validation failures in BPMN
- Form Schema Migration — Upgrade existing
form_schemadefinitions