UBML — Unified Business Modeling Language

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 bridges the gap between informal workshop discovery and formal business modeling—designed from the ground up for AI assistance and modern development workflows.

📖 Read the full vision →

The Problem

Software development is getting dramatically faster. AI-assisted coding tools are turning what took weeks into hours. But this creates a new bottleneck: understanding what to build.

The gap is widening. Implementation accelerates while specification stays stuck in slides, scattered notes, and diagrams that can't be validated or versioned. Organizations produce more software, faster, that doesn't match how the business actually works.

Traditional modeling tools don't help:

• UML/BPMN demand precise semantics before you've understood the business
• Diagramming tools present blank canvases with no guidance
• Workshop notes can't be validated, connected, or processed

UBML solves this by treating business understanding as code - structured, validated, version-controlled and designed for AI assistance.

Who Is This For?

UBML is for everyone who needs to understand how a business works:

| Role | Use Case | |------|----------| | Software engineers | Understand the real-world context and motivation behind what you're building | | Management consultants | Capture workshop findings in structured, validated models | | Business analysts | Map how organizations actually operate | | Strategy teams | Build ROI-backed business cases for change | | Operations leaders | Identify bottlenecks and improvement opportunities | | Tool developers | Embed UBML editing in web applications |

Whether you're figuring out what to build or why it matters, UBML provides a shared language between business and technology.

What You Can Model

| Domain | Elements | |--------|----------| | Processes | Workflows (L1–L4), steps, decisions, phases | | Organization | Roles, teams, systems, resource pools, skills | | Information | Entities, documents, locations, relationships | | Strategy | Value streams, capabilities, products, portfolios | | Analysis | KPIs, ROI models, simulation scenarios | | Improvements | Hypothesis trees to identify how to make more money |

Key Features

• Version control — Track changes to business processes with Git
• Validation — Schema + cross-document references in one call
• Editor support — Red squiggles in VS Code as you type
• CLI for CI/CD — Validate models in your pipeline
• Universal — Works everywhere: browser, Node, Deno, Bun (zero Node deps)
• AI-ready — Semantic structure designed for AI assistance
• Open standard — MIT licensed, no vendor lock-in

Quick Example

# process.ubml.yaml
ubml: "1.1"

processes:
  PR00001:
    name: "Customer Onboarding"
    description: "End-to-end onboarding from application to activation"
    level: 3

    steps:
      ST00001:
        name: "Receive Application"
        kind: action
        description: "Receive and log new application"

      ST00002:
        name: "Verify Identity"
        kind: action
        description: "Verify customer identity documents"
        inputs:
          - ref: EN00001
        outputs:
          - ref: EN00002

      ST00003:
        name: "Approved?"
        kind: decision
        description: "Decision point for application approval"

See the example/ directory for a complete workspace.

Getting Started

Install

# Install globally for CLI usage
npm install -g ubml

# Or install locally for library integration
npm install ubml

Initialize a workspace

ubml init my-project
cd my-project

This creates:

my-project/
├── my-project.workspace.ubml.yaml
├── process.ubml.yaml
└── actors.ubml.yaml

Configure VS Code

Tip: Running ubml init automatically creates VS Code settings for you!

For manual setup, install the YAML extension and ubml init will generate .vscode/settings.json with schema validation configured for both simple (process.ubml.yaml) and prefixed (my-process.process.ubml.yaml) file naming patterns.

Validate

# Single file
ubml validate process.ubml.yaml

# Entire workspace
ubml validate ./my-project

# JSON output for CI/CD
ubml validate . --format json

For Developers

Library Usage

// Parse, validate, serialize (works everywhere - browser, Node, Deno, Bun)
import { parse, validate, serialize, schemas } from 'ubml';

// Node.js file operations
import { parseFile, validateWorkspace, serializeToFile } from 'ubml/node';

// ESLint plugin
import ubml from 'ubml/eslint';

Parse and Validate

import { parse, validate } from 'ubml';

// Parse documents
const actors = parse(actorsYaml, 'actors.actors.ubml.yaml');
const process = parse(processYaml, 'process.process.ubml.yaml');

// Validate everything (schema + cross-document references)
const result = await validate([actors.document!, process.document!]);

if (!result.valid) {
  for (const error of result.errors) {
    console.error(`${error.filepath}: ${error.message}`);
  }
}

// Check for warnings (unused IDs with line numbers)
for (const warning of result.warnings) {
  console.warn(`${warning.filepath}:${warning.line}:${warning.column} - ${warning.message}`);
}

Validate Workspace (Node.js)

import { validateWorkspace } from 'ubml/node';

// Validate all UBML files in a directory (schema + references)
const result = await validateWorkspace('./my-workspace');

if (!result.valid) {
  console.log(`${result.errorCount} errors in ${result.fileCount} files`);
  for (const file of result.files) {
    for (const error of file.errors) {
      console.error(`${file.path}:${error.line} - ${error.message}`);
    }
  }
}

TypeScript Types

import type { Process, Step, Actor, ProcessDocument } from 'ubml';

const process: Process = {
  id: 'PR00001',
  name: 'Customer Onboarding',
  level: 3,
  steps: {
    ST00001: {
      name: 'Receive Application',
      kind: 'action',
    }
  }
};

ESLint Integration

// eslint.config.js
import ubml from 'ubml/eslint';

export default [
  {
    files: ['**/*.ubml.yaml'],
    ...ubml.configs.recommended,
  },
];

File Naming Convention

| Pattern | Purpose | |---------|---------| | *.workspace.ubml.yaml | Workspace configuration | | *.process.ubml.yaml | Process definitions | | *.actors.ubml.yaml | Roles, teams, systems | | *.entities.ubml.yaml | Data model | | *.hypotheses.ubml.yaml | Problem framing | | *.strategy.ubml.yaml | Strategic elements | | *.metrics.ubml.yaml | KPIs and analysis | | *.scenarios.ubml.yaml | Simulations |

Documentation

• Vision — Why UBML exists and where it's going
• Best Practices — Guidelines for effective modeling
• Design Principles — DSL design philosophy
• Examples — Sample workspace with all document types
• CLI Schema Reference — Run ubml schema to explore interactively

Open Standard

UBML is released under the MIT License. Your models belong to you—plain text files you can version, export, and process with any tool. No vendor lock-in, no proprietary formats.

Contributing

See CONTRIBUTING.md for development setup.

# Install dependencies (uses npm workspaces)
npm install

# Build all packages
npm run build

# Run tests
npm run test

# Type check
npm run typecheck

License

MIT — see LICENSE

UBML is developed by NETWORG, a consulting and technology firm focused on business process improvement.