Support for organisation-specific schema extensions (standards)

[rocketstack-matt]

Summary

Enable organisations to extend CALM schemas with their own specific requirements (e.g., firm-specific inventory IDs, risk attributes) without needing to fork or replace the entire schema hierarchy from calm.json down.

Problem Statement

CALM has a concept of 'standards' which allows extending base schemas with more specific requirements. Currently, this approach has significant limitations:

1. Schema hierarchy coupling: Unless an organisation creates a complete replacement for CALM from calm.json down, the tooling has no awareness of custom standards
2. Maintenance burden: Introducing new standards is time-consuming and error-prone
3. Tooling gaps: The CLI, VS Code extension, and CALM Chat Mode have no mechanism to discover or apply organisation-specific schemas

Proposed Solution

1. CLI Validation Extension

Extend calm validate to accept additional organisation-specific schema directories:

calm validate --architecture arch.json --standards ./org-standards/

This would layer organisation schemas on top of the base CALM schemas during validation.

Related: #1562

2. VS Code Extension Enhancement

Allow users to configure folders containing additional schemas via extension settings:

{
  "calm.standards.paths": [
    "./org-standards",
    "/shared/company-calm-standards"
  ]
}

This would enable:

• Real-time validation against organisation standards during authoring
• Autocompletion for organisation-specific properties and values
• Hover documentation for custom schema elements

3. CALM Chat Mode Integration

Extend Chat Mode to be aware of organisation-specific standards so it can:

• Generate architectures that comply with organisation requirements
• Provide guidance on organisation-specific fields
• Validate suggestions against custom schemas

Example Use Case

An organisation wants to require:

• A firm-inventory-id field on all nodes
• Risk classification attributes (data-classification, business-criticality)
• Approved technology stacks for specific node types

They would create an extension schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://myorg.com/calm/standards/node-extensions.json",
  "allOf": [
    { "$ref": "https://calm.finos.org/release/1.1/meta/core.json#/defs/node" },
    {
      "properties": {
        "firm-inventory-id": { "type": "string", "pattern": "^INV-[0-9]{6}$" },
        "data-classification": { "enum": ["public", "internal", "confidential", "restricted"] },
        "business-criticality": { "enum": ["low", "medium", "high", "critical"] }
      },
      "required": ["firm-inventory-id", "data-classification"]
    }
  ]
}

Benefits

• Reduced friction: Organisations can adopt CALM and layer their requirements without forking
• Consistent tooling: Single source of truth for standards across CLI, IDE, and AI assistants
• Easier upgrades: Organisation standards remain separate from core CALM, simplifying version upgrades
• Better developer experience: Authors get real-time feedback on organisation-specific requirements

Affected Components

• CLI (cli/)
• Shared (shared/)
• VS Code Extension (calm-plugins/vscode/)
• CALM AI (calm-ai/)
• Documentation (docs/)

Additional Context

This proposal builds on the existing schema extension patterns in CALM and would formalise the approach for organisation-specific customisation.