contract-standards

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

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

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:

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

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:

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

<plugin-root>/fullstack-typescript/system/system-run.sh contract generate-types <component-name>

Generated Type Usage

Server and webapp consume types via workspace dependency:

// 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:

info:
  version: '1.0.0'  # Bump on breaking changes

---

Validation

Spectral Linting

<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

<plugin-root>/fullstack-typescript/system/system-run.sh contract validate <component-name>

Step 3: Generate Types

<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):

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.