|
| 1 | +# CALM Moment Creation Guide |
| 2 | + |
| 3 | +## Critical Requirements |
| 4 | + |
| 5 | +⚠️ **ALWAYS call the moment creation tool before creating any moment** |
| 6 | +⚠️ **ALWAYS call the control creation tool before adding controls to a moment** |
| 7 | + |
| 8 | +## What Are Moments? |
| 9 | + |
| 10 | +Moments represent the "major stages" an architecture progresses through over time. A moment represents a single point in time, and the architecture at that moment. They provide several key capabilities: |
| 11 | + |
| 12 | +- **Time-Based Modeling**: Capture how an architecture evolves over time, including changes to nodes, interfaces, and controls. |
| 13 | +- |
| 14 | +- **Non-Functional Requirements**: Controls can be added to moments to specify non-functional requirements such as security policies, compliance controls, and operational constraints governing the change to an architecture. |
| 15 | + |
| 16 | +- **Architecture Decision Records**: Moments can have one or more architecture decision records (ADRs) associated with them, documenting key decisions made to reach that moment. |
| 17 | + |
| 18 | +## Official JSON Schema Definition |
| 19 | + |
| 20 | +The complete moment schema from the FINOS CALM v1.1 specification: |
| 21 | + |
| 22 | +```json |
| 23 | +{ |
| 24 | + "node-moment": { |
| 25 | + "required": [ |
| 26 | + "details" |
| 27 | + ], |
| 28 | + "properties": { |
| 29 | + "node-type": { |
| 30 | + "const": "moment" |
| 31 | + }, |
| 32 | + "valid-from": { |
| 33 | + "type": "string", |
| 34 | + "format": "date", |
| 35 | + "description": "The date when this architecture moment came into effect." |
| 36 | + }, |
| 37 | + "adrs": { |
| 38 | + "type": "array", |
| 39 | + "items": { |
| 40 | + "type": "string" |
| 41 | + }, |
| 42 | + "description": "External links to ADRs (Architecture Decision Records) or similar documents that provide context or decisions related to why the architecture changed." |
| 43 | + }, |
| 44 | + "interfaces": false |
| 45 | + } |
| 46 | + }, |
| 47 | + "node": { |
| 48 | + "type": "object", |
| 49 | + "properties": { |
| 50 | + "unique-id": { |
| 51 | + "type": "string" |
| 52 | + }, |
| 53 | + "node-type": { |
| 54 | + "$ref": "#/defs/node-type-definition" |
| 55 | + }, |
| 56 | + "name": { |
| 57 | + "type": "string" |
| 58 | + }, |
| 59 | + "description": { |
| 60 | + "type": "string" |
| 61 | + }, |
| 62 | + "details": { |
| 63 | + "type": "object", |
| 64 | + "properties": { |
| 65 | + "detailed-architecture": { |
| 66 | + "type": "string" |
| 67 | + }, |
| 68 | + "required-pattern": { |
| 69 | + "type": "string" |
| 70 | + } |
| 71 | + }, |
| 72 | + "additionalProperties": false |
| 73 | + }, |
| 74 | + "interfaces": { |
| 75 | + "type": "array", |
| 76 | + "items": { |
| 77 | + "anyOf": [ |
| 78 | + { "$ref": "interface.json#/defs/interface-definition" }, |
| 79 | + { "$ref": "interface.json#/defs/interface-type" } |
| 80 | + ] |
| 81 | + } |
| 82 | + }, |
| 83 | + "controls": { |
| 84 | + "$ref": "control.json#/defs/controls" |
| 85 | + }, |
| 86 | + "metadata": { |
| 87 | + "$ref": "#/defs/metadata" |
| 88 | + } |
| 89 | + }, |
| 90 | + "required": ["unique-id", "node-type", "name", "description"], |
| 91 | + "additionalProperties": true |
| 92 | + }, |
| 93 | + "node-type-definition": { |
| 94 | + "anyOf": [ |
| 95 | + { |
| 96 | + "enum": [ |
| 97 | + "actor", |
| 98 | + "ecosystem", |
| 99 | + "system", |
| 100 | + "service", |
| 101 | + "database", |
| 102 | + "network", |
| 103 | + "ldap", |
| 104 | + "webclient", |
| 105 | + "data-asset" |
| 106 | + ] |
| 107 | + }, |
| 108 | + { |
| 109 | + "type": "string" |
| 110 | + } |
| 111 | + ] |
| 112 | + }, |
| 113 | + "metadata": { |
| 114 | + "oneOf": [ |
| 115 | + { |
| 116 | + "type": "array", |
| 117 | + "items": { |
| 118 | + "type": "object" |
| 119 | + } |
| 120 | + }, |
| 121 | + { |
| 122 | + "type": "object", |
| 123 | + "additionalProperties": true |
| 124 | + } |
| 125 | + ] |
| 126 | + } |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +## Required Properties |
| 131 | + |
| 132 | +Every moment MUST conform to both the `node` and `node-moment` schemas. |
| 133 | + |
| 134 | +Every moment MUST have: |
| 135 | + |
| 136 | +- `unique-id` (string) |
| 137 | +- `node-type` (the constant value `moment`) |
| 138 | +- `name` (string) |
| 139 | +- `description` (string) |
| 140 | +- `details` - MUST be present. Object with `detailed-architecture` or `required-pattern` properties |
| 141 | + |
| 142 | +## Optional Properties |
| 143 | + |
| 144 | +- `valid-from` - Date string (YYYY-MM-DD) indicating when this moment came into effect. It is ONLY permitted on past or current moments. |
| 145 | +- `interfaces` - is NOT permitted on a moment |
| 146 | +- `controls` - Compliance controls (see control creation tool) |
| 147 | +- `metadata` - Additional information (see metadata creation tool for details) |
| 148 | + |
| 149 | +## Details Property Structure |
| 150 | + |
| 151 | +The `details` property follows this exact schema: |
| 152 | + |
| 153 | +```json |
| 154 | +{ |
| 155 | + "details": { |
| 156 | + "type": "object", |
| 157 | + "properties": { |
| 158 | + "detailed-architecture": { |
| 159 | + "type": "string" |
| 160 | + }, |
| 161 | + "required-pattern": { |
| 162 | + "type": "string" |
| 163 | + } |
| 164 | + }, |
| 165 | + "additionalProperties": false |
| 166 | + } |
| 167 | +} |
| 168 | +``` |
| 169 | + |
| 170 | +**Important**: |
| 171 | + |
| 172 | +- The details object allows NO additional properties beyond `detailed-architecture` and `required-pattern` |
| 173 | +- `detailed-architecture`: Fully qualified address/URL to a detailed architecture document (use `.architecture.json` suffix) |
| 174 | +- `required-pattern`: Fully qualified address/URL to a required pattern document (use `.pattern.json` suffix) |
| 175 | + |
| 176 | +## Metadata Schema Rules |
| 177 | + |
| 178 | +Critical: Metadata can be either an array OR an object (see metadata creation tool for complete guidance): |
| 179 | + |
| 180 | +```json |
| 181 | +{ |
| 182 | + "metadata": { |
| 183 | + "oneOf": [ |
| 184 | + { |
| 185 | + "type": "array", |
| 186 | + "items": { |
| 187 | + "type": "object" |
| 188 | + } |
| 189 | + }, |
| 190 | + { |
| 191 | + "type": "object", |
| 192 | + "additionalProperties": true |
| 193 | + } |
| 194 | + ] |
| 195 | + } |
| 196 | +} |
| 197 | +``` |
| 198 | + |
| 199 | +## Example Moment |
| 200 | + |
| 201 | +```json |
| 202 | +{ |
| 203 | + "unique-id": "trading-api-stage-1", |
| 204 | + "node-type": "moment", |
| 205 | + "name": "Trading API Service Initial Release", |
| 206 | + "description": "First design of trading API", |
| 207 | + "details": { |
| 208 | + "detailed-architecture": "https://calm.company.com/architectures/trading-api-v1.architecture.json" |
| 209 | + }, |
| 210 | + "metadata": [ |
| 211 | + { |
| 212 | + "version": "2.1.0", |
| 213 | + "owner": "Trading Team", |
| 214 | + "runtime": "Java 17" |
| 215 | + } |
| 216 | + ] |
| 217 | +} |
| 218 | +``` |
| 219 | + |
| 220 | +## Schema Validation Rules |
| 221 | + |
| 222 | +1. **Required Properties**: Must include `unique-id`, `node-type`, `name`, `description`, `details`. |
| 223 | +2. **Node Type**: Must be `moment` |
| 224 | +3. **Details Object**: Only allows `detailed-architecture` and `required-pattern` properties |
| 225 | +4. **Metadata**: Can be array of objects OR single object (see metadata creation tool) |
| 226 | +5. **Additional Properties**: Schema allows additional properties at node level (`"additionalProperties": true`) |
| 227 | + |
| 228 | +## Key Reminders |
| 229 | + |
| 230 | +- Always use the moment creation tool before creating moments |
| 231 | +- Reference the metadata creation tool for metadata structure guidance |
| 232 | +- The schema is authoritative - follow it exactly |
| 233 | +- Node unique-ids must be unique across the entire timeline |
0 commit comments