Domain Event Schema Design Review Prompt

Domain event schemas are contracts between bounded contexts. A poorly designed event creates coupling, breaks consumers, and hides causation. This prompt acts as a design reviewer that critiques an event schema before it reaches a schema registry or gets implemented in a producer. Use it when a platform engineer or domain architect proposes a new event type, modifies an existing event, or audits a catalog of events for consistency. The prompt assumes you have a draft schema in JSON, Avro, or Protobuf format and want a structured critique covering naming conventions, payload design, versioning strategy, enrichment decisions, and ordering assumptions.

The prompt is not a replacement for consumer-driven contract testing or schema registry compatibility checks. It is a design-time guardrail that catches fat events, missing causation identifiers, and implicit ordering dependencies before they become runtime incidents. For example, if a OrderPlaced event embeds the entire customer profile and shopping cart snapshot, the prompt will flag it as a fat event that couples consumers to producer internals. If an event lacks a correlationId or causationId, the prompt will call out the missing causation chain that makes debugging and tracing impossible in production. If the schema implies consumers must process events in a specific sequence without an explicit ordering key, the prompt will surface that hidden assumption.

Do not use this prompt for runtime schema validation, consumer compatibility testing, or performance benchmarking. It does not replace a schema registry's compatibility rules, nor does it simulate consumer behavior under load. Use it early in the design process, before implementation, and pair it with a schema registry check and at least one consumer-driven contract test before deploying to production. For high-risk domains such as finance or healthcare, always route the prompt's output through a human architect review before finalizing the schema.

The following prompt template is designed to be copied directly into your AI workflow. It provides a structured framework for reviewing domain event schemas, covering naming conventions, payload design, versioning strategy, and enrichment patterns. Replace each square-bracket placeholder with your specific event schema, domain context, and review constraints before running the prompt.

codeCopy
You are a domain event schema design reviewer. Your task is to critique the provided domain event schema and produce a structured review report.

## EVENT SCHEMA TO REVIEW
[EVENT_SCHEMA]

## DOMAIN CONTEXT
[DOMAIN_CONTEXT]

## REVIEW CRITERIA
Evaluate the schema against the following dimensions:

1. **Naming and Semantics**: Does the event name clearly communicate what happened in domain language? Are field names consistent with the ubiquitous language? Flag any ambiguous or technical-only naming.

2. **Payload Design**: Is the payload complete enough for consumers without being a fat event? Check for missing required fields, overly large payloads, and fields that belong in a different event or context.

3. **Versioning and Evolution**: Does the schema include a version indicator? Assess backward compatibility risks if fields are added, removed, or changed. Flag any implicit versioning assumptions.

4. **Causation and Correlation**: Does the event include causation ID, correlation ID, and event ID? Check that consumers can reconstruct causal chains and correlate related events.

5. **Enrichment Strategy**: Is the event self-contained enough for common consumers, or does it force excessive lookups? Identify fields that should be enriched at source versus fields consumers should fetch.

6. **Ordering Assumptions**: Does the schema imply or require ordering guarantees? Flag any assumptions about total ordering, exactly-once delivery, or synchronous processing.

7. **Schema Registry Compatibility**: If using a schema registry, assess compatibility with common registry formats (Avro, JSON Schema, Protobuf). Flag type choices that cause serialization problems.

## OUTPUT FORMAT
Produce a JSON review report with this structure:

{
  "overall_assessment": "PASS | NEEDS_REVISION | FAIL",
  "summary": "2-3 sentence summary of key findings",
  "findings": [
    {
      "severity": "BLOCKER | HIGH | MEDIUM | LOW",
      "dimension": "Naming | Payload | Versioning | Causation | Enrichment | Ordering | Compatibility",
      "description": "Specific finding with evidence from the schema",
      "recommendation": "Actionable fix or design change"
    }
  ],
  "risks": [
    {
      "risk": "Description of production risk if not addressed",
      "likelihood": "HIGH | MEDIUM | LOW",
      "impact": "HIGH | MEDIUM | LOW"
    }
  ],
  "versioning_notes": "Specific guidance on versioning strategy for this schema"
}

## CONSTRAINTS
- Only flag issues you can point to in the provided schema. Do not invent problems.
- If the schema is incomplete, note what is missing rather than assuming defaults.
- For [RISK_LEVEL] workflows, require human review before publishing events to production.
- If the schema appears production-ready with no significant issues, say so clearly.

Adaptation guidance: Replace [EVENT_SCHEMA] with the actual schema definition in JSON Schema, Avro, Protobuf, or a structured description. Replace [DOMAIN_CONTEXT] with a brief description of the bounded context, the event's purpose, and any known consumer requirements. Replace [RISK_LEVEL] with HIGH for financial, compliance, or safety-critical domains to enforce human review requirements. For low-risk internal events, you can remove or relax the human review constraint. If you have specific organizational standards for event schemas, add them as additional review criteria before the output format section.

This prompt is designed to be called programmatically as part of a schema registry CI check or an internal developer portal review workflow. The primary integration point is a pre-merge or pre-registration gate: when a team proposes a new event schema or a version bump, the application sends the schema definition, the owning bounded context, and any consumer registry metadata to the model. The model returns a structured critique that your harness can parse, log, and act on before the schema is published. Do not use this prompt for runtime event validation; it is a design-time review tool, not a production event filter.

Wire the prompt into a lightweight service or CI job that constructs the [EVENT_SCHEMA] input from your schema registry (Avro, JSON Schema, or Protobuf descriptor), populates [BOUNDED_CONTEXT] from your service catalog, and injects [CONSUMER_REGISTRY] by querying which downstream services subscribe to this event type. The harness must enforce a strict JSON output contract: parse the model response, validate it against the expected schema (fields like critique.categories, critique.severity, critique.recommendation), and retry once with a repair prompt if parsing fails. Log every review result—including model, prompt version, schema version, and parsed critique—to an audit table so you can track review quality over time. For high-risk domains (finance, healthcare, auth), add a human approval gate: if the critique contains any severity: "BLOCKER" finding, prevent automatic merge and route to a designated reviewer queue.

Model choice matters here. Use a model with strong structured output support and a large context window if your schemas include verbose Protobuf descriptors or extensive consumer metadata. Enable JSON mode or structured outputs if your provider supports it; otherwise, include a repair step that strips markdown fences and retries parsing. Avoid running this prompt on every commit if schemas haven't changed—cache the last review result keyed by schema fingerprint (hash the normalized schema content). The next step after implementation is to build an eval set: collect 20–30 real schemas with known issues (fat events, missing causation IDs, ambiguous enum values) and verify the prompt catches them consistently before you trust the automation.