# Blueprint Catalog CALM Standard

CALM (the Common Architecture Language Model, a FINOS specification) describes a system's architecture as a JSON
document. It names business flows and capabilities only in free text. This Standard lets any CALM node,
relationship, flow or whole architecture name what it supports in the Blueprint Catalog, using the catalog's stable
ids, so a system model can be read against a shared business model.

- Standard: `/calm/v1/blueprint-catalog.standard.json` (JSON Schema 2020-12, composes with CALM release 1.2)
- Example: `/calm/v1/examples/online-store-checkout.architecture.json` (fictional)
- Index: `/calm/index.json`

## How to tag an element

Add a `blueprint-catalog` entry to the element's `metadata` (CALM 1.2 allows `metadata` on nodes, relationships,
flows and the architecture; flows accept no other extra properties, so `metadata` is the one place that works
everywhere):

```json
"metadata": [
  { "blueprint-catalog": {
      "catalog-release": "0.31.0",
      "business-capability-ids": ["BC-670.10"],
      "value-stream-stage-ids": ["VS-120.10"],
      "data-concept-ids": ["DC-110"] } }
]
```

Every field is optional, but at least one must be present. `catalog-release` records the catalog version the ids
came from: when an id is retired, `/api/v1/capability/<id>.json` names its successor.

## How to require tags in a pattern

Compose the Standard's definitions with CALM's in a pattern or architecture: `$defs/node`, `$defs/relationship` and
`$defs/flow` each take the CALM 1.2 definition and require a valid `blueprint-catalog` entry, for example
`{ "$ref": "https://catalog.mikereams.com/calm/v1/blueprint-catalog.standard.json#/$defs/flow" }`.

## Checking the ids

The Standard checks each id's shape. To check that an id exists, look it up in the catalog API
(`/api/v1/capability/<id>.json`, `/api/v1/value-stream/<VS-id>.json`, `/api/v1/data-concepts.json`) or with the
catalog's MCP tool `catalog_search`.

## Versioning and license

Version 1 only ever gains optional fields; a breaking change would be published as `/calm/v2/`. The Standard and
example are CC BY 4.0 Mike Reams. CALM is an Apache-2.0 specification of FINOS; this catalog is not affiliated with
or endorsed by FINOS.