9 views
EventBridge makes publishing easy and breaking consumers even easier. A renamed field or tightened enum ships in minutes; twenty Lambdas fail overnight. Senior teams treat event schemas like public APIs: additive evolution, defaults on read, and contract tests that fail the producer’s PR before the bus sees the payload.
⚡ TL;DR: Register schemas; allow add-optional-field only by default. Consumers must ignore unknown fields and default missing optionals. Version major only on break; dual-publish during migration. Pair with DynamoDB Streams Outbox and CQRS Boundary Criteria.
EventBridge Schema Evolution: production guidance
json
{
"$id": "order.placed.v1",
"type": "object",
"additionalProperties": true,
"required": ["orderId", "customerId", "total", "currency"],
"properties": {
"orderId": { "type": "string", "format": "uuid" },
"customerId": { "type": "string" },
"total": { "type": "integer", "minimum": 0 },
"currency": { "type": "string", "enum": ["USD", "EUR", "INR"] },
"promoCode": { "type": "string" }
}
}
python
❌ Shipping # ci/schema_diff.py
BREAKING = {"remove_required", "rename", "narrow_type", "remove_enum_value"}
def classify(old: dict, new: dict) -> str:
# illustrative — use json-schema-diff / buf breaking in real CI
removed_req = set(old.get("required", [])) - set(new.get("required", []))
if removed_req:
return "breaking"
# ✅ Adding optional properties is additive
return "additive"
currency from string to {code, precision} in place — that is a major version, not a “cleanup.”
Consumer defaults and unknown fields
typescript
// consumers/orderPlaced.ts
type OrderPlacedV1 = {
orderId: string;
customerId: string;
total: number;
currency: "USD" | "EUR" | "INR";
promoCode?: string;
};
export function parseOrderPlaced(raw: unknown): OrderPlacedV1 {
const e = raw as Record<string, unknown>;
// ✅ Ignore unknown keys; default optionals
return {
orderId: String(e.orderId),
customerId: String(e.customerId),
total: Number(e.total),
currency: e.currency as OrderPlacedV1["currency"],
promoCode: e.promoCode ? String(e.promoCode) : undefined,
};
}
Dual-publish for major migrations
| Phase | Producer | Consumers |
|---|---|---|
| 0 | v1 only | all on v1 |
| 1 | v1 + v2 (same transaction / outbox) | migrate one-by-one |
| 2 | v2 only when %v1 consumers = 0 | v2 |
| 3 | remove v1 schema from registry | — |
order.placed and order.placed.v2) so you never fork business transactions.
Contract tests on the producer PR
typescript
// __tests__/events.contract.test.ts
import { schemas } from "../schemas";
import { buildOrderPlaced } from "../producers/orders";
test("order.placed matches registry schema", () => {
const evt = buildOrderPlaced(sampleOrder);
expect(() => schemas["order.placed.v1"].validate(evt)).not.toThrow();
});
test("consumer fixture corpus still parses", () => {
for (const fix of loadCorpus("order.placed")) {
expect(() => parseOrderPlaced(fix)).not.toThrow();
}
});
Closing checklist
✅ Dos – ✅ Put schemas in registry / repo with review – ✅ Allow only additive changes on minor versions – ✅ Consumers ignore unknowns and default optionals – ✅ Dual-publish across major migrations – ✅ Fail producer CI on breaking schema diffs ❌ Don’ts – ❌ Don’t rename fields in place – ❌ Don’t require new fields without a defaulting window – ❌ Don’t parse withas any and hope
– ❌ Don’t delete detail-types while consumers remain
– ❌ Don’t evolve enums by silently removing values
Related reading
- DynamoDB Streams Outbox: Domain Events Without Dual-Write Failures
- CQRS Boundary Criteria: When Separate Models Finally Earn Complexity Tax
- Idempotency Keys End-to-End
- Lambda Test Events as Contracts
Watch: 100 Days of AI on YouTube
Short videos from CheatCoders, one AI engineering topic per day.
Most viewed
- Python Decorators Explained: From Simple Wrappers to Production Patterns
- Claude Code vs Cursor vs GitHub Copilot: Choose by Workflow, and Set Up One Repo That Works With All Three
- AI Agent Frameworks in 2025: LangGraph vs CrewAI vs AutoGen vs Raw API
- Python String Methods: Every str Method With Real Production Examples
- Css Animation Performance: Performance-Optimized Motion for Modern UIs
Newly added
- AWS Systems Manager Parameter Store: Hierarchical Runtime Config for Coding Agents
- Amazon Cognito Identity Pools: Federate Coding-Agent Tool Callers Without Long-Lived Keys
- Amazon Athena for Coding Agents: Query Tool Audit Logs and Eval Traces on S3 Without a Warehouse
- AWS Batch for Coding Agents: Parallel Overnight PR Reviews and Long-Running Jobs Without Lambda Timeouts
- Amazon Bedrock Prompt Management: Version and A/B Test Coding-Agent System Prompts
Deep-dive PDF
Get the expanded guide for this post — extra diagrams-style checklists, failure modes, and a production walkthrough. Free when you subscribe to CheatCoders.
Already subscribed? or open the subscribe page.
Discover more from CheatCoders
Subscribe to get the latest posts sent to your email.
