LiorCohen/sdd / plugin/fullstack-typescript/skills/components/contract/contract-standards
contract-standards
VerifiedOpenAPI contract standards for API specification, versioning, and type generation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
SKILL.md
View on GitHub---
name: contract-standards
description: OpenAPI contract standards for API specification, versioning, and type generation.
---
# Contract Standards Skill
Standards for OpenAPI contract components that define API specifications and generate TypeScript types.
---
## Purpose
Contract components are the single source of truth for API types:
1. **Define API shape** in OpenAPI 3.0 YAML
2. **Generate TypeScript types** consumed by server and webapp
3. **Validate API consistency** via Spectral linting
4. **Enable type-safe development** across the stack
---
## Directory Structure
```text
components/contract[-{name}]/
├── package.json # Build scripts (generate:types, validate)
├── tsconfig.json # TypeScript config for generated types
├── openapi.yaml # OpenAPI 3.0 specification
├── .spectral.yaml # Spectral linting rules (optional)
├── .gitignore # Ignores generated/ directory
└── generated/ # Git-ignored generated output
└── api-types.ts # Generated TypeScript types
```
---
## Config Schema
Contract components do not require application config from `components/config/`. They are build-time artifacts, not runtime services. The `contract-scaffolding` skill generates an `openapi.yaml`, `package.json` with type generation scripts, and a `generated/` directory for TypeScript types.
---
## OpenAPI Specification Standards
### Info Section
```yaml
openapi: '3.0.3'
info:
title: Project API
version: '1.0.0'
description: API description
```
### Path Naming
| Pattern | Example | Use Case |
|---------|---------|----------|
| `/resources` | `/users` | Collection endpoint |
| `/resources/{id}` | `/users/{userId}` | Single resource |
| `/resources/{id}/subresources` | `/users/{userId}/orders` | Nested resources |
**Rules:**
- Use plural nouns for collections (`/users`, not `/user`)
- Use kebab-case for multi-word paths (`/user-profiles`)
- Use camelCase for path parameters (`{userId}`)
- Avoid verbs in paths (use HTTP methods instead)
### Operation IDs
Operation IDs become handler function names:
```yaml
paths:
/users:
get:
operationId: listUsers # -> handleListUsers
post:
operationId: createUser # -> handleCreateUser
/users/{userId}:
get:
operationId: getUser # -> handleGetUser
put:
operationId: updateUser # -> handleUpdateUser
delete:
operationId: deleteUser # -> handleDeleteUser
```
**Rules:**
- Use camelCase
- Start with verb: `get`, `list`, `create`, `update`, `delete`
- Be specific: `getUserProfile`, not `getProfile`
### Request/Response Schemas
```yaml
components:
schemas:
User:
type: object
required:
- id
- email
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
createdAt:
type: string
format: date-time
CreateUserRequest:
type: object
required:
- email
properties:
email:
type: string
format: email
name:
type: string
Error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
```
**Naming Conventions:**
- Resource schemas: `User`, `Order`, `Task`
- Request schemas: `CreateUserRequest`, `UpdateOrderRequest`
- Response wrappers (if needed): `UserListResponse`, `PaginatedResponse`
- Errors: `Error`, `ValidationError`
### Standard Error Responses
Define reusable error responses:
```yaml
components:
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
```
### Health Endpoints
**Health check endpoints are NOT defined in the contract.** They are infrastructure endpoints implemented directly in the Operator layer:
- `/health` - Liveness probe
- `/readiness` - Readiness probe
These run on a separate port (e.g., 9090) from the main API.
---
## Type Generation
### Running Generation
```bash
<plugin-root>/fullstack-typescript/system/system-run.sh contract generate-types <component-name>
```
### Generated Type Usage
Server and webapp consume types via workspace dependency:
```typescript
// In server or webapp
import type { components, paths } from '@project/contract';
// Schema types
type User = components['schemas']['User'];
type CreateUserRequest = components['schemas']['CreateUserRequest'];
// Path types (for typed API clients)
type GetUserPath = paths['/users/{userId}']['get'];
```
### Type Import Rules
- **Always use `import type`** - Contract types are compile-time only
- **Never modify generated files** - Regenerate instead
- **Add to workspace dependencies** - Use `"workspace:*"` version
---
## Versioning
### API Versioning Strategy
| Strategy | When to Use |
|----------|-------------|
| URL path (`/v1/users`) | Breaking changes require new version |
| No versioning | Internal APIs, rapid iteration |
For most SDD projects, avoid versioning until you have external consumers.
### Schema Versioning
Track changes in `info.version`:
```yaml
info:
version: '1.0.0' # Bump on breaking changes
```
---
## Validation
### Spectral Linting
```bash
<plugin-root>/fullstack-typescript/system/system-run.sh contract validate <component-name>
```
Uses `.spectral.yaml` for custom rules (optional).
### Required Validations
1. **All paths have operationId**
2. **All schemas have required fields defined**
3. **Response schemas match request context**
4. **No unused schemas**
---
## Implementation Order
When adding a new endpoint:
### Step 1: Design the Endpoint
1. Add path to `openapi.yaml`
2. Define request schema (if POST/PUT/PATCH)
3. Define response schema
4. Add operationId
### Step 2: Validate
```bash
<plugin-root>/fullstack-typescript/system/system-run.sh contract validate <component-name>
```
### Step 3: Generate Types
```bash
<plugin-root>/fullstack-typescript/system/system-run.sh contract generate-types <component-name>
```
### Step 4: Implement in Server
Server endpoint implementation must follow `backend-standards` — it defines the CMDO handler → orchestrator → repository layering that contract endpoints are built upon.
---
## Multi-Contract Projects
When a project has multiple contracts (e.g., public API vs internal API):
```text
components/contracts/
├── public-api/ # External-facing API
│ └── openapi.yaml
└── internal-api/ # Service-to-service API
└── openapi.yaml
```
Each contract:
- Has its own package name (`@project/public-api`)
- Generates its own types
- Is consumed independently by servers/webapps
---
## Summary Checklist
Before committing contract changes:
- [ ] All paths have operationId
- [ ] Operation IDs follow camelCase verb convention
- [ ] Request/response schemas are defined
- [ ] Required fields are specified
- [ ] Standard error responses are used
- [ ] Types regenerated after spec changes
- [ ] Validation passes (`contract validate`)
- [ ] No health endpoints in contract (they're infrastructure)
---
## Input / Output
This skill defines no input parameters or structured output.
---
## Related Skills
- `backend-standards` — Delegate to this for server-side endpoint implementation. Defines the CMDO handler → orchestrator → repository layering that contract endpoints are built upon.
- `frontend-standards` — Delegate to this for webapp consumption of generated types. Defines MVVM patterns and TanStack Query hooks that use the TypeScript types generated from OpenAPI specs.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |