@finos/calm-schema
v1.3.0
Published
The CALM (Common Architecture Language Model) Meta Schema
Readme
CALM Schema
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
Using the schema
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.
Each release is also served at the URL in its $id, for example
https://calm.finos.org/release/1.2/meta/calm.json.
standards/ holds standards that extend the schema, for example the
deployment decorator standard. Each standard has its own version and is served
at https://calm.finos.org/standards/<name>/<version>/. The npm package does not include them.
Project repositories
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. |
Proposing a schema change
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. The publish workflow publishes the tag to npm and to calm.finos.org. Then it starts the schema compatibility workflow in architecture-as-code, which tests every CALM tool against the new version and opens an issue that names the tools that fail.
Contributing
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: All pull requests to this repository require a signed CLA via EasyCLA. Read FINOS Contribution Requirements before contributing.
Questions about the CLA or EasyCLA? Email [email protected]
Governance
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 |
A contributor must be nominated and approved by a vote of the existing Maintainers before they are granted write access to this repository, as set out in GOVERNANCE.md.
Support
Support is community-based and best-effort: ask in a GitHub issue in this repository. The project's SUPPORT.md states which schema releases are supported and when a release stops receiving security updates. To report a vulnerability privately, follow SECURITY.md, which also holds the dependency and code scanning policy and the instructions for verifying release integrity.
License
Copyright 2026 FINOS
Distributed under the Apache License, Version 2.0.
SPDX-License-Identifier: Apache-2.0
