Skip to content

P2.SPC.001 — API boundary has a machine-readable contract

Field Value
Principle P2 Spec-first
Severity warn
Evidence strong
Stability experimental

What it checks

Fires when the repo looks like an HTTP/gRPC/GraphQL service (based on directory and filename patterns like handlers/, controllers/, server.go, app.py) but has no machine-readable API contract.

Recognized contract files

  • OpenAPI: openapi.yaml, openapi.yml, openapi.json, swagger.*
  • Protobuf: *.proto under proto/ or api/
  • GraphQL: schema.graphql, *.graphql under graphql/
  • Any file under api/ with .yaml, .yml, or .json extension

Service indicators

The rule considers a repo a "service" when it contains files with path segments or basenames matching common web framework conventions:

  • Path segments: handler, controller, router, routes, endpoint, server, views, resource
  • Basenames: server.go, server.ts, server.js, app.py, app.js, routes.rb, routes.py, wsgi.py, asgi.py

When to suppress

If the repo is a library, CLI tool, or internal service that intentionally has no external API contract, add an ignore entry:

ignore:
  - rule: P2.SPC.001
    reason: "Internal service with no external consumers"
    expires: "2027-01-01"