api-schema

name	api-schema
description	Defines request/response shapes, versioning, validation, and compatibility rules for API-first work. Trigger on 'design API', 'OpenAPI spec', 'REST schema', 'API versioning', 'generate client SDK'. DO NOT USE for GraphQL schemas, gRPC/protobuf definitions (use stack-standards), auth endpoint logic (use auth-patterns), or external API client wrappers (use external-api-client).
license	Apache-2.0
compatibility	{"clients":["openai-codex","gemini-cli","opencode","github-copilot"]}
metadata	{"owner":"codex","domain":"api-schema","maturity":"draft","risk":"low","tags":["api","schema"]}

Purpose

Design API schemas using OpenAPI 3.1 and JSON Schema for type-safe contracts between services. Define versioning strategy, distinguish breaking from non-breaking changes, and enable code generation from specs. The schema IS the contract—disagreement about the schema means disagreement about the API.

When to use this skill

Use when:

• Designing new REST/HTTP API
• Adding endpoints to existing API
• Generating client SDKs or server stubs
• Documenting API for external consumers

Do NOT use when:

• GraphQL APIs (different schema language)
• Internal RPC/gRPC (use protobuf)
• Simple scripts with no API consumers

Operating procedure

1. Create OpenAPI 3.1 specification:

   openapi: 3.1.0
   info:
     title: User Service API
     version: 1.0.0
     description: API for user management
   
   servers:
     - url: https://api.example.com/v1
       description: Production
     - url: https://staging-api.example.com/v1
       description: Staging
   
   paths:
     /users/{userId}:
       get:
         operationId: getUser
         summary: Get user by ID
         parameters:
           - name: userId
             in: path
             required: true
             schema:
               type: string
               format: uuid
         responses:
           '200':
             description: User 
             
               
                 
                    
           
                
   

Output defaults

# openapi.yaml
openapi: 3.1.0
info:
  title: [Service Name] API
  version: 1.0.0
  description: |
    [Description]
    
    ## Versioning
    URL path versioning: /v1/, /v2/
    
    ## Authentication
    Bearer token in Authorization header

servers:
  - url: https://api.example.com/v1

paths:
  /[resource]:
    get:
      # ...
    post:
      # ...

components:
  schemas:
    # Reusable types
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

References

• OpenAPI 3.1 Specification: https://swagger.io/specification/
• https://spec.openapis.org/oas/v3.1.0
• https://json-schema.org/learn/getting-started-step-by-step

Failure handling

• Schema and implementation drift: Generate code from schema or validate implementation against schema in CI
• Breaking change deployed accidentally: Add breaking-change detection to CI; tools like oasdiff can compare specs
• Clients fail on new fields: Design clients to ignore unknown fields; use additionalProperties: true in response schemas
• Validation too strict: Start permissive, tighten later; it's easier to reject more than to accept more
• Large spec becomes unmaintainable: Split into multiple files using $ref to external files