Skip to content

Commit 8d016b5

Browse files
harveymmaundersharveymmaunders
committed
docs(calm-ai) remove doc changes
Ref #1908
1 parent 1a1ca1e commit 8d016b5

File tree

2 files changed

+74
-59
lines changed

2 files changed

+74
-59
lines changed

‎calm-ai/tools/decorator-creation.md‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -157,18 +157,17 @@ Other deployment targets (e.g. AWS ECS, Azure Container Apps) follow the same pa
157157

158158
```json
159159
{
160-
"$schema": "https://calm.finos.org/standards/deployment/deployment.decorator.schema.json",
160+
"$schema": "https://calm.finos.org/release/1.2/meta/decorators.json#/defs/decorator",
161161
"unique-id": "aks-cluster-deployment-001",
162162
"type": "deployment",
163163
"target": ["aks-architecture.json"],
164164
"applies-to": ["aks-cluster"],
165165
"data": {
166-
"start-time": "2026-02-12T09:30:00Z",
167-
"end-time": "2026-02-12T09:38:00Z",
168-
"status": "completed",
169-
"environment": "production",
170-
"observability": "https://grafana.example.com/d/aks-prod/aks-cluster-overview",
171-
"notes": "Routine upgrade to latest platform version"
166+
"deployment-start-time": "2026-02-12T09:30:00Z",
167+
"deployment-status": "completed",
168+
"deployment-observability": "https://grafana.example.com/d/aks-prod/aks-cluster-overview",
169+
"cluster": "prod-uksouth-aks-01",
170+
"namespace": "trading-system"
172171
}
173172
}
174173
```
@@ -323,4 +322,4 @@ Use **custom decorator schemas** when:
323322
- The information is managed by a different team than the architecture owners
324323
- The data changes independently of the architecture (e.g. deployment status)
325324
- You need to annotate elements across multiple architecture files
326-
- The supplementary data should not clutter the core architecture definition
325+
- The supplementary data should not clutter the core architecture definition

‎docs/docs/core-concepts/decorators.md‎

Lines changed: 67 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -85,14 +85,14 @@ This creates a composable schema inheritance chain where each layer owns its own
8585

8686
To illustrate how the base decorator schema can be extended, consider deployment decorators that track when and how architecture components are deployed, including status, timing, and observability links.
8787

88-
### Example: Deployment Decorator Standard
88+
### Example: Deployment Decorator Schema
8989

90-
A deployment decorator standard constrains `type` to `"deployment"` and defines deployment-specific attributes in `data`:
90+
A deployment decorator schema could constrain `type` to `"deployment"` and define deployment-specific attributes in `data`:
9191

9292
```json
9393
{
9494
"$schema": "https://json-schema.org/draft/2020-12/schema",
95-
"$id": "https://calm.finos.org/standards/deployment/deployment.decorator.schema.json",
95+
"$id": "https://calm.finos.org/release/1.2/meta/deployment.decorator.schema.json",
9696
"title": "CALM Deployment Decorator Schema",
9797
"allOf": [
9898
{
@@ -105,33 +105,23 @@ A deployment decorator standard constrains `type` to `"deployment"` and defines
105105
"data": {
106106
"type": "object",
107107
"properties": {
108-
"start-time": {
108+
"deployment-start-time": {
109109
"type": "string",
110110
"format": "date-time"
111111
},
112-
"end-time": {
113-
"type": "string",
114-
"format": "date-time"
115-
},
116-
"status": {
112+
"deployment-status": {
117113
"type": "string",
118114
"enum": [
119-
"pending", "in-progress", "completed",
120-
"failed", "rolled-back"
115+
"in-progress", "failed", "completed",
116+
"rolled-back", "pending"
121117
]
122118
},
123-
"environment": {
124-
"type": "string"
125-
},
126-
"observability": {
119+
"deployment-observability": {
127120
"type": "string",
128121
"format": "uri"
129-
},
130-
"notes": {
131-
"type": "string"
132122
}
133123
},
134-
"required": ["start-time", "status"],
124+
"required": ["deployment-start-time", "deployment-status"],
135125
"additionalProperties": true
136126
}
137127
},
@@ -143,43 +133,72 @@ A deployment decorator standard constrains `type` to `"deployment"` and defines
143133

144134
| Property | Type | Required | Description |
145135
|---|---|---|---|
146-
| `start-time` | string (date-time) | Yes | ISO 8601 timestamp of when the deployment started |
147-
| `status` | string (enum) | Yes | Current status: `pending`, `in-progress`, `completed`, `failed`, `rolled-back` |
148-
| `end-time` | string (date-time) | No | ISO 8601 timestamp of when the deployment completed or failed |
149-
| `environment` | string | No | Target environment (e.g., production, staging, development) |
150-
| `observability` | string (uri) | No | Link to logs, metrics, or observability dashboards |
151-
| `notes` | string | No | Free-form notes or comments about the deployment |
136+
| `deployment-start-time` | string (date-time) | Yes | ISO 8601 timestamp of when the deployment started |
137+
| `deployment-status` | string (enum) | Yes | Current status: `in-progress`, `failed`, `completed`, `rolled-back`, `pending` |
138+
| `deployment-observability` | string (uri) | No | Link to logs, metrics, or observability dashboards |
152139

153140
The `data` object uses `additionalProperties: true` so that extension schemas can add domain-specific sub-objects.
154141

155142
## Example: Kubernetes Deployment Decorators
156143

157-
Taking the extension pattern further, a Kubernetes-specific decorator can add a `kubernetes` sub-object inside `data` with cluster-specific attributes. The Kubernetes properties are nested to avoid conflicts with the base deployment properties.
158-
159-
### Kubernetes-Specific Properties
144+
Taking the extension pattern further, a Kubernetes-specific decorator could add a `kubernetes` sub-object inside `data` with cluster-specific attributes. The Kubernetes properties are nested to avoid conflicts with the base deployment properties and to allow each schema layer to lock down its own scope.
160145

161-
When deploying to Kubernetes, add platform-specific details in a `kubernetes` sub-object:
146+
### Kubernetes Decorator Schema
162147

163-
| Property | Type | Description |
164-
|---|---|---|
165-
| `kubernetes.helm-chart` | string | Helm chart name and semver version (e.g. `my-app:1.2.3`) |
166-
| `kubernetes.cluster` | string | Kubernetes cluster identifier |
167-
| `kubernetes.namespace` | string | Kubernetes namespace for the deployment |
168-
| `kubernetes.workload-type` | string | Type of workload (e.g. `Deployment`, `StatefulSet`) |
169-
| `kubernetes.replicas` | number | Number of replicas deployed |
148+
```json
149+
{
150+
"$schema": "https://json-schema.org/draft/2020-12/schema",
151+
"$id": "https://calm.finos.org/release/1.2/meta/kubernetes.decorator.schema.json",
152+
"title": "CALM Kubernetes Deployment Decorator Schema",
153+
"allOf": [
154+
{
155+
"$ref": "https://calm.finos.org/release/1.2/meta/deployment.decorator.schema.json"
156+
},
157+
{
158+
"type": "object",
159+
"properties": {
160+
"data": {
161+
"type": "object",
162+
"properties": {
163+
"kubernetes": {
164+
"type": "object",
165+
"properties": {
166+
"helm-chart": {
167+
"type": "string",
168+
"pattern": "^[a-z0-9-]+:[0-9]+\\.[0-9]+\\.[0-9]+$"
169+
},
170+
"cluster": { "type": "string" },
171+
"namespace": { "type": "string" }
172+
},
173+
"required": ["helm-chart", "cluster"],
174+
"additionalProperties": false
175+
}
176+
},
177+
"required": ["kubernetes"]
178+
}
179+
}
180+
}
181+
]
182+
}
183+
```
170184

171-
The deployment decorator standard allows `additionalProperties: true` in the `data` object, so platform-specific sub-objects like `kubernetes`, `aws-ecs`, or `azure` can be added without modifying the base standard.
185+
| Property | Type | Required | Description |
186+
|---|---|---|---|
187+
| `kubernetes.helm-chart` | string (pattern) | Yes | Helm chart name and semver version (e.g. `my-app:1.2.3`) |
188+
| `kubernetes.cluster` | string | Yes | Kubernetes cluster identifier |
189+
| `kubernetes.namespace` | string | No | Kubernetes namespace for the deployment |
172190

173-
## Standard Inheritance
191+
## Schema Inheritance
174192

175-
The deployment decorator standard demonstrates how standards build upon the base decorator schema:
193+
The examples above demonstrate how the schema inheritance chain allows each layer to define its own properties while composing cleanly:
176194

177195
```
178-
decorators.json (base: unique-id, type, target, applies-to, data)
179-
└── deployment.decorator.schema.json (type="deployment", deployment-specific properties)
196+
decorators.json (base: unique-id, type, applies-to, data)
197+
└── deployment decorator (type="deployment", deployment attributes in data)
198+
└── kubernetes decorator (kubernetes sub-object in data)
180199
```
181200

182-
The deployment standard constrains `type` to `"deployment"` and defines the structure of the `data` field with standard deployment properties (`start-time`, `status`, etc.). Organizations can add platform-specific sub-objects within `data` (like `kubernetes`, `aws-ecs`, or `azure`) to capture deployment details specific to their infrastructure.
201+
Other deployment targets (e.g. AWS ECS, Azure Container Apps) could follow the same pattern — extend a deployment decorator schema and add their own sub-object inside `data`.
183202

184203
## Worked Example
185204

@@ -204,18 +223,15 @@ A Kubernetes deployment decorator for this node could look like:
204223

205224
```json
206225
{
207-
"$schema": "https://calm.finos.org/standards/deployment/deployment.decorator.schema.json",
226+
"$schema": "https://calm.finos.org/release/1.2/meta/kubernetes.decorator.schema.json",
208227
"unique-id": "aks-cluster-deployment-001",
209228
"type": "deployment",
210229
"target": ["aks-architecture.json"],
211230
"applies-to": ["aks-cluster"],
212231
"data": {
213-
"start-time": "2026-02-12T09:30:00Z",
214-
"end-time": "2026-02-12T09:38:00Z",
215-
"status": "completed",
216-
"environment": "production",
217-
"observability": "https://grafana.example.com/d/aks-prod/aks-cluster-overview",
218-
"notes": "Routine upgrade to latest platform version",
232+
"deployment-start-time": "2026-02-12T09:30:00Z",
233+
"deployment-status": "completed",
234+
"deployment-observability": "https://grafana.example.com/d/aks-prod/aks-cluster-overview",
219235
"kubernetes": {
220236
"helm-chart": "aks-platform:3.2.1",
221237
"cluster": "prod-uksouth-aks-01",
@@ -229,5 +245,5 @@ This decorator:
229245
- Targets the architecture document `aks-architecture.json` via `target`
230246
- References the `aks-cluster` node within that architecture via `applies-to`
231247
- Satisfies the base decorator schema (has `unique-id`, `type`, `target`, `applies-to`, `data`)
232-
- Satisfies the deployment standard (`start-time`, `status` are present, with optional fields `end-time`, `environment`, `observability`, `notes`)
233-
- Includes platform-specific Kubernetes details in the `kubernetes` sub-object (helm chart, cluster, namespace)
248+
- Satisfies the deployment schema (`deployment-start-time`, `deployment-status` are present)
249+
- Satisfies the Kubernetes schema (`helm-chart`, `cluster` are present inside the `kubernetes` sub-object)

0 commit comments

Comments
 (0)