CALM (Common Architecture Language Model) is a machine-readable specification for describing software architecture as versioned code. It defines a JSON Schema for nodes, relationships, flows, and controls so an architecture can be validated, diffed, and governed in a pipeline rather than drawn in a diagram.
CALM
CALM, the Common Architecture Language Model, is FINOS’s specification for expressing software architecture as machine-readable, version-controlled code. It comes out of the Architecture as Code project and takes the position that an architecture diagram is the wrong artifact — a picture cannot be validated, cannot be diffed across releases, and cannot fail a build. A CALM document can do all three.
- Nodes and relationships - The core model: the systems, services, actors, and networks in an architecture, and the typed connections between them.
- Controls - Requirements attached directly to the architecture, so a security or compliance rule lives on the component it governs rather than in a separate document.
- Flows - Named sequences across relationships, describing how a request or a piece of data actually traverses the architecture.
- Patterns and validation - Reusable architectural patterns plus a CLI that checks a given architecture against them, which is what makes CALM enforceable in CI.
CALM matters to API practitioners because it is the layer above the contract. OpenAPI and AsyncAPI describe one interface each; CALM describes how those interfaces are wired into a system and what rules that wiring has to satisfy. That makes it a natural companion to API governance work — the same instinct that moves style rules into a linter, applied to architecture. It is also, alongside FDC3, one of the two FINOS specifications tracked in the weekly specification harvest.
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
