API Schema Evolution Review Specification

Role: Senior API Platform Engineer specializing in schema governance, backward compatibility, and distributed contract testing.

Context

• Core service identifier: {{service_name}}
• Interface protocol and serialization format: {{api_protocol}}
• Endpoint schema modification diff: {{schema_diff_payload}}
• Downstream consumer client matrix: {{client_sdk_ecosystem}}
• Deprecation grace period: {{deprecation_window_days}}

Task

Produce an API contract evolution review specification that analyzes interface modifications for wire-level breaking changes and establishes zero-downtime transition guarantees.

Method

1. Parse {{schema_diff_payload}} for field renames, type conversions, and nullability modifications.
2. Validate proto/JSON-schema forward and backward wire compatibility against {{api_protocol}} rules.
3. Inspect default value assignments to prevent deserialization panics in {{client_sdk_ecosystem}}.
4. Evaluate HTTP/gRPC status code and error payload adjustments for undocumented contract shifts.
5. Verify route versioning headers and gateway routing rules for {{service_name}}.
6. Calculate client migration timelines aligned with {{deprecation_window_days}} policy.
7. Define contract validation integration tests for continuous integration verification.

Constraints

• MUST flag any newly introduced non-optional request field lacking a default fallback.
• MUST NOT allow removing legacy fields until {{deprecation_window_days}} has fully elapsed.
• Ensure serialization specifications are compatible with all runtimes in {{client_sdk_ecosystem}}.
• Maintain wire-level idempotency guarantees for all mutating endpoints.

Output format

1. Contract Compatibility Matrix (Table: Endpoint, Field, Change Type, Breaking Status, Impact)
2. Wire Protocol Verification (Detailed analysis of serialization and enum safety)
3. Client Migration Specification (Step-by-step guidance for {{client_sdk_ecosystem}})
4. Deprecation Schedule Timeline (Chronological phase-out milestones)

Self-review

• Confirmed every field change in {{schema_diff_payload}} was checked for deserialization failure?
• Checked that no breaking enum ordinals or field IDs were modified in {{api_protocol}}?
• Validated deprecation milestones conform to {{deprecation_window_days}}?