CALM is an open-source, JSON-based meta-schema for defining system architectures as code — versioned, validatable, and composable alongside the implementations they describe.
CALM turns architecture into a versioned JSON document that travels with the code, validates in CI, and binds compliance controls to the relationships they govern.
architecture.calm.json, validated against its pattern and the shared meta-schema.calm validate runs next to your unit tests; non-conforming changes fail the build, not the next Architecture Review Board (ARB).@finos/calm-cli from npm, render with a self-hosted CALM Hub, and ship a docs site with calm docify.For three decades, architecture artefacts have lived in Visio files, Confluence pages, and PowerPoint decks. Implementation has lived in Git. The two have drifted apart at every release. CALM closes that gap by treating the model itself as a versioned JSON document that travels with the source.
Every Tier 1 institution has the same problem. A reference architecture is approved by a board, drawn in Visio, attached to an Architecture Decision Record (ADR), and within two sprints it no longer reflects the deployed estate. Reviews happen in meetings that produce no machine-checkable output. Compliance evidence becomes a forensic exercise — piecing together screenshots, change tickets, and runbook entries to satisfy DORA Art. 6, SOX ITGC, or MAS TRM.
A CALM architecture.calm.json is the contract. It binds three things: intent (the pattern),
instantiation (the deployed system), and control (the compliance posture). You review it in a pull request,
validate it in CI, render it as C4 (context/container) diagrams, and query it for drift — one
artefact, several views. The same artefact answers what is the system?,
does it meet our golden pattern?, and which controls apply?.
CALM has a small, deliberate set of primitives. Each is a typed JSON object with a unique identifier and a defined slot in the meta-schema. Learn these seven and you can read almost any CALM document — interfaces and evidence, defined in the glossary, complete the set.
A service, database, network, actor, deployment target, or other addressable element. Identified by a
stable unique-id, and exposing interfaces — typed connection points such as
a URL or host/port pair.
Connects two or more nodes. The relationship-type determines semantics:
connects, deployed-in, composed-of, interacts, or
options (a decision point in a pattern).
The escape hatch. Anything that does not fit the core schema — cost centre, data classification, business owner — lives here as structured key/value pairs.
A pattern is a JSON Schema that describes a class of valid architectures — for example, a golden three-tier web app or an event-driven microservice topology. Patterns are the unit of reuse.
An architecture document is a specific, validated instance of a pattern. It contains the same nodes and relationships, populated with real names, owners, and runtime details.
Declarative requirements attached to nodes or relationships. Examples: “all relationships entering PCI scope must use mutual TLS (mTLS)”, “every persistent store must declare encryption at rest”.
A flow describes a business or data path across nodes — for example, the steps to register an attendee, settle a trade, or process an instant payment. Flows reference existing nodes and relationships in order, so they remain consistent with the structural model.
Three nodes, two relationships, one control. The same model is renderable as a C4 container diagram or as a Mermaid graph — CALM is the source, the diagrams are views.
FINOS members did not open-source CALM to make documentation prettier. They open-sourced it because regulators are asking the same questions in five jurisdictions, and there is no scalable way to answer them with PowerPoint.
Attach DORA Art. 6, PCI DSS v4.0.1 Req. 4, and SWIFT CSCF 2.4A directly to the connections they constrain. Evidence is a query against the model, not a reconstruction from tickets and screenshots.
A nightly job introspects the cluster (or Terraform state, or cloud APIs) and renders the live topology as CALM. Diff against the approved document → drift PR opened automatically.
Architecture changes are GitHub pull requests on the CALM document. Reviewers see the JSON diff, the rendered C4 view, and the controls delta in the same place they review code.
A new service must validate against the approved pattern before merge. The validation gate fails the build; by the time a system reaches production review, it has already been validated.
CALM validation runs on every pull request and blocks the merge on failure — the same gate that catches a failing unit test or SAST finding.
calm validate sits alongside unit tests and SAST as a first-class CI gate.
CALM ships as an npm CLI. The only hard prerequisite is Node.js 20+ — the floor documented in the
official getting-started guide. Java 21 and Maven are needed only if you build CALM Hub from
source; the published Docker image and the CLI itself need neither. Start with the
preflight check — if a binary already shows ok, skip the step that installs it.
Run the loop below once. It probes every binary the rest of this section installs and prints
ok with a version or missing. Each subsequent step is safe to skip if its
binary reports ok at a recent enough version (Node 20+, Java 21+ for CALM Hub).
# report which prerequisites are present on this machine
for cmd in curl gpg make git node npm calm java mvn; do
if command -v "$cmd" >/dev/null 2>&1; then
ver=$("$cmd" --version 2>/dev/null | head -n1)
printf " ok %-6s %s\n" "$cmd" "$ver"
else
printf " missing %-6s -\n" "$cmd"
fi
done
Typical output on a fresh Ubuntu 26.04 box:
ok curl curl 8.18.0 (x86_64-pc-linux-gnu) ok gpg gpg (GnuPG) 2.4.8 missing make - ok git git version 2.53.0 missing node - missing npm - missing calm - missing java - missing mvn -
Refresh the package index and install the small set of tools you need to bootstrap Node. Skip this step
if the preflight reported ok for curl, gpg, make,
and git — ca-certificates is preinstalled on Ubuntu Server images.
# refresh index, install build essentials and curl
sudo apt update
sudo apt install -y curl ca-certificates gnupg build-essential git
Ubuntu 26.04 ships a recent Node in apt, but it tracks Debian’s snapshot and can
drift from the active LTS. Use the NodeSource repository to pin Node 22.x — the CLI’s
documented floor is Node 20+, and Node 22 is a maintenance LTS line supported until April 2027
(Node 20 reached end-of-life in April 2026; Node 24 is the current active LTS if you prefer it). Skip
this step if the preflight reported ok for both node and npm at
v20 or newer.
# add NodeSource repo and install Node 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
Confirm both binaries are on PATH and reporting a version on the 22.x line.
node --version v22.14.0 npm --version 10.9.2
Pull the official package from npm. The binary is exposed as calm. Skip if the preflight
already reported ok for calm — re-run only to upgrade.
npm install -g @finos/calm-cli
Print the version and the top-level command list.
calm --version calm --help Commands: generate [options] Generate an architecture from a CALM pattern file. validate [options] Validate that an architecture conforms to a given CALM pattern. diff [options] Compare two CALM documents (architectures or patterns) and report what changed. template [options] Generate files from a CALM model using a Handlebars template bundle. docify [options] Generate a documentation website off your CALM model. init-ai [options] Augment a git repository with AI assistance for CALM. help [command] display help for command
Only required if you build the CALM Hub registry/visualisation server from source. It is a Quarkus
application needing Java 21+ and Maven 3.8.6+ — to skip Java entirely, run the published Docker
image instead (see the tutorial). Skip this step if the preflight reported
ok for both java (21 or newer) and mvn.
sudo apt install -y openjdk-21-jdk maven java --version mvn --version
The FINOS monorepo carries the spec, reference patterns, and the conference-signup tutorial used below.
git clone https://github.com/finos/architecture-as-code.git
cd architecture-as-code/calm/getting-started
ls -1 *.json
conference-signup.pattern.json
Take the official getting-started pattern, instantiate it as an architecture, validate, visualise, and render a documentation site. Five steps — locate, generate, validate, visualise, docify — the same loop you will run in CI.
The FINOS monorepo bundles a reference pattern for a simple attendee-registration system. The pattern is a JSON Schema describing the shape of a valid architecture.
cd architecture-as-code/calm/getting-started ls -1 README.md conference-signup.pattern.json controls img
calm generate walks the pattern and produces a stub architecture document — five
nodes and four relationships for this pattern. The stub contains placeholders
([[ HOST ]], -1) that you replace with real values.
calm generate \ --pattern ./conference-signup.pattern.json \ --output ./conference-signup.arch.json info [file-system-document-loader]: ./conference-signup.pattern.json exists, loading as file... info [calm-generate]: Generating a CALM architecture... info [calm-generate]: Successfully generated architecture to [./conference-signup.arch.json]
calm validate checks the architecture against the pattern (schema conformance) and against
any attached controls. The exit code is non-zero only on errors; add --strict to fail on
warnings too — that combination is the CI gate. Warnings on a fresh stub are expected: they point
at the placeholder values you have not filled in yet.
calm validate \ --pattern ./conference-signup.pattern.json \ --architecture ./conference-signup.arch.json info [calm-validate]: Formatting output as json { "jsonSchemaValidationOutputs": [], "spectralSchemaValidationOutputs": [ { "code": "architecture-has-no-placeholder-properties-string", "severity": "warning", "message": "String placeholder detected in architecture.", "path": "/nodes/conference-website/interfaces/conference-website-url/url", … }, … six more placeholder warnings … ], "hasErrors": false, "hasWarnings": true }
CALM Hub is the self-hostable registry and visualisation server for CALM documents. Upload the architecture to your instance and you get a rendered topology and a shareable URL. The quickest route is the published Docker image; building from source needs Java 21 + Maven.
# quickest: published Docker image (no Java required) cd architecture-as-code/calm-hub/deploy docker compose up # or: dev mode from source, standalone storage (no MongoDB required) cd architecture-as-code ./mvnw -pl calm-hub quarkus:dev -Dcalm.database.mode=standalone calm-hub on JVM (powered by Quarkus 3.x) started. Listening on: http://localhost:8080
calm docify generates a static site from an architecture — nodes, relationships,
controls, and embedded diagrams. The output is a folder you can publish to GitHub Pages.
calm docify \
--architecture ./conference-signup.arch.json \
--output ./website
# writes a static documentation site into ./website
Truncated for clarity — two nodes and two relationships are elided, and the full document also
carries metadata and controls. Note the interfaces on each node: typed connection points whose
placeholder values ([[ HOST ]], -1) you fill in, and exactly what the first-run
validate warnings point at. The $schema URL records which pattern the document instantiates.
{
"$schema": "https://calm.finos.org/getting-started/conference-signup.pattern.json",
"nodes": [
{
"unique-id": "conference-website",
"node-type": "webclient",
"name": "Conference Website",
"description": "Website to sign up for a conference",
"interfaces": [{ "unique-id": "conference-website-url", "url": "[[ URL ]]" }]
},
{
"unique-id": "load-balancer",
"node-type": "network",
"name": "Load Balancer",
"interfaces": [{ "unique-id": "load-balancer-host-port", "host": "[[ HOST ]]", "port": -1 }]
},
/* … "attendees" (service) and "attendees-store" (database), each with image + port interfaces … */
{
"unique-id": "k8s-cluster",
"node-type": "system",
"name": "Kubernetes Cluster",
"description": "Kubernetes Cluster with network policy rules enabled"
}
],
"relationships": [
{
"unique-id": "conference-website-load-balancer",
"protocol": "HTTPS",
"relationship-type": {
"connects": {
"source": { "node": "conference-website" },
"destination": { "node": "load-balancer" }
}
}
},
/* … "load-balancer-attendees" (mTLS) and "attendees-attendees-store" (JDBC) … */
{
"unique-id": "deployed-in-k8s-cluster",
"relationship-type": {
"deployed-in": {
"container": "k8s-cluster",
"nodes": [ "load-balancer", "attendees", "attendees-store" ]
}
}
}
]
}
A reference list of CALM-adjacent terms. Skim if you are already fluent; bookmark if you are not.
unique-id.@finos/calm-cli on npm) for generating, validating, diffing, templating, and documenting CALM documents.If you take nothing else from this page, take these. Each one shifts how architecture is practised — not what is drawn.
Diagrams are derived views. The CALM document is the source. If they disagree, the JSON wins — rebuild the picture from the data.
Everything — patterns, architectures, controls — validates against one meta-schema. The schema is the only thing you need to learn deeply.
One golden pattern, dozens of architectures. The pattern enforces what is non-negotiable; the architecture fills in the rest.
calm validate sits next to your unit tests. A non-conforming architecture fails the build — not the next architecture review board.
Attach DORA, PCI DSS, SOX, and MAS TRM requirements to the relationships they govern. Evidence is queryable, not forensic.
Self-host the registry from the published Docker image or run the Quarkus service from source. Diagrams render automatically from the model — no hand-drawn topology to maintain.
The authoritative sources. Pin these in your bookmarks bar.
npm install -g.