Skip to content

3.3 Event Contracts (Avro)

Sprint: Sprint 03 - Platform Starters and Event Contracts
Feature ID: 3.3
Status: DONE (2/2)
Subtasks: 3.3.1 (DONE), 3.3.2 (DONE)

Objective

Deliver "Event Contracts (Avro)" within Sprint 03 - Platform Starters and Event Contracts.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • Sprint 01 (Schema Registry available)
  • 3.3.1

Subtasks

3.3.1 Event envelope and MVP schemas

  • ID: 3.3.1
  • Status: DONE (EventEnvelope + MVP schemas generated and compiled in platform-event-contracts)
  • Title: Define EventEnvelope and core MVP Avro schemas
  • Description: In platform-event-contracts, Avro schemas under src/main/avro/*.avsc, namespace com.telco.platform.events.<domain>. Define shared EventEnvelope.avsc (eventId, eventType, occurredAt timestamp-millis, traceId, correlationId, payload) and the MVP schemas matching the event catalog: customer-registered, customer-kyc-approved, order-created, payment-completed, payment-failed, subscription-activated, subscription-suspended, invoice-generated, quota-threshold-reached, quota-exceeded, ticket-opened. Versioned record names end in V1; fields nullable-friendly for backward compatibility. Generate via avro-maven-plugin.
  • Business Purpose: A single governed schema source for all cross-service events (NFR-16, ADR-019).
  • Inputs: PLATFORM-SPEC Section 7, docs/architecture/event-catalog.md.
  • Outputs: .avsc files + generated Java records.
  • Acceptance Criteria:
  • mvn -q generate-sources produces *V1 Java classes; each schema declares domain.event.v1 naming and nullable defaults.
  • Dependencies: Sprint 01 (Schema Registry available)
  • Complexity: M

3.3.2 Schema Registry compatibility check in build

  • ID: 3.3.2
  • Status: DONE
  • Title: Wire Schema Registry backward-compatibility verification
  • Description: Add a Maven goal (schema-registry-maven-plugin or equivalent) that validates each .avsc against the registry for BACKWARD compatibility on verify, and a script to register schemas. Fail the build on an incompatible change (ADR-019).
  • Business Purpose: Prevent breaking event-contract changes from merging (NFR-16).
  • Inputs: ADR-019.
  • Outputs: Compatibility-check plugin binding + registration script.
  • Acceptance Criteria:
  • A deliberately incompatible schema edit fails mvn verify; a compatible additive change passes.
  • Dependencies: 3.3.1
  • Complexity: M

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • .avsc files + generated Java records.
  • Compatibility-check plugin binding + registration script.

Definition of Done

  • All subtasks (3.3.1, 3.3.2) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).