Schema contracts between product and lifecycle teams.
Define the committed business fact before its JSON shape. Maintain a registry of consumer dependencies, version semantic changes deliberately, and test campaign behavior as well as structural validation.
Inside this article 5 sections +
A lifecycle event contract should describe a business fact, its identity and timing, and what consumers may safely infer from it. Keep a dependency registry linking each event version to campaigns, analytics models, and operational consumers. Schema validation alone cannot detect a change in meaning that sends the wrong message.
Product and lifecycle teams often discover this gap when a field is renamed or a milestone changes. The event still arrives as valid JSON, yet a campaign treats a trial extension as a new purchase or sends setup advice to an already active account.
Contract the fact before the payload
Take an illustrative trial_extended event. Its meaning is that an authorized operation committed a new trial end time for one account. It is not a request to extend the trial, a page view, or proof that an email should be sent. That sentence defines when the producer emits the event and the boundary consumers can trust.
Specify the business identifiers, original occurrence time, event ID, schema version, and operation ID. Include the previous and new end times when consumers need to explain the change. Record the reason using a controlled value rather than a free-text support note that might contain sensitive information.
Keep delivery metadata separate from the fact. Retry count, destination response, and replay batch describe transport. The account's trial dates describe the business. Mixing them encourages consumers to interpret “received today” as “extended today,” which becomes wrong after a pipeline repair.
| Consumer | Depends on | Contract test |
|---|---|---|
| Lifecycle confirmation | New end time; eligible recipient; live delivery mode | Replay stores history without sending |
| Account analytics | Account ID; occurrence time; extension reason | Account switch does not change attribution |
| Warehouse model | Stable event ID; previous and new end times | Duplicate delivery does not add another extension |
| Support timeline | Operation ID; actor category | Displays committed change without private note text |
Validate shape with a small schema
The following excerpt validates a narrow part of the illustrative contract. It deliberately omits recipient addresses: recipients should be resolved through the approved account-to-person rules, not copied into every event. A full contract also validates time semantics and business authorization outside JSON Schema.
{
"type": "object",
"required": ["event_id", "schema_version", "account_id", "reason"],
"properties": {
"event_id": {"type": "string", "minLength": 1},
"schema_version": {"const": 1},
"account_id": {"type": "string", "minLength": 1},
"reason": {"enum": ["customer_request", "service_recovery"]}
},
"additionalProperties": true
}
Allowing additional fields makes additive producer changes easier for tolerant consumers. It does not mean consumers may start depending on undocumented fields. A stricter schema can be useful at a particular boundary, but then adding a field requires coordinated compatibility handling. Choose the policy explicitly instead of letting a validator's defaults define it.
Validate before committing an event to the delivery pipeline where possible. Also validate at consumer boundaries so an old producer or repair script cannot bypass the contract. Invalid events need a quarantine record with an owner and safe diagnostic detail; silently dropping them converts a clear schema failure into a mysterious campaign gap.
Separate additions from semantic breaks
Adding an optional locale field can be backward compatible if consumers ignore it. Changing account_id from a workspace identifier to a parent-company identifier is a semantic break even if its JSON type stays a string. Changing time units from seconds to milliseconds is another break that a broad number schema may accept.
Publish a new version or event name when meaning changes. Keep an explicit transition interval with a designated canonical version for each consumer. If the producer temporarily emits both versions, prevent a messaging consumer from treating them as two independent reasons to contact the person.
Do not overload an existing event to avoid adding a contract. A cancelled extension and a committed extension are different facts. Clear event names and business state transitions make campaign conditions easier to review and warehouse history easier to reconstruct.
Test the consumer contract, not only JSON
Maintain fixtures for a normal extension, a repeated delivery, an older replay, a missing reason, an unsupported version, and an account whose primary contact changes before delivery. For each fixture, specify the expected campaign eligibility, warehouse count, and support display.
Include negative cases where the payload is structurally valid but wrong for the business: an end time earlier than the prior end time, an account unrelated to the operation, or a reason not permitted for the acting role. These checks belong to domain logic and producer tests, not to a promise that JSON Schema can validate all meaning.
Run consumer fixtures before a producer change is released. Keep the relevant campaign condition or transformation version in the registry so the test result identifies what was actually reviewed. A spreadsheet that names a campaign but not its current dependency can become stale as quickly as undocumented code.
Give contract changes an owner and an exit condition
Assign one owner for the business meaning and one responsible maintainer for each consumer. The producer team should not need permission for every internal implementation change, but it must expose changes to facts consumers rely on. Consumers should not quietly reinterpret an event to solve an unrelated reporting problem.
Retire an old version only after its consumers have migrated and delayed or replayed records have a defined path. Keep a transformation for historical data where needed, and record the loss of information if an older event cannot support a new field. Do not fabricate historical values to satisfy a new schema.
The account identity guide defines actor and account context; replay-safe lifecycle delivery separates facts from message eligibility. Software implementation can make the contract registry, validation, and consumer fixtures part of the delivery workflow.