Specifications Overview
ContractSpec is built on a spec-first philosophy. You define declarative TypeScript specifications that describe what your application can do. Runtime adapters automatically serve these specs as type-safe API endpoints (REST, GraphQL, MCP), enforce policies, and validate inputs/outputs—no code generation required.
Why spec-first matters
Traditional development requires writing and maintaining separate code for APIs, databases, UI components, validation logic, and access control. This approach leads to:
- Duplication across front-end and back-end
- Type mismatches and runtime errors
- Security vulnerabilities from inconsistent policy enforcement
- High maintenance burden when requirements change
With ContractSpec, you define your application's operations (Commands/Queries), workflows, and policies in pure TypeScript. Runtime adapters ensure consistency, type safety, and policy enforcement across your entire stack—the spec is the implementation.
Specification types
| Spec Type | Purpose | Generates |
|---|---|---|
| CapabilitySpec | Defines what your application can do: operations (Commands/Queries), their inputs, outputs, policies, and side effects. | Runtime-served REST/GraphQL/MCP endpoints, Zod validation, policy enforcement |
| DataViewSpec | Describes how data should be queried, filtered, sorted, and presented to users. | Database queries, list/detail views, search interfaces |
| WorkflowSpec | Orchestrates multi-step processes with retries, compensation, and monitoring. | Workflow engine, state machines, retry logic, observability hooks |
| PolicySpec | Defines who can do what, when, and under what conditions. Supports ABAC and PII rules. | Policy decision points, access control middleware, audit logs |
| OverlaySpec | Allows safe, signed customization of UI layouts and field visibility by tenants or users. | Personalized UI components, layout variations, conditional rendering |
| TelemetrySpec | Specifies what metrics, logs, and traces to collect for observability. | Instrumentation code, dashboards, alerting rules |
| MigrationSpec | Manages incremental, reversible schema and data migrations. | Migration scripts, rollback procedures, version tracking |
How specs work together
Specs compose naturally. A WorkflowSpec can invoke multiple CapabilitySpecs. A DataViewSpec respects PolicySpecs to filter sensitive fields. An OverlaySpec can hide or rearrange UI elements generated from a CapabilitySpec, but only within the bounds allowed by the underlying policy.
This composability means you can build complex applications from simple, reusable building blocks—all while maintaining type safety and policy enforcement.
Next steps
Explore each specification type in detail using the links in the table above, or continue with the core concepts: