# FlowMarkup

> FlowMarkup is a declarative, non-Turing-complete YAML format for defining process flows. It provides exactly 25 directives for sequencing, branching, error handling, parallel execution, and typed data flow. Every flow is validated by JSON Schema, 463 static analysis rules, and a native testing framework before execution.

## Key Facts

- Version: 0.9.0
- Format: YAML (single-file, declarative)
- Expression language: CEL (Common Expression Language) — non-Turing-complete
- Validation: JSON Schema (Draft 2020-12) + 463 static analysis rules + native testing framework
- License: Open Web Foundation Agreement 1.0 (OWFa 1.0)
- Author: Łukasz Nawojczyk (Progralink)
- 25 directives, 27 example flows, 50+ standard error types

## What Makes FlowMarkup Different

- Not a framework or library — it is a specification
- Separates orchestration from execution
- Process definitions are contracts, not programs
- AI models are called as services, not used as orchestrators
- Opaque secrets (cannot be logged, interpolated, or returned)
- Deny-by-default capability security
- Built-in circuit breakers, saga transactions, streaming (yield/onYield)
- Native testing with mocks, fixtures, assertions, and fault injection

## Specification Documents

- Language Specification: https://flowmarkup.com/spec/FLOWMARKUP-SPECIFICATION.md
- Validation Rules (463 rules): https://flowmarkup.com/spec/FLOWMARKUP-VALIDATION.md
- Testing Framework: https://flowmarkup.com/spec/FLOWMARKUP-TESTING.md
- Engine Implementation Guide: https://flowmarkup.com/spec/FLOWMARKUP-ENGINE.md
- Cross-Language Guide (Java, Go, Python, TypeScript, Rust, C#): https://flowmarkup.com/spec/FLOWMARKUP-ENGINE-CROSSLANG.md
- Secrets Management: https://flowmarkup.com/spec/FLOWMARKUP-SECRETS.md
- Error Catalog (50+ types): https://flowmarkup.com/spec/FLOWMARKUP-ERRORS.md
- Examples Guide: https://flowmarkup.com/spec/FLOWMARKUP-EXAMPLES.md
- Changelog: https://flowmarkup.com/spec/FLOWMARKUP-CHANGELOG.md
- JSON Schema (Draft 2020-12): https://flowmarkup.com/spec/FlowMarkup-0.9.0.schema.json

## Tools

- Online Inspector (validation + editing): https://flowmarkup.com/inspector/
- Claude AI Skill (FlowMarkup-aware authoring): https://flowmarkup.com/spec/FlowMarkup-0.9.0-skill.zip
- Full Spec Archive: https://flowmarkup.com/spec/FlowMarkup-0.9.0-spec.zip

## The 25 Directives

group, if, forEach, while, repeat, try, set, log, logWarn, logError, switch, assert, throw, return, yield, wait, waitUntil, break, continue, emit, waitFor, lock, cancel, parallel, race

## Default Actions (7)

call, run, exec, request, mail, storage, ssh

## Example (Minimal)

```yaml
flowmarkup:
  title: Hello World
  input:
    name: STRING
  output:
    greeting: TEXT
  requires: {}
  do:
    return:
      greeting: "Hello, {{name}}!"
```

## Website

https://flowmarkup.com/