Schemas
Review TypeScript declarations and JSON schemas for workspace tasks, triggers, sanitizers, tests, and Trends definitions.
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 Trends schema validates the observation span, metrics, budgets, and optional regression policy together in one authoring schema.
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 YAML beneath ansight/tests |
trends-definition.v1.schema.json | Observation spans, metric budgets, and regression policies beneath ansight/trends |
trigger-definition.v1.schema.json | The static trigger descriptor exported by a trigger module |
The filenames retain their .v1. names for compatibility. Current task and
trigger schemas accept descriptor versions 1 and 2: version 1 requires an
SDK app-tool provider; version 2 adds capability requirements and external
execution support. Workspace tests and Trends definitions still use
"schemaVersion": 1. These versions are unrelated to the app version.
Each link opens the complete source with syntax highlighting, copy, and download actions. Online files come from the host source used to build this website. Generate local copies with your installed CLI when you need its exact contract.
TypeScript declarations
Tasks, triggers, and sanitizers also have declarations for editor completion and type checking. Sanitizers use these declarations without a JSON descriptor schema.
| File | Describes |
|---|---|
ansight/tasks/ansight-task.js | Named runtime permission constants; see permissions |
ansight/tasks/ansight-task.d.ts | Task descriptors, invocation context, host APIs, app tools, and assertions |
ansight/triggers/ansight-trigger.d.ts | Trigger descriptors, events, conditions, retry policy, and app-tool actions |
ansight/sanitizers/ansight-sanitizer.d.ts | Captured evidence types and sanitizer function signatures |
Schemas are necessary but not sufficient
JSON Schema can validate the shape of one definition. The host also performs semantic checks, including valid Trends event spans and metric policies.
Always validate through Ansight:
ansight test validate .The installed CLI is the source of truth for the definitions it supports.
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 and
Trends 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
Tooling and Validation.