Define versioned dashboard model and validation #3

New issue

Closed

opened 2026-06-18 16:11:54 +02:00 by vince · 0 comments

vince commented

2026-06-18 16:11:54 +02:00

Owner

Parent: #1

Goal

Define the canonical dashboard model that the renderer and AI agent both operate on. This is the source of truth instead of YAML files.

Scope

Design a JSON-serializable, versioned dashboard document model.
Cover dashboard metadata, layout regions, telemetry cards, service groups, service entries, status bars, datasource references, status rules, icons, links, and display units.
Use @sinclair/typebox as the schema authoring layer so TypeScript types and JSON Schema come from one source.
Use ajv for runtime validation of dashboard documents and agent/tool inputs.
Export JSON Schema for agent/tool structured outputs and external integrations.
Add typed TypeScript interfaces inferred from the schema.
Add fixture examples for the Dimension Lab dashboard and at least one non-Dimension Lab dashboard to prove portability.
Add clear validation errors that can be returned to agents.

Acceptance criteria

The model has an explicit version field and migration strategy placeholder.
Invalid dashboard documents fail with actionable Ajv validation errors.
Components can consume typed model objects without knowing where they came from.
The Dimension Lab fixture contains content only in the model fixture, not in renderer code.
JSON Schema output exists for agent/tool contracts.
TypeBox schemas are treated as the canonical schema source; Zod is not the primary model dependency.

Out of scope

Database persistence.
Agent mutation endpoints.
Final visual rendering.

Parent: #1 ## Goal Define the canonical dashboard model that the renderer and AI agent both operate on. This is the source of truth instead of YAML files. ## Scope - Design a JSON-serializable, versioned dashboard document model. - Cover dashboard metadata, layout regions, telemetry cards, service groups, service entries, status bars, datasource references, status rules, icons, links, and display units. - Use `@sinclair/typebox` as the schema authoring layer so TypeScript types and JSON Schema come from one source. - Use `ajv` for runtime validation of dashboard documents and agent/tool inputs. - Export JSON Schema for agent/tool structured outputs and external integrations. - Add typed TypeScript interfaces inferred from the schema. - Add fixture examples for the Dimension Lab dashboard and at least one non-Dimension Lab dashboard to prove portability. - Add clear validation errors that can be returned to agents. ## Acceptance criteria - The model has an explicit version field and migration strategy placeholder. - Invalid dashboard documents fail with actionable Ajv validation errors. - Components can consume typed model objects without knowing where they came from. - The Dimension Lab fixture contains content only in the model fixture, not in renderer code. - JSON Schema output exists for agent/tool contracts. - TypeBox schemas are treated as the canonical schema source; Zod is not the primary model dependency. ## Out of scope - Database persistence. - Agent mutation endpoints. - Final visual rendering.