CALM CLI Contract Specification

Version: 1.0.0
Status: Finalized
Context: architectural-governance
Satisfies: SDS-039, PRD-004, PRD-005

Overview

This document defines the contract specification for the CALM CLI Service, establishing the commands, inputs, outputs, and exit codes that constitute the stable interface for architectural validation and visualization.

Commands

1. calm validate

Purpose: Validate architecture definition against CALM schema and controls.

Syntax:

1

calm validate <path> [--format json|text] [--verbose]

Inputs:

Outputs:

Success (exit code 0):

1
2
3
4
5
6
7
8

{
  "status": "valid",
  "nodesValidated": 12,
  "relationshipsValidated": 18,
  "controlsCompliant": 15,
  "controlsNonCompliant": 0,
  "warnings": []
}

Failure (exit code 1):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "status": "invalid",
  "errors": [
    {
      "code": "SCHEMA_VIOLATION",
      "node": "customer-db",
      "message": "Missing required field: security.encryption"
    }
  ],
  "warnings": [
    {
      "code": "DEPRECATED_FIELD",
      "node": "order-service",
      "message": "Field 'version' is deprecated, use 'semver'"
    }
  ]
}

Exit Codes:

2. calm visualize

Purpose: Generate visual diagrams from CALM architecture definitions.

Syntax:

1

calm visualize <path> --output <file> [--format png|svg|puml] [--style c4|simple|detailed]

Inputs:

Outputs:

1
2
3
4
5
6
7

{
  "status": "success",
  "output": "architecture.png",
  "format": "png",
  "nodesRendered": 12,
  "edgesRendered": 18
}

Exit Codes:

3. calm compliance

Purpose: Report compliance status against architectural controls.

Syntax:

1

calm compliance <path> [--fail-on-non-compliant] [--format json|text]

Inputs:

Outputs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "compliant": 15,
  "nonCompliant": 2,
  "waived": 1,
  "controls": [
    {
      "id": "data-encryption-at-rest",
      "status": "compliant",
      "node": "customer-db"
    },
    {
      "id": "api-rate-limiting",
      "status": "non-compliant",
      "node": "order-to-payment",
      "message": "No rate limiting configuration found"
    },
    {
      "id": "pii-masking",
      "status": "waived",
      "node": "analytics-service",
      "waiver": {
        "id": "W-2025-001",
        "approvedBy": "platform-lead",
        "validUntil": "2025-12-31T23:59:59Z",
        "rationale": "Analytics requires unmasked data for training"
      }
    }
  ]
}

Exit Codes:

Data Formats

Input: CALM Architecture File

File Extension: .calm.json

Schema: FINOS CALM 2.0 specification

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "calm-version": "2.0",
  "nodes": [
    {
      "id": "order-service",
      "type": "service",
      "name": "Order Service",
      "description": "Handles order processing",
      "security": {
        "authentication": "oauth2",
        "authorization": "rbac"
      },
      "controls": {
        "data-encryption-at-rest": "enabled",
        "api-rate-limiting": "1000/min"
      }
    }
  ],
  "relationships": [
    {
      "id": "order-to-payment",
      "source": "order-service",
      "target": "payment-gateway",
      "type": "http",
      "protocol": "https"
    }
  ]
}

Output: Validation Report Schema

JSON Schema:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["status", "nodesValidated", "relationshipsValidated"],
  "properties": {
    "status": {
      "type": "string",
      "enum": ["valid", "invalid"]
    },
    "nodesValidated": {
      "type": "integer",
      "minimum": 0
    },
    "relationshipsValidated": {
      "type": "integer",
      "minimum": 0
    },
    "controlsCompliant": {
      "type": "integer",
      "minimum": 0
    },
    "controlsNonCompliant": {
      "type": "integer",
      "minimum": 0
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": {
            "type": "string"
          },
          "node": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": {
            "type": "string"
          },
          "node": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

Error Codes

Code Description Resolution
SCHEMA_VIOLATION Input file violates CALM schema Fix JSON structure per CALM 2.0 spec
MISSING_CONTROL Required control not defined Add control configuration to node
INVALID_CONTROL_VALUE Control value format incorrect Check control value against allowed types
DEPRECATED_FIELD Field is deprecated Migrate to recommended field
MISSING_DEPENDENCY External tool not found (PlantUML/Graphviz) Install required dependencies
FILE_NOT_FOUND Input file does not exist Check path
INVALID_FORMAT Unknown output format Use png, svg, or puml

CI/CD Integration Contract

GitHub Actions Example:

1
2
3
4
5
6
7

- name: Validate Architecture
  run: |
    calm validate architecture/*.calm.json --fail-on-non-compliant
    if [ $? -ne 0 ]; then
      echo "❌ Architecture validation failed"
      exit 1
    fi

Exit Code Contract:

Versioning

CLI Version: 1.0.0
CALM Spec Compatibility: 2.0+

Semver Guarantee:

Dependencies Contract

Required:

Optional (for visualization):

Installation:

1

npm install -g @finos/calm-cli

Testing Contract

Unit Tests:

Integration Tests:

Contract Validation: