0
# Validate Command
1
2
> **NOTE**: This is a CLI-only command. @finos/calm-cli does not export functions for programmatic use.
3
4
The `validate` command verifies that a CALM architecture conforms to a given pattern or schema. It performs comprehensive validation including JSON schema validation and Spectral-based linting, providing detailed error and warning reports in multiple output formats.
5
6
## Capabilities
7
8
### Validate Command
9
10
Validates a CALM architecture against a pattern with detailed error and warning reporting.
11
12
```typescript { .api }
13
/**
14
* Validate that an architecture conforms to a given CALM pattern
15
* @command calm validate [options]
16
*/
17
interface ValidateCommandOptions {
18
/** Path to pattern file (file path or URL)
19
* CLI flags: -p, --pattern <file>
20
*/
21
pattern?: string;
22
23
/** Path to architecture file (file path or URL)
24
* CLI flags: -a, --architecture <file>
25
*/
26
architecture?: string;
27
28
/** Path to directory containing meta schemas
29
* CLI flags: -s, --schema-directory <path>
30
* Default: CALM_META_SCHEMA_DIRECTORY
31
*/
32
schemaDirectory?: string;
33
34
/** Fail if warnings are reported
35
* CLI flags: --strict
36
* Default: false
37
*/
38
strict?: boolean;
39
40
/** Output format: 'json', 'junit', or 'pretty'
41
* CLI flags: -f, --format <format>
42
* Default: 'json'
43
*/
44
format?: 'json' | 'junit' | 'pretty';
45
46
/** Output file path (stdout if not specified)
47
* CLI flags: -o, --output <file>
48
*/
49
output?: string;
50
51
/** Enable verbose logging
52
* CLI flags: -v, --verbose
53
* Default: false
54
*/
55
verbose?: boolean;
56
}
57
```
58
59
**Requirements:**
60
- At least one of `pattern` or `architecture` must be specified
61
- If only `architecture` is provided, pattern is loaded from the architecture's `$schema` field
62
63
**Usage Examples:**
64
65
```bash
66
# Validate with both architecture and pattern
67
calm validate -a architecture.json -p pattern.json
68
69
# Validate with JSON output to file
70
calm validate -a architecture.json -p pattern.json -f json -o results.json
71
72
# Validate in strict mode (fail on warnings)
73
calm validate -a architecture.json -p pattern.json --strict
74
75
# Validate with JUnit output format (for CI/CD)
76
calm validate -a architecture.json -p pattern.json -f junit -o results.xml
77
78
# Validate with pretty-printed output
79
calm validate -a architecture.json -p pattern.json -f pretty
80
81
# Validate architecture against its embedded schema
82
calm validate -a architecture.json
83
84
# Use custom schema directory
85
calm validate -a architecture.json -p pattern.json -s ./custom-schemas
86
87
# Enable verbose logging
88
calm validate -a architecture.json -p pattern.json -v
89
```
90
91
## Output Formats
92
93
### JSON Format (Default)
94
95
Structured JSON output containing validation results:
96
97
```json
98
{
99
"jsonSchemaValidationOutputs": [],
100
"spectralSchemaValidationOutputs": [
101
{
102
"code": "architecture-has-no-placeholder-properties-string",
103
"severity": "warning",
104
"message": "String placeholder detected in architecture.",
105
"path": "/nodes/0/interfaces/0/host",
106
"schemaPath": "",
107
"line_start": 10,
108
"line_end": 10,
109
"character_start": 18,
110
"character_end": 30
111
}
112
],
113
"hasErrors": false,
114
"hasWarnings": true
115
}
116
```
117
118
### JUnit Format
119
120
XML format compatible with CI/CD systems like Jenkins:
121
122
```xml
123
<?xml version="1.0" encoding="UTF-8"?>
124
<testsuites>
125
<testsuite name="CALM Validation" tests="1" failures="0">
126
<testcase name="architecture.json" />
127
</testsuite>
128
</testsuites>
129
```
130
131
### Pretty Format
132
133
Human-readable formatted output for terminal display:
134
135
```
136
✓ No errors found
137
⚠ 2 warnings found:
138
- String placeholder detected at /nodes/0/interfaces/0/host
139
- Numerical placeholder detected at /nodes/0/interfaces/0/port
140
```
141
142
## Validation Modes
143
144
### Standard Mode (Default)
145
146
- Reports both errors and warnings
147
- Exit code 0 if no errors, 1 if errors present
148
- Warnings do not affect exit code
149
150
### Strict Mode
151
152
Enabled with `--strict` flag:
153
154
- Reports both errors and warnings
155
- Exit code 1 if either errors or warnings are present
156
- Useful for enforcing zero-warning policies in CI/CD
157
158
## Validation Types
159
160
### JSON Schema Validation
161
162
Validates architecture structure against JSON schemas:
163
164
- Checks required fields are present
165
- Validates data types (strings, numbers, arrays, objects)
166
- Enforces schema constraints (min/max, patterns, enums)
167
- Validates references and IDs
168
169
### Spectral Validation
170
171
Applies additional linting rules using Spectral:
172
173
- Detects placeholder values (strings like "PLACEHOLDER", numbers like -1)
174
- Validates architectural patterns and conventions
175
- Checks naming conventions
176
- Enforces best practices
177
178
## Loading Patterns and Architectures
179
180
### From Local Files
181
182
```bash
183
calm validate -a ./path/to/architecture.json -p ./path/to/pattern.json
184
```
185
186
### From URLs
187
188
```bash
189
calm validate \
190
-a https://example.com/architectures/my-arch.json \
191
-p https://example.com/patterns/api-gateway.json
192
```
193
194
### From Architecture $schema Field
195
196
If architecture includes a `$schema` field pointing to a pattern:
197
198
```json
199
{
200
"$schema": "https://calm.finos.org/patterns/api-gateway.json",
201
"nodes": [...]
202
}
203
```
204
205
You can validate without specifying pattern:
206
207
```bash
208
calm validate -a architecture.json
209
```
210
211
The CLI will automatically load the pattern from the `$schema` URL.
212
213
## Configuration
214
215
### CALMHub Integration
216
217
The validate command supports loading patterns and architectures from a CALMHub instance using the user configuration file:
218
219
**Via User Configuration File (`~/.calm.json`):**
220
221
```json
222
{
223
"calmHubUrl": "https://calmhub.example.com"
224
}
225
```
226
227
**Important:** Unlike the `generate` command which accepts a `-c, --calm-hub-url` command-line option, the **validate command does NOT accept `--calm-hub-url` as a command-line flag**. The validate command will **only** use the CALMHub URL from the `~/.calm.json` configuration file if present.
228
229
When a CALMHub URL is configured, the validate command uses it to:
230
- Load patterns specified as CALMHub URLs (e.g., when using `-p https://calmhub.example.com/patterns/api-gateway.json`)
231
- Load architectures specified as CALMHub URLs
232
- Resolve remote schema references
233
234
**To configure CALMHub for validation:**
235
1. Create or edit `~/.calm.json` in your home directory
236
2. Add the `calmHubUrl` property with your CALMHub instance URL
237
3. Run validation commands normally - the CALMHub URL will be used automatically for remote resources
238
239
**Example with CALMHub configuration:**
240
241
```bash
242
# After configuring ~/.calm.json with calmHubUrl
243
calm validate -a architecture.json -p https://calmhub.example.com/patterns/api-pattern.json
244
```
245
246
The pattern will be loaded from the configured CALMHub instance.
247
248
## Exit Codes
249
250
| Exit Code | Condition |
251
|-----------|-----------|
252
| 0 | Validation successful (no errors, warnings allowed in standard mode) |
253
| 1 | Validation failed (errors present) or strict mode with warnings |
254
255
## Error Handling
256
257
### Common Errors
258
259
**Missing Required Options:**
260
```
261
error: one of the required options '-p, --pattern' or '-a, --architecture' was not specified
262
```
263
**Solution:** Provide at least one of the options.
264
265
**Invalid JSON Format:**
266
```
267
An error occurred while validating: Invalid JSON format
268
```
269
**Solution:** Verify architecture file contains valid JSON.
270
271
**File Not Found:**
272
```
273
An error occurred while validating: ENOENT: no such file or directory
274
```
275
**Solution:** Verify file paths are correct.
276
277
**Schema Not Found:**
278
```
279
An error occurred while validating: Schema not found
280
```
281
**Solution:** Verify schema directory path and that required schemas are present.
282
283
**Network Errors:**
284
```
285
An error occurred while validating: Failed to fetch URL
286
```
287
**Solution:** Verify URLs are accessible and network connection is available.
288
289
## Validation Outcome Structure
290
291
```typescript { .api }
292
// Validation outcome from @finos/calm-shared
293
interface ValidationOutcome {
294
/** JSON schema validation errors */
295
jsonSchemaValidationOutputs: ValidationError[];
296
/** Spectral linting errors and warnings */
297
spectralSchemaValidationOutputs: SpectralError[];
298
/** Whether any errors were found */
299
hasErrors: boolean;
300
/** Whether any warnings were found */
301
hasWarnings: boolean;
302
}
303
304
interface ValidationError {
305
/** Error code (string or number) */
306
code: string | number;
307
/** Error message */
308
message: string;
309
/** JSON path to error location */
310
path: string;
311
/** Schema path that failed */
312
schemaPath: string;
313
}
314
315
interface SpectralError {
316
/** Error/warning code */
317
code: string;
318
/** Severity level */
319
severity: 'error' | 'warning' | 'info' | 'hint';
320
/** Error/warning message */
321
message: string;
322
/** JSON path to issue location */
323
path: string;
324
/** Schema path */
325
schemaPath: string;
326
/** Line number where issue starts */
327
line_start: number;
328
/** Line number where issue ends */
329
line_end: number;
330
/** Character position where issue starts */
331
character_start: number;
332
/** Character position where issue ends */
333
character_end: number;
334
}
335
```
336
337
## Integration with CI/CD
338
339
### GitHub Actions Example
340
341
```yaml
342
name: Validate CALM Architecture
343
on: [push, pull_request]
344
345
jobs:
346
validate:
347
runs-on: ubuntu-latest
348
steps:
349
- uses: actions/checkout@v3
350
- uses: actions/setup-node@v3
351
with:
352
node-version: '18'
353
- run: npm install -g @finos/calm-cli
354
- run: calm validate -a architecture.json -p pattern.json --strict -f junit -o results.xml
355
- uses: actions/upload-artifact@v3
356
if: always()
357
with:
358
name: validation-results
359
path: results.xml
360
```
361
362
### GitLab CI Example
363
364
```yaml
365
validate-calm:
366
image: node:18
367
script:
368
- npm install -g @finos/calm-cli
369
- calm validate -a architecture.json -p pattern.json --strict -f junit -o results.xml
370
artifacts:
371
reports:
372
junit: results.xml
373
```
374
375
## Best Practices
376
377
1. **Use Strict Mode in CI/CD:** Enable `--strict` to enforce zero-warning policy
378
2. **Use JUnit Format for CI:** JUnit output integrates with most CI/CD platforms
379
3. **Version Control Patterns:** Store patterns in version control alongside architectures
380
4. **Validate Early:** Run validation as part of pre-commit hooks or PR checks
381
5. **Use Verbose Mode for Debugging:** Enable `-v` when troubleshooting validation issues
382
6. **Fix Placeholders:** Generated architectures contain placeholders that trigger warnings
383
7. **Schema Versioning:** Pin schema versions in `$schema` field for reproducibility
384