liveBook · Manning

Schema

As explained in Microservices Patterns, Second Edition

A formal definition of the fields, types, and structural rules of a message or data object.

A schema defines the structure of data, including its fields and types. In an asynchronous API, message schemas form part of a contract that also identifies channels, message types, and whether a service sends or receives messages. section 8.3.5

Schema changes must account for data that already exists. An old event consumer may ignore a newly added attribute, but an updated consumer can still encounter persisted events without it. For Avro, the new schema must specify a default for the attribute or deserialization fails. section 8.3.4

Evolving order events

Adding a coupon ID to an Order Created event requires consumers to handle older events without that attribute. Replacing Order Fulfilled with Order Ready For Pickup and Order Picked Up is a breaking change. During migration, the service can publish all three events until consumers switch, although they may still encounter older events afterward. section 8.3.4

Listing 8.3 An excerpt from an AsyncAPI document that defines a service publishing events such as CustomerCreatedEvent to the com.example.Customer channel.
channels:
  com.example.Customer:
    address: com.example.Customer
    messages:
      com.example.CustomerCreatedEvent:
        $ref: "#/components/messages/com.example.CustomerCreatedEvent"
    ...
messages:
    com.example.CustomerCreatedEvent:
      headers:
        $ref: "#/components/schemas/HeadersNotDocumented"
      payload:
        schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0
        schema:
          $ref: "#/components/schemas/com.example.CustomerCreatedEvent"
      name: com.example.CustomerCreatedEvent
      title: com.example.CustomerCreatedEvent
    ...
components:
  schemas:
   com.example.CustomerCreatedEvent:
      title: CustomerCreatedEvent
      type: object
      properties:
        id:
          type: string
      examples:
        - id: string

operations:
  io.eventuate.exampleapp.events.publisher.CustomerEventPublisherImpl:
    action: send
    channel:
      $ref: "#/channels/com.example.Customer"
    messages:
      - $ref: "#/channels/com.example.Customer/messages/com.example.CustomerCreatedEvent"

The AsyncAPI example links a channel to an event message and references separate schemas for its headers and payload. section 8.3.5

A database schema is also a design decision for a domain module. Modules should normally collaborate through APIs rather than direct database access to reduce coupling; a cross-module SQL join can nevertheless be worthwhile when implementation ease and efficiency outweigh modularity. section 6.2.3

For a CQRS view, design the schema around both queries and event-triggered create, update, and delete operations, rather than copying provider data models. Store data returned by queries, data needed to evaluate them, and data needed to locate records for updates. Decide how to group records, what to precompute, and which indexes to define, balancing read efficiency against update cost. section 13.3.2

Grouping a query view

An order query that returns an order with its ticket and delivery can use one grouped record or gather separate records. Grouping can match the result shape and retrieve it in one read, but schema choices must also support efficient event-handler updates. section 13.3.2

How Microservices Patterns, Second Edition covers it

How deep it goes
Explains compatibility changes and CQRS schema decisions, including defaults, record grouping, precomputation, and indexes.
Examples
Uses order events with coupon IDs and grouped order, ticket, and delivery records.
What you can do after
Evaluate schema changes and CQRS view designs for compatibility and query-update trade-offs.
How it connects
Connects schemas to asynchronous messaging, API compatibility, domain modules, and CQRS views.

Also explained in

Compare how 54 books explain schema →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Microservices Patterns, Second Edition. The section links point to the parts of the book it draws on.