OSS-first docs
These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.
Capabilities
Capabilities are the core building block of ContractSpec. They define what your app can do.
Overview
A ContractSpec (or Capability) is a typed, declarative description of an operation. It defines the operation's name, version, inputs, outputs, policies, and side effects. Runtime adapters automatically serve these as REST/GraphQL/MCP endpoints with full validation and policy enforcement.
Defining a Command (Write)
import { defineCommand } from '@contractspec/lib.contracts-spec';
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
const TransferFundsInput = new SchemaModel({
name: 'TransferFundsInput',
fields: {
recipient: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
amount: { type: ScalarTypeEnum.PositiveNumber(), isOptional: false },
},
});
const TransferFundsOutput = new SchemaModel({
name: 'TransferFundsOutput',
fields: {
transactionId: { type: ScalarTypeEnum.String(), isOptional: false },
timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false },
},
});
export const TransferFunds = defineCommand({
meta: {
key: 'wallet.transferFunds',
version: '1.0.0',
description: 'Transfer funds to another user',
goal: 'Enable peer-to-peer payments',
context: 'Requires sufficient balance',
owners: ['team-payments'],
tags: ['payments'],
stability: 'stable',
},
io: {
input: TransferFundsInput,
output: TransferFundsOutput,
},
policy: {
auth: 'user',
flags: ['payments_enabled'],
},
});Schema Types
ContractSpec uses @contractspec/lib.schema for I/O definitions. This provides Zod validation, GraphQL types, and JSON Schema from a single source.
- •
ScalarTypeEnum.NonEmptyString()- Non-empty text - •
ScalarTypeEnum.PositiveNumber()- Positive numbers - •
ScalarTypeEnum.DateTime()- ISO 8601 timestamps - •
ScalarTypeEnum.Email()- Valid email addresses - •
defineEnum(...)- Type-safe enums
Contracts and specs
Understand the spec model that drives generated surfaces, validation, policy, and safe regeneration.
Data views
Define queryable, presentable views that stay aligned with the rest of the system.
Why ContractSpec
Keep educational and comparison content reachable without letting it define the primary OSS learning path.