ubml

UBML - Unified Business Modeling Language

npm version License: MIT

A notation for understanding how organizations create and deliver value.

UBML is a YAML-based format for capturing business processes, organizational structures, and strategic initiatives. It provides structure for the space between informal workshop discovery and formal business modeling — designed for business analysts and management consultants, with first-class support for AI assistance and version control.

Vision · Getting Started · Example Workspace · Documentation · Personas · npm

The Problem

AI-assisted coding is compressing implementation timelines from weeks to hours. But a new bottleneck has emerged: understanding what to build. Implementation accelerates while specification remains stuck in slides, scattered notes, and diagrams that can’t be validated or versioned.

Existing tools don’t address this well:

UBML bridges the gap between informal discovery and formal modeling — structured enough for validation and AI processing, readable enough for stakeholders who have never seen a modeling notation.

Read the full vision

Key Characteristics

What a Workspace Contains

A UBML workspace is a structured model of an organization — designed to be maintained across multiple improvement cycles rather than delivered once and discarded.

┌─────────────────────────────────────────────────────────────┐
│                        STRATEGY                             │
│       Value streams, capabilities, products, portfolios     │
├─────────────────────────────────────────────────────────────┤
│                     CHANGE & ANALYSIS                       │
│     Hypotheses, scenarios, KPIs, ROI business cases         │
├─────────────────────────────────────────────────────────────┤
│                     OPERATIONAL MODEL                       │
│         Processes, actors, entities, resources              │
├─────────────────────────────────────────────────────────────┤
│                       KNOWLEDGE                             │
│       Sources, insights, glossary, evidence chains          │
├─────────────────────────────────────────────────────────────┤
│                       WORKSPACE                             │
│            Configuration, scope, and conventions            │
└─────────────────────────────────────────────────────────────┘

Information flows between layers: knowledge feeds the operational model, the model informs analysis, analysis shapes strategy, and strategic priorities direct where to gather more knowledge. See Workspace Anatomy for details.

Format

UBML files are plain YAML:

ubml: "1.4"

processes:
  PR00001:
    name: "Customer Onboarding"
    description: "End-to-end process for onboarding new customers"
    level: 3

    steps:
      ST00001:
        name: "Receive Customer Application"
        kind: action
        inputs:
          - ref: EN00001  # Customer Application Form
        outputs:
          - ref: EN00002  # Verified Customer Record

      ST00002:
        name: "Verify Customer Identity"
        kind: action
        inputs:
          - ref: EN00002
          - ref: EN00003  # ID Documents

      ST00003:
        name: "Review Application"
        kind: decision
        description: "Approval or rejection decision point"

Files can be opened in any text editor, reviewed in Git diffs, and processed by AI assistants. The format is readable by both business stakeholders and engineers.

Audience

UBML is designed for consultant-led engagements that transition into client self-service. All participants work in the same workspace on the same model, with views adapted to their role.

Role What you do with UBML
Business Analysts Process transcripts and interviews into validated models. Map end-to-end workflows. Build hypothesis trees.
Management Consultants Drop in meeting notes, capture observations, review models, present findings to leadership.
Client Stakeholders Validate models — confirm “yes, this is what we actually do.” Provide corrections and context.
Operations Leaders Identify bottlenecks, define KPIs, evaluate business cases for proposed changes.
Strategy Teams Map capabilities, design value streams, prioritize investments across initiatives.
Software Developers Receive business context — understand why the process works this way before building.

See Personas & Consumers for detailed definitions.

Why Plain Text

The choice of YAML plain text is deliberate:

Improvement Cycle

UBML supports iterative organizational improvement — the workspace persists across cycles rather than being delivered once:

 ┌────────────────────────────────────────────────┐
 │                                                │
 ▼                                                │
Capture as-is → Analyze → Plan → Execute → Absorb ┘
  1. Capture — Model how the business actually operates today
  2. Analyze — Decompose issues, form hypotheses, simulate scenarios, build business cases
  3. Plan — Prioritize improvements, sequence initiatives, define the target operating model
  4. Execute — Implement changes (outside UBML — this is project management territory)
  5. Absorb — Yesterday’s target state becomes today’s baseline. The model is ready for the next cycle.

Process changes trace back through the initiative that delivered them, the hypothesis that proposed them, and the evidence that justified them. The workspace accumulates context across cycles.

Relationship to Formal Standards

UBML does not replace BPMN, ArchiMate, or UML. It sits upstream as the working format where business understanding is captured. When a client or enterprise tooling requires a formal notation, UBML exports to it.

Standard UBML Relationship
BPMN 2.0 Primary process export target
ArchiMate 3.2 Business and strategy layer mapping
UML 2.5 Activity, Use Case, Class, State Machine diagrams
DMN / CMMN Decision modeling and case management
Lean VSM Native value stream stage and flow time support
Mermaid / PlantUML Markdown-embeddable diagrams for documentation

Exports are lossy by design — UBML captures stakeholder context, hypotheses, and evidence chains that formal notations have no place for. The UBML model remains the source of truth. See Projections & Export Mappings for detailed mapping documentation.

Getting Started

1. Create Your First Workspace

npx ubml init my-first-project
cd my-first-project

This generates template files with example content showing the UBML structure.

You’ll need Node.js 18+. Visual tools are coming — for now, UBML uses the command line.

2. Explore and Build

# Browse your model
npx ubml show process

# Add elements interactively — the CLI guides you
npx ubml add process "Order Fulfillment"
npx ubml add step "Receive Order"
npx ubml add actor "Warehouse Worker"

# Validate everything
npx ubml validate .

Or open the folder in VS Code — UBML configures schema validation automatically for auto-complete, error highlighting, and field descriptions.

3. Iterate

Start with process and actors. Add entities, metrics, hypotheses, and strategy as understanding deepens. UBML supports progressive formalization — rough models are valid, additional rigor is optional until needed. See the example workspace for a complete sample.

File Types

All files end in .ubml.yaml. Add them as you need them:

File Type What Goes There
*.workspace.ubml.yaml Project scope and configuration
*.process.ubml.yaml How work gets done — workflows, steps, decisions
*.actors.ubml.yaml Who does the work — roles, teams, systems
*.entities.ubml.yaml What they work with — documents, data, locations
*.metrics.ubml.yaml How you measure — KPIs, costs, targets
*.hypotheses.ubml.yaml Problem analysis — issue trees, root causes
*.strategy.ubml.yaml Strategic elements — capabilities, value streams
*.scenarios.ubml.yaml What-if analysis — simulations, forecasts
*.sources.ubml.yaml Where knowledge comes from — interviews, documents
*.insights.ubml.yaml What was learned — pains, observations, opportunities
*.glossary.ubml.yaml Shared vocabulary — domain-specific term definitions

Documentation

Document What You’ll Find
Vision Why UBML exists, the specification crisis, what success looks like
Workspace Anatomy How the five conceptual layers connect and what each contains
Design Principles Binding constraints that govern every language design decision
Design Decisions Specific choices made, alternatives rejected, and rationale
Personas & Consumers Who uses UBML, what they need, and how they collaborate
Projections & Exports How UBML maps to BPMN, ArchiMate, UML, Mermaid, PlantUML, and more
Example Workspace A complete sample workspace with all document types
Schema Reference The YAML schema definitions that power validation
Contributing Development setup and contribution guidelines
Changelog Notable changes to UBML
Code of Conduct Community standards

Projection Details

Target Standard Mapping Document
BPMN 2.0 BPMN Projection
ArchiMate 3.2 ArchiMate Projection
UML 2.5 UML Projection
DMN / CMMN DMN-CMMN Projection
BMM 1.3 BMM Projection
Value Stream Mapping VSM Projection
Mermaid Mermaid Rendering
PlantUML PlantUML Rendering
Data Formats Data Format Mappings

For Developers

UBML works as a library in any JavaScript/TypeScript environment:

npm install ubml

import { parse, validate } from 'ubml';
import { validateWorkspace } from 'ubml/node';
import ubml from 'ubml/eslint';

Parse UBML files, validate schema + cross-document references, serialize back to YAML. Full TypeScript types for all elements. Works in browser, Node, Deno, Bun — zero Node dependencies in the core.

Open Standard

UBML is released under the MIT License and developed in the open. Models are plain text files that can be versioned, exported, and processed with any tool. Commercial tooling may be built on top of UBML, but the notation and models carry no vendor dependency.

Get Involved

UBML is developed by NETWORG, a consulting and technology firm focused on business process improvement. Part of the TALXIS platform ecosystem.

This site is open source. Improve this page.