Kafka Schema Evolution Review

Reviews schema changes for compatibility and evolution best practices. A single breaking schema change can take down every consumer of a topic.

Target environment: $ARGUMENTS

Workflow

Copy this checklist and track your progress:

Schema Review Progress:
- [ ] Step 1: Fetch registered schemas
- [ ] Step 2: Scan codebase for schema files
- [ ] Step 3: Detect breaking changes
- [ ] Step 4: Check schema quality
- [ ] Step 5: Check schema drift
- [ ] Step 6: Generate report

1. Fetch registered schemas from the live cluster via Lenses MCP
2. Scan codebase for schema definition files (see references/compatibility-rules.md for file types)
3. Detect breaking changes against compatibility rules in references/compatibility-rules.md
4. Check schema quality against best practices
5. Check schema drift between repo and cluster
6. Report findings with migration guidance

Step 1: Fetch Registered Schemas

Use Lenses MCP tools to get the current state of schemas in the cluster:

• listtopicmetadata - get all schemas registered against topics (key and value)
• gettopicmetadata - get the current schema for a specific topic
• get_dataset - get dataset field-level details, policies and governance metadata
• listdatasets with schemaformat filter - find all topics using a given format (AVRO, JSON, PROTOBUF)

Expected output: Map of topics to their registered schemas (key and value) with format and version info.

Validation: If no schemas are registered, note this as a governance gap and proceed with codebase-only analysis.

Step 2: Codebase Inspection

Search the codebase for schema definition files. Consult references/compatibility-rules.md for the full list of file types and search patterns.

Use git diff to identify recently changed schema files if reviewing a PR.

Step 3: Compatibility Checks

For each schema change, evaluate against the compatibility rules in references/compatibility-rules.md. Check backward, forward and full compatibility depending on the topic's configured compatibility level.

Step 4: Schema Quality Checks

Apply the quality checks from references/compatibility-rules.md:

• Fields without documentation annotations
• Missing default values on optional fields
• Inconsistent naming conventions
• Unused or overly generic field names

Step 5: Schema Drift Detection

Compare schema files in the repo against schemas registered in the cluster:

• Use execute_sql to sample live data and verify it matches the expected schema
• Flag schemas in the repo that differ from what's registered
• Flag topics with registered schemas that have no corresponding file in the repo

Success Criteria

Quantitative

• Triggers on 90% of schema-related queries (test with 10-20 varied phrasings)
• Completes review in under 12 tool calls (MCP + codebase search)
• 0 false positives on breaking change detection

Qualitative

• Breaking changes include clear migration guidance
• Schema drift is reported with both repo and cluster versions
• Quality findings are actionable without external documentation

Examples

Example 1: Pre-merge schema review

User says: "Review the schema changes in this PR"

Actions:

1. Run git diff to find changed .avsc, .proto or .json schema files
2. Fetch the currently registered schema from the cluster via Lenses MCP
3. Evaluate each change against compatibility rules

Result: Report listing any breaking changes with migration guidance

Example 2: Full schema audit

User says: "Audit all schemas in the staging environment"

Actions:

1. Fetch all registered schemas via listtopicmetadata
2. Scan the codebase for schema files
3. Check for drift between repo and cluster
4. Run quality checks on all schemas

Result: Comprehensive report covering compatibility, quality and drift

Example 3: Investigating a consumer failure

User says: "Consumers are failing to deserialise messages from orders.payment.completed"

Actions:

1. Fetch the registered schema for that topic via gettopicmetadata
2. Sample live data with execute_sql to see actual message format
3. Compare against the schema file in the repo

Result: Diagnosis of schema mismatch with remediation steps

Troubleshooting

No schemas registered in the cluster

Cause: Schema Registry is not configured or topics use schemaless formats (plain JSON, CSV). Solution: This is a valid finding - report it as a governance gap rather than an error. Recommend adding schema registration.

Schema drift detected but intentional

Cause: The cluster schema was updated independently of the repo (e.g., via Schema Registry UI). Solution: Report the drift and recommend syncing the repo to match the cluster as the source of truth.

Cannot sample data with execute_sql

Cause: Topic is empty, permissions are restricted or the topic uses an unsupported format. Solution: Note the limitation in the report. Use gettopicmetadata as a fallback for schema information.

Output Format

## Schema Review Report

### Environment: {name}

### Breaking Changes (must fix before merge)
- [schema-file] Description of the breaking change
  Affected topics: {list}
  Migration: {guidance}

### Compatibility Warnings
- [schema-file] Description of the issue
  Recommendation: How to fix it

### Schema Quality
- [schema-file:field] Description of the quality issue
  Recommendation: How to improve it

### Schema Drift
- [topic-name] Schema in repo differs from registered schema
  Repo version: {summary} | Cluster version: {summary}

### Summary
- X breaking changes found
- Y compatibility warnings found
- Z quality issues found
- Schema files scanned: N
- Topics with drift: M