Event Versioning and Evolution Prompt

This prompt is designed for platform engineers and architects who are planning a change to an event schema in a production system with multiple independent consumers. The core job-to-be-done is generating a structured, decision-support assessment that compares versioning strategies, evaluates forward and backward compatibility, and outlines a concrete consumer migration path. Use it when you are adding an optional field, removing a deprecated field, changing a data type, restructuring a nested payload, or deprecating an entire event type. The prompt assumes you have a current schema definition, a proposed new schema definition, and a list of known downstream consumers. It does not require a running schema registry, but it produces output that should be validated against your registry's compatibility rules before implementation.

Do not use this prompt for greenfield schema design where no existing consumers exist, as the versioning and migration assessment adds unnecessary complexity. Do not use it as a substitute for automated schema compatibility checks in your CI/CD pipeline; it is a design review tool, not a build gate. The prompt is also inappropriate for evaluating infrastructure-level changes like broker upgrades, partition count adjustments, or serialization format migrations (e.g., Avro to Protobuf), which require different analysis frameworks. If you are changing a schema that has no consumers yet, use the Event Schema Design Review Prompt instead. If you are choosing between serialization formats, use the Message Serialization Format Decision Prompt.

Before running this prompt, gather the current event schema, the proposed schema, a list of consumer teams or services, and any known constraints like regulatory retention requirements or SLAs. The prompt will ask you to specify a risk level, which controls the depth of analysis: low-risk changes (adding an optional field) get a lightweight compatibility check, while high-risk changes (removing a required field) trigger a full migration plan with rollback analysis. The output is a decision-support document, not executable code. After receiving the assessment, review it with consumer teams, validate the compatibility claims against your schema registry, and use the migration plan as input to your release coordination process. Never ship a breaking change based solely on this prompt's output without contract testing against real consumer code.

This prompt template is designed to be pasted directly into your AI system. It instructs the model to act as a distributed systems architect and produce a structured versioning strategy assessment. The template uses square-bracket placeholders that you must replace with your specific context, such as the current and proposed event schemas, your system's compatibility requirements, and your organization's operational constraints.

textCopy
You are a principal engineer specializing in event-driven architectures and schema evolution. Your task is to produce a structured versioning strategy assessment for an event schema change.

## Input
- **Current Event Schema:** [CURRENT_SCHEMA]
- **Proposed Event Schema:** [PROPOSED_SCHEMA]
- **System Context:** [SYSTEM_CONTEXT]
- **Consumer Registry:** [CONSUMER_REGISTRY]
- **Operational Constraints:** [OPERATIONAL_CONSTRAINTS]

## Output Schema
Return a JSON object with the following structure:
{
  "compatibility_assessment": {
    "backward_compatible": boolean,
    "forward_compatible": boolean,
    "breaking_changes": [
      {
        "field": "string",
        "change_type": "string (e.g., removal, type_change, semantic_change)",
        "impact": "string",
        "affected_consumers": ["string"]
      }
    ]
  },
  "versioning_strategy": {
    "recommended_approach": "string (e.g., dual-publish, schema-registry-upgrade, tolerant-reader)",
    "deprecation_timeline": "string",
    "consumer_migration_plan": [
      {
        "consumer_id": "string",
        "required_action": "string",
        "deadline": "string",
        "risk_level": "string (low, medium, high)"
      }
    ]
  },
  "failure_modes": [
    {
      "scenario": "string",
      "detection_mechanism": "string",
      "mitigation": "string"
    }
  ],
  "recommendation": "string"
}

## Constraints
- Flag any change that could cause silent data loss or deserialization failures.
- If a breaking change is unavoidable, require a dual-publish period with a clear deprecation window.
- For each consumer, specify whether it requires a code change, configuration update, or no action.
- Include failure mode checks for: poison messages, schema registry mismatch, and consumer lag during migration.
- If the risk level for any consumer is "high," recommend a rollback plan.

To adapt this prompt, replace the placeholders with concrete details. [CURRENT_SCHEMA] and [PROPOSED_SCHEMA] should contain the full schema definitions, ideally in JSON Schema, Avro, or Protobuf format. [CONSUMER_REGISTRY] is a critical input: provide a list of all known consumers, their owners, and their current schema expectations. If this registry is incomplete, the assessment will have blind spots. [OPERATIONAL_CONSTRAINTS] should include your deployment windows, rollback capabilities, and any SLAs that limit downtime. After generating the output, validate the JSON structure before integrating it into your decision process. For high-risk migrations, always have a human architect review the breaking_changes and failure_modes arrays before executing the plan.

This prompt is designed to be a decision-support tool within a formal architecture review process, not a standalone oracle. The primary integration point is a pull request or design document review workflow where an architect or platform engineer submits a proposed schema change alongside the current schema, consumer registry, and deprecation policy. The prompt's output should be treated as a structured analysis artifact that feeds into a human-led decision meeting or an Architecture Decision Record (ADR).

To wire this into an application, wrap the prompt in a function that accepts the required inputs: [CURRENT_SCHEMA], [PROPOSED_SCHEMA], [CONSUMER_REGISTRY], and [DEPRECATION_POLICY]. The application layer should first validate that all inputs are non-empty and that the schemas are parseable JSON or Avro/Protobuf definitions. Before calling the model, run a deterministic pre-check for obvious breaking changes (e.g., field removal, type narrowing) using a schema diffing library like json-schema-diff-validator or an Avro compatibility checker. This pre-check serves as a baseline to compare against the model's analysis and helps detect hallucinations. After receiving the model's output, validate the JSON structure against a strict schema that requires the compatibility_assessment, breaking_changes, migration_steps, and risk_evaluation fields. If validation fails, retry once with the validation error injected into the prompt as additional context. Log every input, output, and validation result to an audit trail for governance review.

For high-risk systems (financial ledgers, healthcare events, auth events), the output must be routed to a human review queue before any schema migration is approved. The review interface should display the model's analysis alongside the deterministic diff, allowing the reviewer to accept, reject, or amend each finding. Do not automate schema registry updates based solely on the model's output. The next step after a successful review is to generate an ADR from the trade_off_summary field and attach the full analysis as an appendix. Avoid using this prompt for trivial additive changes like adding an optional field with a default value; those should be handled by automated CI checks to prevent review fatigue.