Canonical Data Model

In a growing company with 20 microservices, each team models data differently. The order service calls it customer_id. The billing service calls it account_id. The shipping service calls it recipient_id. They all mean the same thing, the person who placed the order, but every integration requires a translation layer.

Now multiply this by every entity in your system: orders, products, addresses, payments. Each service has its own representation, its own field names, its own data types, its own validation rules. Integrating any two services requires a custom adapter. With 20 services, you potentially need 190 adapters (N * (N-1) / 2).

A canonical data model (CDM) defines one standard representation for each business entity. All services agree to use this common language for inter-service communication. The order service still stores data however it wants internally, but when it publishes events or receives commands, it speaks the canonical language.

Instead of 190 point-to-point translations, each service only needs one translation: between its internal model and the canonical model. Twenty translations instead of 190. That's the power of a shared standard.

A CDM is a set of shared schemas that define how business entities look when they cross service boundaries:

// Canonical Order (the shared contract)
interface CanonicalOrder {
 orderId: string; // UUID
 customer: {
 customerId: string;
 email: string;
 name: string;
 };
 items: CanonicalLineItem[];
 pricing: {
 subtotal: number; // Always in smallest currency unit (cents)
 tax: number;
 shipping: number;
 total: number;
 currency: string; // ISO 4217 (e.g., "USD")
 };
 shipping: CanonicalAddress;
 status: 'placed' | 'paid' | 'shipped' | 'delivered' | 'cancelled';
 timestamps: {
 placedAt: string; // ISO 8601
 paidAt?: string;
 shippedAt?: string;
 };
}

Design principles:

1. Use universal standards. ISO 4217 for currencies, ISO 8601 for dates, ISO 3166 for country codes. Don't invent your own conventions.

2. Be explicit about units. Is amount in dollars or cents? Is weight in grams or kilograms? Always specify. Better yet, use the smallest unit (cents, grams) to avoid floating-point issues.

3. Version the schema. The canonical model will evolve. Use schema versioning (Avro, Protobuf with field numbers, or a version field in JSON) so old and new messages coexist.

4. Keep it minimal but complete. Include only fields that cross service boundaries. Internal fields (database IDs, implementation details) stay internal.

5. Use a schema registry. Centralize canonical schema definitions (Confluent Schema Registry, AWS Glue Schema Registry) so all services reference the same source of truth.