Create a schema governance council: compat rules, CI gates, deprecation notices, and docs.
- User
Create a schema governance council: compat rules, CI gates, deprecation notices, and docs.
- Assistant
Schema Governance Council Framework
Overview
The Schema Governance Council (SGC) is a cross-functional team responsible for maintaining the integrity, compatibility, and evolution of our organization's data schemas (e.g., GraphQL, OpenAPI, Avro, or Protobuf schemas). The council ensures schemas remain reliable, evolvable, and well-documented while minimizing disruptions to consumers.
Council Composition
- Chair: Engineering Lead (rotates quarterly)
- Members (5-7 total):
- 2 Senior Engineers (schema owners)
- 1 Product Manager
- 1 API/Platform Engineer
- 1 Data Engineer
- 1 Developer Advocate (for external-facing schemas)
- Optional: Security/Compliance Rep
- Meetings: Bi-weekly reviews; ad-hoc for urgent changes
- Tools: GitHub for schema repo, Slack/Teams channel, Notion/Confluence for docs
Core Principles
- Backward Compatibility First: No breaking changes without 12+ months notice.
- Automation Over Manual Review: 90%+ enforcement via CI gates.
- Transparency: All decisions public in schema repo.
1. Compatibility Rules (Compat Rules)
Defines allowable schema changes to preserve contract stability. Enforced via automated tools (e.g.,
graphql-schema-diff,openapi-diff, or custom scripts).Breaking Changes (🚫 Forbidden without deprecation)
Change Type Example Impact Remove field/type Delete user.emailClients fail Rename field/type user.name→user.fullNameClients fail Change type String→IntParsing errors Make required optional → required ?address→addressValidation fails Change enum values Add/remove enum case without prefix Enum mismatches Non-Breaking Changes (✅ Allowed)
Change Type Example Notes Add optional field Add user.phone?: StringClients ignore Add enum value Add STATUS_PENDINGClients handle unknown Deprecate field Mark @deprecatedClients warned Add description/docs Update field comment Improves DX Reorder fields In JSON/GraphQL Order-agnostic Forward Compatibility Rules
- New fields must default to
null/optional. - Enum additions must use underscore-prefix (e.g.,
_NEW_VALUE) for safe client handling.
Rule Enforcement: Schema diffs must pass CI gates (see below). Manual overrides require council approval via GitHub PR label:
sgc/breaking-change.
2. CI Gates
Automated pipeline gates in GitHub Actions / GitLab CI to block invalid schema changes. Runs on every PR to schema repo.
Gate Pipeline Stages
# Example GitHub Actions Workflow Snippet name: Schema Governance CI on: [pull_request] jobs: compat-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Schema Diff Tools run: npm i -g @graphql-inspector/cli openapi-diff # Or equivalent - name: Check Backward Compat run: | graphql-inspector diff schema.old.json schema.new.json --require-compatible openapi-diff old.yaml new.yaml --breaking-only # Fail on breaks - name: Validate Deprecations run: ./scripts/check-deprecations.sh # Custom: Ensure breaks have notices - name: Lint Docs run: spectral lint schema.yaml # Spectral/OpenAPI linting - name: Generate Changelog if: github.event_name == 'pull_request' run: ./scripts/gen-changelog.py > CHANGELOG.mdGate Outcomes
Status Action Labels ✅ All Pass Auto-merge if <3 reviewers sgc/approved⚠️ Warnings (e.g., new deprecations) Require 1 approver sgc/review❌ Breaks Detected Block merge sgc/blocked+ Slack alertCoverage Target: 100% of PRs. Fallback: Manual council review for tool failures.
3. Deprecation Notices
Structured process for sunsetting schema elements. No removal without 12-month runway.
Deprecation Lifecycle
-
Mark Deprecated (Day 0):
- Add
@deprecated(reason: "Use user.fullName instead", since: "2024-10-01") - CI auto-generates notice in PR description.
- Add
-
Notify (Immediate):
- Slack:
#schema-changeschannel post. - Email: API consumers list.
- Webhook: To monitoring tools (e.g., PagerDuty if critical).
- Slack:
-
Milestones:
Phase Timeline Action Announce PR merge Mark + notify Warn 6 months Client-side warnings enforced Soft-Remove 12 months Ignore in responses (log usage) Hard-Remove 18 months Delete; new major version -
Tracking:
- Dedicated GitHub Issue template:
sgc/deprecation-{field}-{date}. - Usage Metrics: Integrate with schema registry (e.g., Apollo Studio) to track adoption.
- Dedicated GitHub Issue template:
Template:
## Deprecation: user.email **Reason**: Migrating to verified emails. **Replacement**: user.verifiedEmail **Timeline**: - Deprecated: 2024-10-01 - Remove: 2025-10-01 **Impact**: Affects 5% of queries (per metrics).
4. Documentation (Docs)
Living docs auto-generated and human-curated. Hosted in schema repo + public site (e.g., ReadMe.io, GitHub Pages).
Standards
- Schema-Level: Every field/type must have
description: "...". - ChangeLog: Auto-generated per release (e.g., via
semantic-release). - Guides:
Doc Type Location Update Trigger Full Schema Reference /docs/reference.md(auto-gen viagraphql-docs)Every merge Migration Guides /docs/migrations/On deprecation PR Best Practices /docs/governance.md(this doc!)Council approval Changelog CHANGELOG.mdCI gate
Generation Workflow
# Post-merge hook npm run generate-docs # SpectaQL/GraphQL Docs → Markdown git add docs/ && git commit -m "docs: regenerate"Accessibility
- Public repo:
schemas.trailblazerlabs.com - Versioned:
v1.2.3/schema.graphql - Searchable: Integrate with Algolia.
Getting Started
- Repo Setup: Fork/create
org/schemaswith this framework. - Onboard Team: First council meeting to ratify rules.
- Pilot: Apply to 1 schema; measure breakage (target: 0%).
Contact: Ping
@sherlock-aiin Slack for customizations. This framework is evolvable—propose changes via PR! 🕵️♂️
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.