Streaming Schema Registry Compatibility Prompt

Use this prompt when a data platform team submits a schema change for a topic governed by a schema registry, such as Confluent Schema Registry, AWS Glue, or Apicurio. The prompt's job is to validate the proposed schema against the currently registered version and the declared compatibility mode (BACKWARD, FORWARD, FULL, and their transitive variants). It produces a structured compatibility report that goes far beyond a binary pass/fail check. The report identifies breaking changes, field additions, default value gaps, type promotions, and the required consumer upgrade order. This is the artifact that turns a silent registry rejection into an actionable plan for the engineering team responsible for the change.

This prompt is designed to be a gate in a CI/CD pipeline or a mandatory step in a schema review workflow. The ideal user is a data engineer, a platform engineer, or a backend developer who has authored a new .avsc, .proto, or JSON Schema file and needs to register it. The required context includes the full text of the proposed schema, the full text of the latest registered schema, and the declared compatibility mode. Without all three, the prompt cannot perform a meaningful analysis. The prompt does not replace the registry's own compatibility check; instead, it adds the human-readable reasoning, consumer impact analysis, and upgrade sequencing that the registry's opaque pass/fail does not provide. This makes it a critical tool for teams practicing zero-downtime deployments with streaming data.

Do not use this prompt for simple format validation, for schemas that are not yet registered, or as a substitute for integration tests. It is not a schema linting tool. It is also not a replacement for a human review when a FULL_TRANSITIVE compatibility check fails; in such cases, the prompt's report should be a starting point for an architectural discussion, not the final word. The prompt's value is in its structured, deterministic reasoning about field-level changes. When you integrate it, ensure your harness provides the exact registered schema version, not a stale cached copy, as the entire analysis hinges on a correct diff. After the report is generated, the next step is to attach it to the schema change request and use the consumer upgrade order to sequence deployments safely.

This prompt template is designed to be pasted directly into your AI harness. It instructs the model to act as a schema registry compatibility reviewer, comparing a proposed schema change against the current schema and the registry's compatibility configuration. The model must identify breaking changes, classify compatibility violations (BACKWARD, FORWARD, FULL, NONE), and produce a structured report that a CI/CD pipeline can parse. Before using this prompt, ensure your harness has access to both the current and proposed schema definitions, along with the registry's configured compatibility type. If your harness passes schemas as separate structured objects rather than inline text, adjust the [CURRENT_SCHEMA] and [PROPOSED_SCHEMA] placeholders to reference those objects by name or ID.

textCopy
You are a schema registry compatibility reviewer for a streaming data platform. Your task is to compare a proposed schema change against the current registered schema and determine whether the change violates the configured compatibility rules.

## INPUTS
- Current registered schema: [CURRENT_SCHEMA]
- Proposed new schema: [PROPOSED_SCHEMA]
- Schema format: [SCHEMA_FORMAT: AVRO | PROTOBUF | JSON_SCHEMA]
- Configured compatibility type: [COMPATIBILITY_TYPE: BACKWARD | FORWARD | FULL | BACKWARD_TRANSITIVE | FORWARD_TRANSITIVE | FULL_TRANSITIVE | NONE]
- Subject name: [SUBJECT_NAME]

## TASK
1. Parse both schemas according to the specified format.
2. Identify every field-level change: additions, removals, renames, type changes, default value changes, and logical type modifications.
3. For each change, determine whether it violates the configured compatibility type.
4. Classify each violation as BREAKING or NON-BREAKING under the configured compatibility rules.
5. For breaking changes, specify the consumer upgrade ordering requirement (e.g., "consumers must upgrade before producers").

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "compatibility_check": {
    "subject": "string",
    "compatibility_type": "string",
    "overall_result": "COMPATIBLE | INCOMPATIBLE",
    "changes": [
      {
        "field_path": "string",
        "change_type": "FIELD_ADDED | FIELD_REMOVED | TYPE_CHANGED | DEFAULT_CHANGED | RENAMED | LOGICAL_TYPE_CHANGED",
        "current_definition": "string | null",
        "proposed_definition": "string | null",
        "compatibility_impact": "BREAKING | NON_BREAKING",
        "violated_rule": "string | null",
        "consumer_action": "UPGRADE_BEFORE_PRODUCER | PRODUCER_UPGRADE_BEFORE_CONSUMER | NO_ACTION | ROLLING_UPGRADE_SAFE",
        "explanation": "string"
      }
    ],
    "recommended_migration_order": "string",
    "rollback_risk": "LOW | MEDIUM | HIGH",
    "rollback_notes": "string | null"
  }
}

## CONSTRAINTS
- Do not hallucinate fields that are not present in either schema.
- If a field is renamed, you must detect it as a removal of the old name and an addition of the new name, and flag it as BREAKING unless the schema format supports aliases.
- For AVRO, treat union type narrowing (removing a type from a union) as BREAKING for BACKWARD compatibility.
- For PROTOBUF, field number reuse is always BREAKING regardless of compatibility type.
- If the compatibility type is NONE, report all changes as NON_BREAKING but still list them.
- If you cannot parse either schema, return a single error object: {"error": "PARSE_FAILURE", "detail": "..."}

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL: LOW | MEDIUM | HIGH | CRITICAL]

To adapt this template for your environment, replace the square-bracket placeholders with actual values before execution. The [EXAMPLES] placeholder should contain 2-3 few-shot examples of correct compatibility assessments for your schema format, covering at least one compatible change and one breaking change. The [RISK_LEVEL] placeholder controls the model's conservatism: set it to HIGH or CRITICAL for production pipelines where false negatives (missed breaking changes) are unacceptable, and LOW for development environments where you want to reduce false positives. If your registry enforces transitive compatibility, ensure the [COMPATIBILITY_TYPE] reflects this and that [CURRENT_SCHEMA] includes the last fully-compatible schema, not just the immediate predecessor. After pasting this prompt, validate the output against your registry's actual compatibility check by running the same change through the Confluent Schema Registry or Apicurio Registry API and comparing results. Any discrepancy should trigger a human review of the prompt's reasoning before the change proceeds.

The streaming schema registry compatibility prompt is designed to sit inside a pre-merge or pre-registration pipeline that gates schema changes before they reach the registry. The harness should intercept the proposed schema diff and the target registry's compatibility configuration (e.g., BACKWARD, FORWARD, FULL, BACKWARD_TRANSITIVE) and feed them into the prompt as structured inputs. The model's output is a structured compatibility verdict, not a binary pass/fail. The harness must parse this verdict, extract the compatibility_status, breaking_changes list, and consumer_upgrade_ordering array, and then decide whether to block the pipeline, warn, or auto-approve based on the registry's configured compatibility level and the team's risk policy.

Build the harness as a CI job or a webhook receiver that accepts a schema change event. The harness should first validate inputs: confirm the proposed schema parses correctly against the declared format (Avro, Protobuf, or JSON Schema), confirm the current schema version exists in the registry, and confirm the compatibility level is a recognized value. If validation fails, fail fast with a clear error before calling the model. On model invocation, set temperature=0 and use a structured output mode (JSON mode or function calling) to enforce the output schema. Implement a retry loop with up to 3 attempts if the output fails schema validation or if the model returns a compatibility_status of UNCLEAR. After a successful parse, log the full prompt, response, and parsed verdict to an audit table for downstream review. If the verdict contains breaking_changes with severity HIGH and the registry compatibility level is FULL or BACKWARD_TRANSITIVE, block the pipeline and require human approval via a review ticket that includes the model's explanation and the raw diff. For MEDIUM severity breaking changes under BACKWARD compatibility, auto-warn but allow the pipeline to proceed with a flag for the on-call data platform engineer.

Do not treat the model's output as the sole gate for production schema changes. The harness should cross-reference the model's identified breaking changes against the registry's own compatibility check where available (e.g., Confluent Schema Registry's compatibility API) and flag any disagreement for human review. The prompt is strongest at explaining why a change breaks compatibility and what consumer upgrade ordering is required; it is not a replacement for deterministic compatibility verification. Wire the harness to emit metrics: time-to-verdict, retry count, and human-approval rate. These metrics will help you tune the risk thresholds and decide when the prompt is reliable enough to reduce manual review for low-risk changes.