Event Schema Design Review Prompt Template

This prompt is for platform engineers and architects who need a structured, automated first-pass review of an event schema before it is registered, versioned, or put into production. The job-to-be-done is a systematic critique of a draft schema—in JSON Schema, Avro, or Protobuf format—against evolvability, backward compatibility, semantic clarity, and versioning criteria. It is designed to be used during design review, as a pre-commit gate in CI, or as a preparatory step before a human architecture review. The prompt assumes you have a complete draft schema and want to surface risks that are expensive to fix once producers and consumers are live.

Use this prompt when you need to catch common schema defects early: ambiguous field names, missing required fields, incompatible type changes, unclear enumeration semantics, and versioning gaps that would break downstream consumers. It is particularly valuable in environments with multiple producer and consumer teams where a single breaking change cascades across the system. The prompt works best when you provide the full schema text, the intended compatibility model (e.g., BACKWARD, FORWARD, FULL), and any domain constraints such as naming conventions or field deprecation policies. The output is a structured review with categorized findings, severity ratings, and actionable recommendations—not a binary pass/fail verdict.

Do not use this prompt as a replacement for human architecture review, wire-level serialization compatibility testing, or schema registry validation. It does not validate that your Avro schema produces compatible binary encodings, nor does it test actual consumer deserialization behavior. It is also not suitable for reviewing the business correctness of the event semantics—it can flag that a field named status has no documented enumeration, but it cannot tell you whether the enumeration values match your order lifecycle. For high-risk domains such as financial transactions or healthcare events, always pair this automated review with human approval and evidence grounding. The prompt is a force multiplier for reviewers, not a substitute for architectural judgment.

The prompt below is designed to be pasted directly into your AI tool. It instructs the model to act as a platform architecture reviewer and produce a structured JSON output you can parse in your CI pipeline, design review tool, or schema registry automation. Replace every square-bracket placeholder with your actual schema, constraints, and risk tolerance before use. The prompt forces the model to reason about field semantics, versioning impact, and consumer breakage rather than producing a superficial checklist.

textCopy
You are a platform architecture reviewer specializing in event-driven systems. Your task is to review an event schema for evolvability, backward compatibility, semantic clarity, and operational safety.

## INPUT

Schema to review:
[SCHEMA_DEFINITION]

Schema format (e.g., JSON Schema, Avro, Protobuf, AsyncAPI):
[SCHEMA_FORMAT]

Event type and domain context:
[EVENT_TYPE_AND_DOMAIN]

Known consumers and their compatibility requirements:
[KNOWN_CONSUMERS]

Schema registry or versioning strategy in use:
[VERSIONING_STRATEGY]

## CONSTRAINTS

Apply these review constraints:
[CONSTRAINTS]

Example constraints: "Must maintain backward compatibility for 3 versions", "No required field additions without default values", "All timestamps must be ISO 8601 UTC", "Envelope must include trace-id and correlation-id"

## OUTPUT SCHEMA

Return a single JSON object with this exact structure:
{
  "review_summary": {
    "overall_assessment": "PASS | PASS_WITH_WARNINGS | FAIL",
    "critical_issues_count": 0,
    "warnings_count": 0,
    "suggestions_count": 0
  },
  "findings": [
    {
      "severity": "CRITICAL | WARNING | SUGGESTION",
      "category": "COMPATIBILITY | SEMANTICS | NAMING | VERSIONING | ENVELOPE | OBSERVABILITY | DOCUMENTATION",
      "field_path": "$.field.name or null",
      "description": "Clear explanation of the finding",
      "impact": "What breaks or degrades if this is not addressed",
      "recommendation": "Specific, actionable fix"
    }
  ],
  "compatibility_analysis": {
    "backward_compatible": true,
    "forward_compatible": true,
    "breaking_changes": ["list of breaking changes if any"],
    "consumer_impact": "Description of which consumers are affected and how"
  },
  "semantic_review": {
    "naming_issues": ["ambiguous or inconsistent field names"],
    "missing_fields": ["fields that should exist based on domain context"],
    "type_appropriateness": "Assessment of whether field types match their semantic purpose"
  },
  "versioning_assessment": {
    "versioning_gaps": ["missing version indicators or migration paths"],
    "deprecation_plan": "Assessment of whether deprecated fields have clear removal timelines"
  }
}

## INSTRUCTIONS

1. Parse the schema and identify every field, its type, required/optional status, and default value.
2. For each field, assess whether its name clearly communicates its purpose without domain-internal jargon.
3. Check whether adding, removing, or changing any field would break existing consumers.
4. Verify that the schema includes necessary metadata fields (trace-id, correlation-id, timestamp, event-type, version).
5. Flag any field whose type is technically valid but semantically wrong (e.g., string for a timestamp, integer for an enum).
6. If the schema is a new version of an existing event, verify that the versioning strategy is explicit and safe.
7. Do not invent issues. Only flag real problems you can justify from the schema content.
8. If no issues exist, return PASS with empty findings arrays.

How to adapt this prompt: Replace [SCHEMA_DEFINITION] with the actual schema text. If you're reviewing an Avro schema, set [SCHEMA_FORMAT] to "Avro" and the model will apply Avro-specific compatibility rules. For [CONSTRAINTS], add your organization's specific rules such as field naming conventions, required envelope fields, or compatibility windows. The [KNOWN_CONSUMERS] field is critical: listing which services consume this event helps the model assess real breakage risk rather than theoretical compatibility. If you have no consumers yet, state that explicitly so the model focuses on forward-looking design quality.

What to do next: After pasting the prompt with your placeholders filled, run the output through a JSON schema validator to confirm the structure matches the OUTPUT_SCHEMA contract. For high-risk events in production systems, route CRITICAL findings to a human reviewer before merging schema changes. Store the review output alongside your schema version in the registry for auditability. If the model returns a FAIL assessment, do not proceed with deployment until every CRITICAL finding is resolved or explicitly accepted with a documented rationale.

This prompt is designed to be called programmatically as part of a schema review pipeline, not as a one-off chat interaction. The typical integration point is a CI step that triggers when a new schema version is proposed in your schema registry (e.g., after an avsc, .proto, or AsyncAPI document is committed to a branch). The harness should extract the schema text, the previous version if available, and any consumer compatibility requirements, then assemble the prompt with these inputs and parse the structured review output for automated gating decisions.

Input assembly: Before calling the model, collect three required inputs: [EVENT_SCHEMA] (the full schema definition text), [PREVIOUS_SCHEMA] (the prior version for diff-based compatibility checks, or null for initial versions), and [DOMAIN_CONTEXT] (a brief description of the event's business purpose and known consumers). Optionally, provide [COMPATIBILITY_RULES] if your organization enforces specific rules beyond semantic best practices (e.g., 'no field removal allowed', 'new fields must have defaults'). The harness should validate that the schema parses successfully before sending it to the model—sending unparseable schemas wastes tokens and produces unreliable reviews.

Model choice and configuration: Use a model with strong structured output capabilities and a large context window. Set temperature=0 or very low (0.0–0.1) to maximize consistency across reviews. Enable structured output mode if your provider supports it, binding the response to a schema with fields: compatibility_assessment, semantic_clarity_issues, evolution_risks, missing_required_fields, naming_concerns, versioning_gaps, and overall_verdict (pass/caution/fail). If structured output isn't available, append explicit format instructions to the prompt and validate the JSON response before processing.

Validation and retry logic: After receiving the model response, validate that all required fields are present and that the overall_verdict is one of the expected enum values. If validation fails, retry once with the same prompt. If the second attempt also fails, log the raw response, flag the review as 'inconclusive', and require human review. For high-risk domains (financial events, healthcare data, auth events), always require human sign-off on fail verdicts and consider requiring it for caution verdicts as well. Never auto-merge schema changes that receive a fail verdict.

CI integration pattern: In a GitHub Actions or similar CI pipeline, the harness should: (1) detect changed schema files, (2) for each changed schema, fetch the previous version from the main branch or schema registry, (3) call the model with the assembled prompt, (4) parse and validate the response, (5) post the review as a PR comment with the structured findings, and (6) set a commit status of success (pass), neutral (caution), or failure (fail). Store the full prompt and response as CI artifacts for auditability. Teams should review the first 10–20 automated reviews manually to calibrate thresholds before relying on automated gating.