Skip to content

STORY: Define versioned Kafka event schemas #61

Closed
2 of 2 issues completed
Closed

Description

@ramioooz

Type: Story
Epic: Banking Domain Vertical Slice
Slice: Slice 7 - Events + Notification
Service: event-contracts
Priority: P0

Define governed event schemas instead of sharing handwritten Java event DTOs between services.

Scope:

  • Define transfer-created and related event schemas with explicit ownership and versioning.
  • Register schemas and enforce a documented compatibility mode.
  • Generate service-specific Java models from schemas where appropriate.
  • Validate representative schemas in CI.

Definition of Done:

  • Producers and consumers use the governed schema contract.
  • No shared Java DTO library couples service releases.
  • Compatibility, required headers, delivery semantics, and evolution rules are documented.

Activity

  1. added theissue type on Aug 2, 2026
  2. self-assigned this
    on Aug 30, 2026
  3. ramioooz commented on Aug 31, 2026

    @ramioooz
    MemberAuthor

    The contract-definition slice is ready for review in PR #137: #137. It defines versioned LedgerPostingCompleted.v1 and LedgerPostingFailed.v1 AsyncAPI contracts, required Kafka headers, ownership, partitioning, delivery/DLQ semantics, and compatibility rules. Merge this documentation contract before the ledger outbox, account reservation consumer, and Transaction Service process-manager implementation PRs.

  4. ramioooz commented on Sep 3, 2026

    @ramioooz
    MemberAuthor

    The governed TransferCreated.v1 contract is available for review in the mainline integration PR: #186

    The original PR #173 is stacked on feature/104-event-contracts, so #186 is required before the contract is present on main. Merge this before enabling Notification Service transfer-event consumption; no additional delay is required.

  5. ramioooz commented on Sep 5, 2026

    @ramioooz
    MemberAuthor

    Contract example validation increment

    PR #237 adds the remaining repository-local validation slice for this story. It extends #236 without adding another CI job.

    Delivered

    • Every representative payload example in the four governed AsyncAPI documents is validated against its declared local schema.
    • The dependency-free validator checks required fields, constants, enums, formats, patterns, arrays, object properties, allOf, oneOf, anyOf, if/then, and not used by the current contracts.
    • README and contract-governance documentation now state the executable example-validation boundary.

    Verification

    • ruby scripts/validate_asyncapi_contracts.rb -> Validated 4 AsyncAPI contract documents
    • ruby -c scripts/validate_asyncapi_contracts.rb -> Syntax OK
    • Positive and negative in-memory example checks passed.
    • git diff --check passed.
    • PR CI AsyncAPI contract validation passed.

    Explicitly deferred

    • Generated Java DTO/model libraries: services remain transport-neutral and independently released.
    • Live Schema Registry calls, credentials, subject provisioning, and changed-subject compatibility comparison: platform/release responsibilities, not pull-request requirements.
    • AWS, UAT, PROD, Kafka topic provisioning, and producer/consumer runtime rollout remain outside this repository slice.

    This comment narrows the remaining #61 work to actual producer/consumer adoption evidence and any separately approved Registry integration, rather than duplicating existing contract documentation or introducing unnecessary libraries.

  6. ramioooz commented on Sep 5, 2026

    @ramioooz
    MemberAuthor

    Adoption evidence and closure decision

    The remaining scope is satisfied by the current mainline producer/consumer implementations and the repository-local contract validation already merged:

    • Transaction Service publishes TransferCreated.v1 through its durable outbox and consumes LedgerPostingCompleted.v1, LedgerPostingFailed.v1, and MfaAssuranceGranted.v1 through governed listeners.
    • Ledger Service consumes LedgerPostingRequested.v1 and publishes versioned posting outcome facts through its Kafka adapters and durable inbox/outbox boundaries.
    • Account Service consumes ledger outcomes through its ledger-outcome inbox and applies idempotent projection/reservation transitions.
    • Notification Service consumes TransferCreated.v1 with producer, schema-version, header, and payload validation.
    • MFA Service creates MfaAssuranceGranted.v1 from the durable assurance outbox and publishes the governed envelope.
    • No shared Java DTO library was introduced; each service owns its transport/application records.
    • .github#235 and PRs ci: validate AsyncAPI event contracts #236/ci: validate AsyncAPI payload examples #237 delivered executable validation for all representative examples in the four governed AsyncAPI documents; live Schema Registry provisioning, generated DTO libraries, and AWS/UAT/PROD rollout remain explicitly deferred.

    This closes the schema-definition/adoption story without inventing a new registry integration or CI job. Runtime transfer and assurance behavior remains tracked by .github#103 and .github#208.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions