CALM (the Common Architecture Language Model) is a JSON Schema vocabulary for describing software architecture as data: the nodes that make up a system, the relationships between them, the interfaces they expose, the business flows that run across them, and the controls that govern them. A CALM document is a plain JSON file that validates against this schema, so it can be produced and consumed by tooling — generated from code, rendered as diagrams, checked in CI, or used to enforce architectural and compliance rules — rather than living only as a diagram in a slide deck.
- Nodes — architecture components (systems, services, databases, actors) with properties, interfaces, and deployments
- Relationships — connections between nodes (
interacts,connects,deployed-in,composed-of) - Flows — business flows composed of ordered transitions across relationships, mapping business processes onto technical components
- Controls — security and compliance requirements attached to nodes, relationships, or flows
- Interfaces — modular interface definitions, either built in or externally defined
- Metadata — free-form annotations on any schema element
The schema is published to npm as @finos/calm-schema:
npm install @finos/calm-schemaEach published version is immutable and corresponds to a git tag in this repository (e.g. v1.2). See
CHANGELOG.md for what changed in each release. CALM tooling — including the
CLI, CALM Hub, and the VS Code extension — depends on a
specific published version of this package to validate CALM documents.
CALM Schema is one of three repositories that make up the FINOS Architecture as Code project, also known as CALM:
| Repository | Contents |
|---|---|
| calm-governance | The governance home — project-wide governance, contribution guidelines, and Code of Conduct. Holds no code. |
| calm-schema | This repository. The CALM Meta Schema, its documentation, and validation test suite. |
| architecture-as-code | The main repository — CLI, server, shared libraries, data models, widgets, CALM Hub and its UI, the VS Code extension, and the documentation site. Depends on @finos/calm-schema published from this repository. |
Schema changes are developed on feature branches and merged to main via pull request; main always
holds the current, unreleased state of the schema. Merging to main does not publish anything by
itself — it produces a release candidate that can accumulate further merged changes before a release is
deliberately cut and published to npm as a separate, manually triggered step.
- Open a GitHub Issue using the Schema Change Proposal template, describing the motivation, the proposed change, and the impact on existing tooling.
- Once agreed, develop the change on a feature branch alongside updated validation tests. CI runs the schema test suite on every push.
- Open a pull request to
main. It requires approval from a member of the calm-schema-governance team — see CONTRIBUTING.md. - When maintainers decide to cut a release, publishing to npm and tagging the release is a separate, manually triggered step, kept deliberately outside of the merge process to avoid publishing a schema version prematurely.
For any questions, bugs or feature requests please open an issue For anything else please send an email to {project mailing list}.
To submit a contribution:
- Fork it (https://github.com/finos/calm-schema/fork)
- Create your feature branch (
git checkout -b feature/fooBar) - Read this repository's contribution guidelines, the project-wide contribution guidelines and the Community Code of Conduct
- Commit your changes (
git commit -am 'Add some fooBar') - Push to the branch (
git push origin feature/fooBar) - Create a new Pull Request
Changes to the schema require approval from a member of the calm-schema-governance team — see CONTRIBUTING.md.
NOTE: Pull requests must follow this repository’s contribution policy. FINOS projects typically use DCO (signed commits) and/or CLA via EasyCLA, depending on configuration. Read FINOS Contribution Requirements before contributing.
Questions about CLA, DCO, or EasyCLA? Email help@finos.org
The project's governance policies, Maintainer roster and Code of Conduct are maintained in finos/calm-governance and apply across every repository in the project.
| Document | Covers |
|---|---|
| GOVERNANCE.md | Roles, contribution rules, Maintainer voting, and how Maintainers are added and removed |
| MAINTAINERS.md | The project-wide Maintainer roster and the Lead Maintainer |
| CONTRIBUTING.md | Project-wide contribution guidelines |
| CODE_OF_CONDUCT.md | The Code of Conduct all participants are subject to |
Copyright 2026 FINOS
Distributed under the Apache License, Version 2.0.
SPDX-License-Identifier: Apache-2.0