Finish moving the CALM schema to finos/calm-schema and test the tools against each new release #3240

Status

Updated 2026-10-27. Steps 1 to 5 and 7 to 12 are complete. calm-schema is the only publisher of release/, standards/ and interfaces/ on calm.finos.org. All tools use schema 1.3. The three released decorator standards are on calm.finos.org, and CALM Hub serves them. In this repository, calm/ holds CALM's own architecture and the 2026-03 draft, which early adopters still use (#3532).

Other open items

Feature Proposal

Target Project:

calm/ and the tools that read it (CLI, shared, calm-server, calm-hub, calm-lab, calm-studio), plus finos/calm-schema and finos/calm-governance.

Description of Feature:

The schema moved to finos/calm-schema and the governance documents moved to finos/calm-governance. The move is not complete:

• .github/workflows/s3-sync.yml in this repo still publishes calm/ to the bucket behind calm.finos.org. Every schema $id points there. calm-schema publishes to npm only.
• No package in this repo uses @finos/calm-schema. All tools read calm/release and calm/draft from this repo.
• The README, AGENTS.md and calm/AGENTS.md still say that the schema lives here.

Thus a schema change merged in calm-schema does not get to calm.finos.org or to the tools. A change to calm/ here is published and makes the two copies different.

This issue makes calm-schema the only source of the schema. The tools here get the schema from npm, and a new workflow tests all of them against each new schema release. When a release breaks a tool, the workflow opens an issue. The drafts and release candidates are removed, and so are the parts of calm/ that nothing uses.

User Stories:

• As a schema maintainer, I want a release from calm-schema to be published to calm.finos.org and npm, so that there is one source of truth.
• As a tool maintainer, I want an issue when a new schema release breaks a tool, so that I know what to fix.
• As a contributor or an AI agent, I want each repo to say what it owns and how it relates to the other repos, so that I change the correct repo.

Current Limitations:

State of main on 2026-10-04:

Tools that read calm/release and calm/draft directly:

53 files outside calm/ refer to the drafts:

Proposed Implementation:

Prerequisites

These need setup outside the repos. @rocketstack-matt asked FINOS for P1 and P2 by email to help@finos.org on 2026-10-04, and will confirm on this issue when each one is in place.

This repo keeps its own AWS secrets, because the docs, lab and video deploys also use them.

Ordering rules

• One publisher per prefix. s3-sync.yml here syncs with --delete. If it still runs after calm-schema starts to publish, a push to calm/ here overwrites what calm-schema published. Step 1 removes it at the same time.
• The docs deploy deletes unknown prefixes. s3-docs-sync.yml syncs the docs build to the bucket root with --delete, and keeps only advent/, controls/, draft/, getting-started/, interfaces/, release/, samples/, video/ and workshop/. The next docs deploy deletes anything that calm-schema publishes outside these prefixes. Publish new content under release/<v>/, or add the new prefix to the exclude list first.

Steps

1. Publish the releases and the interfaces from calm-schema, and remove s3-sync.yml here.
   Needs: P1. @rocketstack-matt must confirm that P1 is in place before this step can be completed.

   • Add a calm-schema workflow that builds release/<v>/meta/ from each release tag (1.0, 1.1, 1.2, not the RCs) and interfaces/ from examples/interfaces/, then invalidates CloudFront. Sync each release/<v>/ prefix separately, so that a sync never deletes another version.
   • Remove s3-sync.yml here in the same change window. The drafts, getting-started and controls are then not published any more. They stay in the bucket until steps 6–8.
   • Done when every release/ and interfaces/ URL returns the same content as before.

2. Get the schema from npm.
   Needs: nothing.
   The root package.json pins @finos/calm-schema exactly as the latest release, and pins every release with an alias (for example "calm-schema-1.1": "npm:@finos/calm-schema@1.1.0"). Each workspace that imports the package declares it with "*". The CLI, calm-server and calm-hub copy the releases with scripts/copy-calm-schemas.mjs. Their build fails if the latest release has no alias, so a release cannot drop out of the bundles. Renovate raises @finos/calm-schema updates in their own PR, without automerge, and never updates the aliases. A schema update PR must add the new alias.

3. Add a schema compatibility workflow.
   Needs: step 2. The dispatch trigger also needs P2. @rocketstack-matt must confirm that P2 is in place before that part can be completed. The other triggers do not need P2, so the workflow can merge without it.

   • Triggers: a repository_dispatch from the calm-schema publish workflow after npm publish, a daily check of the npm latest tag as a fallback, and a manual run.
   • Runs the build and tests of every tool against the new version, one job per tool, without fail-fast. This includes ./mvnw verify for calm-hub.
   • If a job fails, it opens one issue for that version (or updates it), with a list of the tools that fail and links to their logs.
   • If all jobs pass, the Renovate PR changes the pinned version.

   npm does not send events to GitHub, so the trigger cannot come from npm directly. The calm-schema GITHUB_TOKEN cannot call another repo, so the dispatch needs the P2 app.

4. Make the CLI workspace templates use 1.2, and then the latest release from npm.
   Needs: P3. @willosborne, can you confirm this?

5. Move the deployment decorator standard to calm-schema and release it.
   Needs: step 1 (and so P1), because the calm-schema workflow publishes it.
   Move calm/draft/2026-03/standards/ (the deployment and Kubernetes decorator standards and their examples) to calm-schema, and promote it to a release through the calm-schema release process. Publish it under release/<v>/ (see the ordering rules). Then change the calm-hub seed data and the calm-hub-ui tests to the release URL.

6. Delete the drafts and release candidates.
   Needs: steps 2, 4 and 5, so that no tool, template or standard uses the drafts. The bucket deletion of the RCs also needs P1. Before the bucket deletion, the CLI smoke fixture cli/smoke/fixtures/genval/conference-signup.pattern.json must stop using the live release/1.0-rc* URLs, because cli-hub-smoke.yml validates it against calm.finos.org.

   • Delete calm/draft and calm/release/1.0-rc*, and remove every reference to them in the tools: the CLI, calm-server and calm-lab bundles, the calm-hub seed data, the tests and fixtures, and the docs.
   • Remove the draft/* exclude from s3-docs-sync.yml, so that the next docs deploy deletes draft/ from the bucket. Delete release/1.0-rc1/ and release/1.0-rc2/ with the calm-schema credentials.
   • Documents that use these URLs as $schema will not resolve after this, so the release notes must say so.

7. Delete calm/controls.
   Needs: step 1 for the bucket part.
   It contains only a README, and nothing uses it. Remove the controls/* exclude from s3-docs-sync.yml, so that the next docs deploy deletes controls/. docs/docs/core-concepts/controls.md and docs/docs/tutorials/_calm-overview/03-governance.mdx show calm.finos.org/controls/... URLs that already return 404. Correct these examples.

8. Delete calm/getting-started.
   Needs: step 1 for the bucket part. Before the getting-started/* exclude is removed, the CLI smoke fixture cli/smoke/fixtures/genval/conference-signup.pattern.json must stop using the live getting-started/controls/* URLs.
   It is a "Get Started in 5 Minutes" guide that builds the repo from source and uses a 1.0-rc2 pattern. The beginner tutorials on the docs site and CALM Lab now cover the same steps. Move the files that the CLI e2e test reads into cli/test_fixtures/getting-started, and update docs/flow-template.md and the calm-studio controls doc that refer to it. Remove the getting-started/* exclude from s3-docs-sync.yml, so that the next docs deploy deletes getting-started/.

9. Remove calm/release and calm/interfaces here.
   Needs: steps 1 and 2, so that calm-schema serves them and no tool here reads them.
   Keep calm/architecture. It is the architecture of the CALM tools, the Spectral workflow lints it, and the CLI docs use it in an example.

10. Add AGENTS.md and CLAUDE.md to calm-schema and calm-governance.
    Needs: nothing.
    Each AGENTS.md says what the repo owns, which repo owns what across the project, the expected layout (the three repos cloned side by side), and how to work across repos: start the agent in architecture-as-code, add the other two repos as additional directories, and target commands at the correct repo (git -C ../<repo>, gh ... --repo finos/<repo>). CLAUDE.md contains only @AGENTS.md, as in this repo.

11. Update this repo's AGENTS.md and README.
    Needs: nothing. Remove calm/AGENTS.md and calm/README.md with step 9.
    Send schema work to calm-schema and governance work to calm-governance, refer to the new AGENTS.md files, and add the same multi-repo section.

12. Correct the calm-schema docs.
    Needs: nothing.
    examples/interfaces/README.md calls the folder "the official repository of standardized CALM interface definitions", says that it is "automatically published to the hosted CALM Hub", and shows a calm-hub.finos.org reference that does not exist. examples/interfaces/example/README.md says that only architecture-as-code may refer to these files.

Alternatives Considered:

Testing Strategy:

• In step 1, compare every release/ and interfaces/ URL on calm.finos.org with its content before the change. They must be identical.
• After step 2, all test suites and ./mvnw verify for calm-hub must pass with the npm packages.
• After step 6, a search for draft/ and 1.0-rc outside the CHANGELOGs finds no references, except the items that Remove the 2026-03 draft after early adopters finish their migration #3533, Remove draft/2025-03 from calm.finos.org after OpenRewrite declares a CALM release #3507 and Remove the CALM 1.0 release candidates from calm.finos.org #3514 track.
• Run the step 3 workflow manually against 1.2.0 (it must pass and must not open an issue), and against a version that breaks a tool (it must open one issue that names that tool).

Documentation Requirements:

Steps 10–12, the docs examples in step 7, and any docs site page that tells contributors to edit calm/. The calm-schema README must say that a release starts the compatibility workflow here.

Implementation Checklist:

• Design reviewed and approved
• Implementation completed
• Tests written and passing
• Documentation updated
• Relevant workflows updated (if needed)
• Performance impact assessed

Additional Context:

• History migration: Migrate 2025-03 draft + 1.0-rc1 schema history [MERGE COMMIT ONLY] calm-schema#12, Refactor nodes and relationships #14, Major refactor - migrating CALM to a specific JSON vocabulary #15, TLS, mTLS and TCP should be added to the Protocol Enum #16, Add Certificate to the Authentication Enum #18 (releases) and Spectral validation PoC #28 (interfaces).
• On 2026-10-04, the meta files at each calm-schema tag were compared with calm/release/<v>/meta here. They are identical.