[CG-5228]

Description

Updates the VS Code plugin (calm-plugins/vscode) to name the applied pattern in $schema (using the pattern's $id) instead of writing metadata.patterns:

• instantiateFromPattern sets $schema to the pattern's $id when present.
• mergePatternIntoArchitecture sets $schema when the target architecture does not already name one, preserves the existing $schema when merging into an architecture that already has one, and no longer writes metadata.patterns.
• Updated App.tsx and PatternPicker.tsx accordingly.

Fixes #3547

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🎨 Code style/formatting changes
• ♻️ Refactoring (no functional changes)
• ⚡ Performance improvements
• ✅ Test additions or updates
• 🔧 Chore (maintenance, dependencies, CI, etc.)

Affected Components

• CLI (cli/)
• Schema (calm/)
• CALM AI (calm-ai/)
• CALM Hub (calm-hub/)
• CALM Hub UI (calm-hub-ui/)
• CALM Lab (calm-lab/)
• CALM Models (calm-models/)
• CALM Server (calm-server/)
• CALM Studio (calm-studio/)
• CALM Widgets (calm-widgets/)
• CALMGuard (calm-guard/)
• Documentation (docs/)
• Shared (shared/)
• VS Code Extension (calm-plugins/vscode/)
• Dependencies
• CI/CD

Testing

• I have tested my changes locally
• I have added/updated unit tests
• All existing tests pass

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (if applicable)
• My changes follow the project's coding standards

[markscott-ms]

Thank you for this PR, @CG-5228. I found one problem, in the inline comment below.

@byrash @rocketstack-matt: the PR keeps the first $schema when you apply a second pattern (one of the two options in #3547). The architecture then has no reference to the second pattern, and calm validate does not check it. Are you happy with this design?

[byrash]

Thank you for this PR, @CG-5228. I found one problem, in the inline comment below.

@byrash @rocketstack-matt: the PR keeps the first $schema when you apply a second pattern (one of the two options in #3547). The architecture then has no reference to the second pattern, and calm validate does not check it. Are you happy with this design?

Thanks for raising this. Our intention is to support multiple patterns on a single architecture, so we do not want to reinforce a design where only a single $schema can be represented.

We acknowledge that the current approach has a validation gap because only the first schema is considered. However, we see this as a limitation of the current validation implementation rather than the target architecture model. Long term, we expect both the architecture representation and calm validate to support and validate all patterns applied to an architecture.

For example, the desired future state would allow an architecture to reference multiple pattern schemas, conceptually similar to:

{
  "patterns": [
    {
      "$schema": "https://example.com/schemas/pattern-a.json"
    },
    {
      "$schema": "https://example.com/schemas/pattern-b.json"
    }
  ]
}

In that model, validation would evaluate the architecture against all referenced pattern schemas rather than stopping at the first one. Given that direction, we would prefer not to optimize the design around a single-schema assumption, as that could make the transition to full multi-pattern support more difficult in the future.
Thanks!

[rocketstack-matt]

Thanks @byrash. I agree that CALM must not stay limited to one pattern. But a patterns array with a nested $schema is not a JSON Schema construct, and it does not close the validation gap.

Reference. In JSON Schema, $schema is one URI. To say "conforms to A and B", make a pattern that is allOf A and B, and name it in $schema. CALM already does this: calm.json is allOf the 2020-12 meta schema and core.json.

{
  "$schema": "https://calm.finos.org/release/1.3/meta/calm.json",
  "$id": "https://example.com/patterns/payments.pattern.json",
  "allOf": [
    { "$ref": "https://example.com/patterns/web.pattern.json" },
    { "$ref": "https://example.com/patterns/db.pattern.json" }
  ]
}

The current calm validate checks both patterns when an architecture names this composite in $schema. No code change is necessary.

Pattern bodies. This is the harder part. Today a pattern gives each node a position: "node 1 is the website, node 2 is the load balancer". Often it also gives the total: "exactly 5 nodes". One architecture cannot pass two patterns that are written like this:

• Pattern A says that node 1 is web. Pattern B says that node 1 is db. One node cannot be both.
• Pattern A says "exactly 2 nodes". When we add the node from pattern B, there are 3.

The architecture fails if we list the patterns in an array, and it also fails if we combine them with allOf.

To fix this, a pattern must say "the architecture has a node like this", with no position and no total. The JSON Schema keyword for this is contains:

"nodes": {
  "prefixItems": [
    { "properties": { "unique-id": { "const": "web" } } },
    { "properties": { "unique-id": { "const": "api" } } }
  ],
  "minItems": 2,
  "maxItems": 2
}

becomes

"nodes": {
  "allOf": [
    { "contains": { "properties": { "unique-id": { "const": "web" } } } },
    { "contains": { "properties": { "unique-id": { "const": "api" } } } }
  ]
}

I tested this. With contains, an architecture passes both patterns when the nodes are in any order, and it fails when a node is missing. But no tool can make an architecture from a contains pattern today, because calm generate, the canvas, Hub UI, CALM Lab and the Spectral pattern rules all read node positions. So this change affects all CALM tools, not only the plugin. #3626 records the requirement and the changes in each tool.

@CG-5228, thank you for this PR and for your work on it. The design must change before the canvas can name more than one pattern, so I am closing this PR and #3547. #3626 replaces them.