Schemas
Understand the generated versioned JSON Schema contracts used to validate workspace definitions and static module descriptors.
CLI v0.23.1
The ansight/schema folder contains machine-readable contracts for workspace
definitions. They help editors and CI catch missing values, unknown fields,
invalid limits, and unsupported contract versions.
The quality schema also validates an optional trend policy on each
measurement. There is no separate trend authoring schema because the policy uses
the measurement’s identity and lifecycle. Runtime trend decisions and history
remain separate contracts.
Most app teams should treat these files as generated reference material. Write definitions in their feature folders; do not customize a schema to make an invalid definition pass locally.
Generated contracts
ansight workspace init . creates:
| File | Validates |
|---|---|
task-definition.v1.schema.json | The static task descriptor exported by a task module |
test-definition.v1.schema.json | Agentic test JSON beneath ansight/tests |
flow-definition.v1.schema.json | Semantic event-window JSON beneath ansight/flows |
quality-definition.v1.schema.json | Per-run measurement JSON beneath ansight/quality |
trigger-definition.v1.schema.json | The static trigger descriptor exported by a trigger module |
The .v1. segment is the Ansight contract version, not the app version. A
definition with "schemaVersion": 1 uses version 1 of the relevant contract.
Sanitizers use TypeScript declarations rather than a JSON descriptor schema.
Schemas are necessary but not sufficient
JSON Schema can validate the shape of one definition. The host also performs semantic and cross-file checks, such as resolving a quality check’s flow.
Always validate through Ansight:
ansight test validate .The running host is the source of truth because its parser and runtime match the installed product version exactly.
Refresh generated files
Initialization preserves existing files by default:
ansight workspace init .Use --force only when you intentionally want the installed host’s canonical
support files to replace local copies:
ansight workspace init . --forceThis also replaces other generated support assets, including folder READMEs, declaration files, and TypeScript configuration. Review the resulting diff before committing.
Editor integration
JSON-aware editors can associate these schemas with workspace definition paths.
Even without an editor association, ansight test validate . validates test,
flow and quality definitions and reports catalog warnings.
Task and trigger authors should use the adjacent .d.ts files for TypeScript
completion while keeping the exported descriptor JSON-compatible. See
Authoring and Validation.
Developing the contract
If you are changing Ansight itself, update the canonical schema artifact, parser, runtime behavior, generated support files, examples, and tests together. Do not patch only a copied schema in an app repository.