Employee Event Contract Versioning

Summary

Every shared integration contract carries SchemaVersion, and Employee mappings currently emit version 1. No formal compatibility governance was found in source.

Audience

• Contract owners, producer and consumer developers, QA engineers, and architects

Overview

The common base requires a numeric schema version. Serialization uses web JSON defaults and omits null properties. Inspected consumers read selected properties permissively and do not show a common schema-version gate.

Confirmed and recommended boundary

Topic	Status
Schema-version field	Confirmed
Employee mappings emit version 1	Confirmed
Central contract assembly	Confirmed
Compatibility/deprecation policy	Not implemented
Consumer support matrix by version	Requires confirmation
Contract registry or schema enforcement	Not implemented

For future changes, additive optional fields are the safest default because current consumers select known properties. Renaming/removing fields, changing meaning or type, or changing event-type routing can break consumers and should require an approved new-version migration. These are public-safe engineering recommendations, not claims of an existing governance process.

Review expectations

Before changing a contract, identify every source-confirmed consumer, add producer serialization tests and consumer fixture tests, define coexistence behavior, and document rollout and rollback ownership. Whether a breaking change uses a new event type or a higher schema version Requires confirmation by contract owners.

Source References

• microservices/src/contracts/Events/IntegrationEvent.cs
• microservices/src/contracts/Events/EmployeeCreatedEvent.cs
• microservices/src/contracts/Events/EmployeeUpdatedEvent.cs
• microservices/src/contracts/Events/EmployeeDeletedEvent.cs
• microservices/src/contracts/Events/ManagerChangedEvent.cs
• microservices/src/contracts/Events/DepartmentChangedEvent.cs
• microservices/src/contracts/Events/EmploymentStatusChangedEvent.cs
• microservices/src/contracts/Events/EmployeeTimelineEventRecordedEvent.cs
• microservices/src/employee-service/Infrastructure/EmployeeDbContext.cs
• microservices/src/shared-kernel/Outbox/IntegrationEventJsonSerializer.cs

Related Articles

• Integration events
• Consumer landscape
• Integration testing guide

See Also

• Event catalog
• Idempotency and ordering

Keywords

• Event schema version
• Contract compatibility
• Contract governance

Revision Information

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