@bladelabs/bpmn-zod

Generate Zod schemas from the OMG BPMN 2.0 metamodel — like drizzle-zod but for process models.

Overview

@bladelabs/bpmn-zod reads the bundled bpmn.json descriptor from bpmn-moddle and generates Zod schemas at runtime for all 137 BPMN 2.0 types. It follows the same pattern as @bladelabs/dmn-zod but targets the OMG BPMN 2.0 specification.

• 137 complex types (Process, Task, SequenceFlow, Gateway, Event, ...)
• 9 enumerations (ProcessType, GatewayDirection, AssociationDirection, ...)
• Zero monorepo coupling — only peers on zod
• Works everywhere — browser, edge, serverless (no filesystem at runtime)
• Inheritance chain resolution — inherited fields included automatically
• Standards provenance — every schema carries .meta() with OMG BPMN 2.0 citation

Installation

pnpm add @bladelabs/bpmn-zod zod

Usage

Golden shape (pure absorption)

import { createBpmnSchema } from '@bladelabs/bpmn-zod'

const ProcessSchema = createBpmnSchema('Process')
const result = ProcessSchema.parse({
  id: 'proc-001',
  name: 'Murabaha Approval',
  isExecutable: true,
  processType: 'Private',
})

Enum schema

import { createBpmnEnumSchema } from '@bladelabs/bpmn-zod'

const ProcessTypeSchema = createBpmnEnumSchema('ProcessType')
ProcessTypeSchema.parse('Private')  // ✓
ProcessTypeSchema.parse('INVALID')  // throws

Domain shape (refined + extended)

import { createBpmnSchema } from '@bladelabs/bpmn-zod'
import { z } from 'zod'

const IslamicFinanceProcess = createBpmnSchema('Process', {
  refinements: {
    processType: () => createBpmnEnumSchema('ProcessType').default('Private'),
    isExecutable: () => z.literal(true),
  },
  extensions: {
    sharia_board_ref: z.string(),
    is_halal_certified: z.boolean(),
  },
})

Project-wide factory

import { createBpmnSchemaFactory } from '@bladelabs/bpmn-zod'

const { createBpmnSchema, createBpmnEnumSchema } = createBpmnSchemaFactory({
  coerce: true,  // XML string → native type conversion
  metaOverrides: { cascadeGroup: 'grc-islamic' },
})

Discovery helpers

import { getBpmnTypeNames, getBpmnEnumNames, getBpmnTypeProperties } from '@bladelabs/bpmn-zod'

getBpmnTypeNames()              // ['Interface', 'Operation', 'Process', ...]
getBpmnEnumNames()              // ['ProcessType', 'GatewayDirection', ...]
getBpmnTypeProperties('Process') // full property list including inherited

BPMN Metamodel Facts

| Metric | Value | |--------|-------| | Complex types | 137 | | Enumerations | 9 | | Max inheritance depth | 5 | | Namespace prefix | bpmn | | Namespace URI | http://www.omg.org/spec/BPMN/20100524/MODEL | | Source | bpmn-moddle resources/bpmn/json/bpmn.json |

Enumerations

| Name | Values | |------|--------| | ProcessType | None, Public, Private | | GatewayDirection | Unspecified, Converging, Diverging, Mixed | | EventBasedGatewayType | Parallel, Exclusive | | RelationshipDirection | None, Forward, Backward, Both | | ItemKind | Physical, Information | | ChoreographyLoopType | None, Standard, MultiInstanceSequential, MultiInstanceParallel | | AssociationDirection | None, One, Both | | MultiInstanceBehavior | None, One, All, Complex | | AdHocOrdering | Parallel, Sequential |

Schema Meta

Every generated schema carries .meta() with:

{
  id: 'zeroh:bpmn/process',
  prefLabel: 'BPMN Process',
  cascadeGroup: 'bpmn',
  category: 'bpmn',
  exactMatch: ['omg-bpmn:Process'],
  broader: ['zeroh:bpmn/flow-elements-container'],
  wasDerivedFrom: ['https://www.omg.org/spec/BPMN/2.0/PDF', ...],
  standards_provenance: {
    source_type: 'formal',
    standard: 'OMG Business Process Model and Notation 2.0',
    standard_uri: 'https://www.omg.org/spec/BPMN/',
    version: '2.0',
    conformance_predicate: 'dcterms:conformsTo',
    fields_from_standard: [...],
    zeroh_extensions: [],
  }
}

API Reference

| Export | Description | |--------|-------------| | createBpmnSchema(typeName, options?) | Generate Zod object schema for a BPMN type | | createBpmnEnumSchema(enumName, options?) | Generate Zod enum schema for a BPMN enumeration | | createBpmnSchemaFactory(defaults) | Create a factory with pre-configured defaults | | createBpmnValidationSchema(typeName, options?) | Strict schema — all fields required | | createBpmnPartialSchema(typeName, options?) | Partial schema — all fields optional | | getBpmnTypeNames() | List all 137 complex type names | | getBpmnEnumNames() | List all 9 enumeration names | | getBpmnTypeProperties(typeName) | Full property list including inherited | | registerBpmnSchema(typeName, schema) | Pre-register hand-authored schema | | initBpmnMetamodel(descriptor) | Override bundled metamodel |

Upgrading (when OMG releases a new BPMN version)

pnpm update bpmn-moddle                          # 1. Update moddle
cp node_modules/bpmn-moddle/resources/bpmn/json/*.json src/data/  # 2. Copy descriptor
# 3. Edit src/standard-config.ts (version, fullName, specPdfUrl)
pnpm generate:overloads && pnpm check            # 4. Regenerate + verify

See src/standard-config.ts for the ~5 fields to update. Everything else derives from the moddle JSON automatically.

Architecture

src/
  data/bpmn.json           # Bundled moddle descriptor (copied from bpmn-moddle)
  standard-config.ts       # Spec constants — the ONE file to edit on upgrade
  metamodel.ts             # Reads descriptor, resolves inheritance chains
  descriptions.ts          # Hand-authored field descriptions from OMG spec
  schema.ts                # Schema factory — derives all meta from config + descriptor
  types.generated.ts       # Auto-generated: type names, interfaces, TYPE_CHAINS

License

Apache-2.0 © 2026 Blade Labs Inc.