Part 2 · 1 chapters · ~8 min

API and Schema Governance

Shared API style guides, linting OpenAPI with Spectral and Protobuf with buf, breaking-change detection in CI, schema registries and compatibility modes for events, database schema review, an API review group for new public APIs, and governance that scales without becoming a bottleneck.

Rules in CI, judgement in review

code

# .spectral.yaml (excerpt): house rules for every OpenAPI document
extends: ["spectral:oas"]
rules:
  paths-kebab-case: { given: "$.paths[*]~", then: { function: pattern, functionOptions: { match: "^(/[a-z0-9-{}]+)+$" } } }
  money-is-minor-units: { given: "$..properties[?(@property.match(/amount/))]", then: { field: type, function: enumeration, functionOptions: { values: [integer, string] } } }
  error-format: { given: "$.paths.*.*.responses[?(@property >= 400)].content", then: { field: "application/problem+json", function: truthy } }

# CI
npx @stoplight/spectral-cli lint openapi.yaml
npx oasdiff breaking main:openapi.yaml openapi.yaml --fail-on ERR
buf lint && buf breaking --against '.git#branch=main'

Database schemas: migrations are reviewed by the owning team plus a database-reliability check for locks and long-running operations (Postgres P5, Deploy course on expand/contract).

API AND SCHEMA GOVERNANCE, AUTOMATED

rules checked in CI, humans for judgement

swipe the figure sideways, or tap expand for full screen

1/4

style as code

Naming, pagination, error format and versioning rules live in a shared ruleset (Spectral for OpenAPI, buf for Protobuf). CI comments on violations.

house style as a linterno debates in review