Design Discussion: CALM-Hub Decorator Registry and Views

[LeighFinegold]

Feature Proposal

Target Project:

calm-hub, calm-hub-ui

Description of Feature:

Decorator standards are intentionally kept outside the CALM schema release cycle; they evolve independently, and that's a reasonable design choice. But there's a gap: CALM Hub has no mechanism to discover decorator standards, and its UI hardcodes knowledge of specific decorator types.

Today, the deployment decorator exists as:

• A worked schema in the documentation
• Draft standards in calm/draft/2026-03/standards/deployment/
• Hardcoded TypeScript types in calm-hub-ui (DeploymentDecorator, DeploymentDecoratorData)
• A dedicated UI panel with deployment-specific rendering logic (DeploymentPanel.tsx, DeploymentDetail.tsx, SummarySection.tsx)
• A hardcoded tab in DiagramSection.tsx: type DiagramTabType = 'diagram' | 'json' | 'deployments'

Because decorator standards live outside the schema release, CALM Hub needs its own mechanism to discover, register, and render decorator standards. Without this, each decorator type ends up hardcoded into the UI, requiring a code change, new React components, and a release for every new decorator type. This contradicts the open-ended type: string design of decorators, where the whole point is that teams can define new types independently.

If a team publishes a threat-model decorator, a business-taxonomy decorator, or any other type today, CALM Hub has no way to render them.

User Stories:

• As a CALM adopter, I want to register my custom decorator type with CALM Hub and have it rendered meaningfully, without waiting for a UI code change.
• As a security team, I want to publish threat-model decorators and have CALM Hub show them alongside deployment decorators, without the CALM Hub team hardcoding support.
• As a CALM contributor, I want to add a new decorator standard without having to also write bespoke React components and TypeScript types for CALM Hub UI.
• As a CALM Hub operator, I want to configure which decorator types my installation supports and how they're validated.

Current Limitations:

• decorators.json defines the base envelope but no standard decorator types are registered or discoverable
• Deployment standard exists only in draft (calm/draft/2026-03/standards/deployment/)
• calm validate is decorator-blind; nothing catches malformed decorators or validates them against type-specific schemas ([calm-spec] Decorator mechanism — close meta-schema and CLI gaps (core.json, sidecar wrapper, extension schemas, calm validate) #2552)
• DiagramSection.tsx defines type DiagramTabType = 'diagram' | 'json' | 'deployments', a closed set
• Deployment tab is architectures-only: isArchitecture && viewModeRow('deployments', ...)
• MetadataPanel has hardcoded tabs for flows, controls, deployment, and ADRs
• New decorator types require code changes in both backend and frontend

Proposed Implementation:

CALM Hub should support a decorator standard registry that serves two purposes: knowing what decorator types are available (with their schemas), and driving how they're rendered in the UI.

Registry mechanism (how CALM Hub knows about decorator types):

Possible approaches include:

• API-based registration: decorator standards registered via REST API and stored in CALM Hub
• Configuration-based: decorator standard schemas loaded from a config directory at startup
• Convention-based: CALM Hub scans for schemas following a naming pattern

Each registered standard provides its JSON schema (using the existing allOf extension of decorators.json) so that CALM Hub can validate incoming decorators against their declared type.

View rendering (how CALM Hub displays registered decorator types):

Possible approaches include:

• Schema-driven rendering: the registered schema includes hints about how to render its data (field labels, layout, formatting). CALM Hub generates a generic view. Declarative but may be too rigid for complex views.
• View registry: administrators register view definitions alongside schemas, describing rendering contracts. More flexible.
• Generic fallback: at minimum, any decorator type without a specific view gets a generic JSON/table renderer. Nothing should be invisible just because it lacks a bespoke component.

The deployment panel could become the first "registered" view rather than a hardcoded one, proving the pattern.

Alternatives Considered:

• Bundle decorator standards into CALM schema releases: rejected because keeping them independent is a deliberate design choice that allows faster evolution
• Continue hardcoding: add new React components for each decorator type. Doesn't scale and creates a release bottleneck
• JSON-only view for non-deployment decorators: functional but loses the value of structured rendering

Additional Context:

This issue is part of a series exploring CALM's decorator and document model. Consider reading the related issues for broader context:

• Design Discussion: Documents vs Decorators #2791 Documents vs Decorators
• Design Discussion: Decorator Association Scalability Concerns #2793 Decorator Association Scalability Concerns
• [calm-spec] Decorator mechanism — close meta-schema and CLI gaps (core.json, sidecar wrapper, extension schemas, calm validate) #2552 Decorator mechanism: close meta-schema and CLI gaps
• RFC: shared CALM semantics layer to align calm-hub-ui and calm-studio #2690 RFC: shared CALM semantics layer to align calm-hub-ui and calm-studio
• Allow flows array to be a reference to a document referencing a flow #1876 Contains the decorator definitional debate (intent vs evidence, ownership-based)

[willosborne]

In theory we can render the standards (json schema) with the same kind of json schema renderers that already exist for e.g. OpenAPI.
One such library is @stoplight/json-schema-viewer - https://github.com/stoplightio/json-schema-viewer

I think we should stick with something generic until we're sure we need some kind of rendering contract feature

[aamanrebello]

For registry mechanism, I prefer configuration based registration, where we update the config manually as and when new decorators are proposed. To my understanding, the list of possible decorators is finite and won't get added to regularly, so if the volume of changes is low then there is a rest API or a scan may be overkill.

For rendering, I agree with Will to do something generic for time being.