EXPERIMENTAL FEEDBACK REQUEST - Calm CLI server

[markscott-ms]

Experimental Feature Feedback

The CALM maintainers seek your feedback on an experimental feature or module, detailed below.

Please add constructive positive or negative feedback as comments to this issue.

Experimental Feature Process

Description of Feature:

It may be required to have the operations of the CALM CLI available over REST.
The validate command has been made available via an API

calm server --schema-directory calm

curl http://127.0.0.1:3000/health

# Missing schema key
curl -H "Content-Type: application/json" -X POST http://127.0.0.1:3000/calm/validate --data @cli/test_fixtures/validation_route/invalid_api_gateway_instantiation_missing_schema_key.json

# Schema value is invalid
curl -H "Content-Type: application/json" -X POST http://127.0.0.1:3000/calm/validate --data @cli/test_fixtures/validation_route/invalid_api_gateway_instantiation_schema_points_to_missing_schema.json

# instantiation is valid
curl -H "Content-Type: application/json" -X POST http://127.0.0.1:3000/calm/validate --data @cli/test_fixtures/validation_route/valid_instantiation.json

Feedback Timeline:

• Publicised at Monthly Working Group Meeting on: 25 Nov 2025 Architecture as Code - Working Group Meeting - Tuesday 25th November 2025 #1847
• Publicised at Weekly Office Hours on: [Date]
• Announced on Architecture as Code Mailing List on: [Date]
• Feedback Period Ends on: 25 Feb 2026
• Accepted as non-experimental / Removed from codebase on: [Date]

Target Project:

It is implemented within the cli codebase.

User Stories:

As a system that needs to process CALM architecture documents
When I have a CALM document to validate
Then I desire to ask a service to validate it rather subprocess invoking node and the CALM CLI.

Feedback Emphasis:

• usefulness of validate available over REST
• usefulness of REST validate being provided by CALM CLI operating in a server mode, and not implementing a validation service within CalmHub
• why a subprocess execution of the calm cli is not suitable
• other facilities that may be required over REST

Current Limitations:

• There is no authentication or authorisation on the exposed API.
• The server listens on all network interfaces.

Implementation Details:

• calm CLI starts a service listening on port 3000 (by default) or other port as specified. The service listens on 0.0.0.0, i.e. all network interfaces
• Uses Node Express as a server
• Loads CALM schemas from a local directory
• Offers a single API endpoint responding to POST requests, accepting JSON and validating against a CALM schema.

[Budlee]

Fantastic and very useful functionality, I will put in an issue and PR to extend the functionality.

The Calm CLI Server should be moved out of Experimental and into General Usage