Expense Event Contract Versioning

Summary

Expense maps all three outbound contracts with schema version 1. No second schema version or explicit multi-version dispatcher is implemented.

Confirmed behavior

Concern	Finding
Producer version	Version 1 for all Expense mappings
Version location	Common integration-event envelope
Serialization	Runtime contract type with consistent shared JSON options
Additive compatibility	Optional approval, rejection, payment, and claimant details are appended nullable fields
Notification missing-version behavior	Consumer envelope defaults a missing transport version to version 1
Payroll version handling	Payroll parses the fields it needs and does not branch on schema version
Unsupported-version rejection	Not implemented
Contract registry	Not implemented

The serializer omits null fields. This behavior and nullable trailing contract fields support additive evolution but do not constitute a formal compatibility guarantee.

Requires confirmation

Schema governance, compatibility testing, supported-version windows, deprecation, consumer upgrade sequencing, and unknown-version handling require confirmation.

Source References

• microservices/src/contracts/Events/IntegrationEvent.cs
• microservices/src/contracts/Events/ExpenseLifecycleEvents.cs
• microservices/src/expense-service/Infrastructure/ExpenseDbContext.cs
• microservices/src/shared-kernel/Outbox/IntegrationEventJsonSerializer.cs
• microservices/src/notification-service/Messaging/NotificationEventConsumer.cs
• microservices/src/payroll-service/Messaging/PayrollReadModelConsumer.cs

Related Articles

• Expense events documentation
• Expense technical documentation
• Expense database documentation

See Also

• Expense API documentation
• Expense module

Keywords

• Expense events
• Contract Versioning
• Integration contracts

Revision Information

• Status: Draft
• Last reviewed: 2026-07-16
• Review cycle: Quarterly