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.
OpenAPI alternative
A spec-first approach that goes beyond OpenAPI with executable contracts and code generation.
OpenAPI Limitations
- OpenAPI is documentation-only
- No type safety from OpenAPI specs
- Manual SDK generation is complex
- Cannot validate implementations against OpenAPI
ContractSpec Advantages
- Executable contracts with validation
- Generate multiple outputs from one spec
- Type-safe by default
- Built-in testing and validation
Comparison: OpenAPI vs ContractSpec
Key differences between OpenAPI documentation and ContractSpec executable contracts.
OpenAPI
- • Documentation specification only
- • No runtime validation
- • Manual code generation
- • Type safety requires tools
- • Separate schemas from documentation
ContractSpec
- • Executable contracts
- • Built-in runtime validation
- • Automatic code generation
- • Type-safe by default
- • Unified spec and implementation
Export from Contracts
Generate OpenAPI documentation from ContractSpec for existing tooling.
export-openapi
# From ContractSpec contracts
contractspec openapi export \
--registry ./src/contracts/registry.ts \
--format yaml \
--out ./openapi.yaml
# Compare: Manual OpenAPI vs Generated
# Manual: Write OpenAPI by hand, maintain separately
# Generated: Single source of truth, always in syncBeyond Documentation
ContractSpec provides more than just API documentation.
multi-output-example.ts
// One contract, multiple outputs
import { UserApiContract } from './contracts/user-api.contract';
// Generated outputs
export const outputs = {
// API documentation (OpenAPI)
openapi: UserApiContract.toOpenAPI(),
// Client SDKs (TypeScript, Python, etc.)
clients: UserApiContract.generateClients({
languages: ['typescript', 'python', 'go'],
}),
// Database schemas (Prisma, Drizzle)
database: UserApiContract.toDatabase({
adapter: 'prisma',
}),
// API handlers (Express, Fastify, Next.js)
handlers: UserApiContract.toHandlers({
framework: 'express',
}),
// Validation middleware
validation: UserApiContract.toValidation({
library: 'zod',
}),
// Type definitions
types: UserApiContract.toTypescript(),
};OSS docsStart with OSS. Adopt Studio when you want the operating layer.
Why ContractSpec
Keep educational and comparison content reachable without letting it define the primary OSS learning path.