Versioned Data Contract Template (Event + Field Definitions)

Purpose

This template helps teams create clear, versioned event data contracts so downstream consumers can trust production events. Use it for OT→MES, MES→IT, or any event-driven integration between operational and information systems.

When to use

• Defining a new event type or updating an existing one.
• Onboarding a new consumer or publisher.
• Documenting contract changes for governance and rollouts.

Top-level Contract Metadata (header)

Include these metadata fields in the event envelope or topic headers so consumers can validate and route messages without parsing payload fields.

• contractName (string) — canonical event name, e.g. machine.status.update
• schemaVersion (string) — semantic version like 1.2.0 (see versioning rules below)
• eventId (UUID/string) — unique id for the event
• eventTime (ISO8601 timestamp) — when the event was produced; include timezone or use UTC
• source (string) — publisher identifier (plant/machine id)
• eventType (string) — e.g. statusChange, metricReading
• schemaUrl (optional) — link to authoritative schema record in the registry

Field Definitions (schema snippet)

List fields with these columns: name, type, units (if applicable), required/optional, description, example. Keep one authoritative JSON Schema or similar in the schema registry and include a brief snippet here for quick reference.

Example field list

• machineId: string — required — logical machine identifier (e.g. PLANT1-MAC-07)
• timestamp: string (ISO8601) — required — reading time in UTC
• status: enum[string] — required — values: running, stopped, fault
• temperature: number — optional — units: °C
• speed: number — optional — units: rpm
• sequenceNumber: integer — optional — monotonic per source for ordering and deduplication
• metadata: object — optional — extensible bag for non-critical info

JSON Schema snippet (authoritative schema should live in registry)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "machine.status.update",
  "type": "object",
  "required": ["machineId","timestamp","status"],
  "properties": {
    "machineId": {"type": "string"},
    "timestamp": {"type": "string", "format": "date-time"},
    "status": {"type": "string", "enum": ["running", "stopped", "fault"]},
    "temperature": {"type": "number"},
    "speed": {"type": "number"},
    "sequenceNumber": {"type": "integer"},
    "metadata": {"type": "object", "additionalProperties": true}
  },
  "additionalProperties": false
}

Sample payload (concrete example)

{
  "contractName": "machine.status.update",
  "schemaVersion": "1.2.0",
  "eventId": "3f6d2e9a-8b2c-4b2f-a9f1-ef4d2a8b9a55",
  "eventTime": "2026-08-27T15:12:30Z",
  "source": "PLANT-A-AREA-3",
  "payload": {
    "machineId": "PLANT-A-MAC-07",
    "timestamp": "2026-08-27T15:12:25Z",
    "status": "running",
    "temperature": 72.4,
    "speed": 1800,
    "sequenceNumber": 12456
  }
}

Optionality and Field Rules

• Required fields must be present and validated by the publisher before dispatch.
• Optional fields may be omitted; consumers must not assume presence unless listed as required.
• Units must be explicit in the field definition (e.g., °C, rpm). If units are absent, state the default units for the domain.
• Timestamps must be ISO8601 and in UTC unless timezone is explicitly provided.
• Numeric ranges and precision should be documented where relevant (e.g., temperature to 1 decimal place).

Schema Versioning & Compatibility Rules

Follow a clear versioning policy to communicate compatibility expectations:

1. Version format: use semantic versioning MAJOR.MINOR.PATCH (e.g., 2.0.0).
2. MAJOR — incompatible changes (breaking): rename/remove required fields, change field types, change semantics. Consumers may break. Increment MAJOR and reset MINOR/PATCH to 0.
3. MINOR — backward-compatible additions: add optional fields, add enum values (if consumers tolerate unknown values), add new objects. Consumers should continue to work. Increment MINOR for compatible additions.
4. PATCH — non-behavioral changes: documentation fixes, metadata-only changes, implementation details. Increment PATCH for fixes that do not affect contract behavior.

Compatibility guidance:

• Publishers: include schemaVersion in every event and publish the full schema to the registry.
• Consumers: validate payloads against the schemaVersion; tolerate additional/unknown optional fields; fail gracefully for missing required fields.
• Registry: support compatibility checks (e.g., detect breaking changes) when new versions are proposed.

Change Control & Ownership

Each contract must have a named owner responsible for lifecycle, change approvals, and consumer communication.

• Owner: Team or person — contact info and escalation path.
• Stakeholders: list consumers and producers that must approve changes.
• Change request process: propose → impact analysis → contract tests → stakeholder review → registry publish → rollout.

Rollout, Migration & Rollback Rules

1. Prefer additive, backward-compatible changes for fast rollouts.
2. For MAJOR (breaking) changes, use one or more of these strategies:
   • Run both vN and vN+1 in parallel (dual-write) for a transition window.
   • Use feature flags or topic partitioning to route new messages to test consumers first.
   • Version the contractName or include schemaVersion prominently so consumers can route by version.
3. Define a deprecation policy: e.g., announce deprecation, allow N months for migration, then remove old version only after all consumers confirm migration or after expiration.
4. Rollback: be prepared to revert publisher changes and republish the previous schema in the registry. Keep a changelog and previous schema artifacts available for at least the deprecation window.

Validation and Testing

• Publishers validate messages against the authoritative schema before sending.
• Consumers run contract tests (consumer-driven contract or integration tests) against published schemas. Consider using tools such as JSON Schema validators, Pact, or a CI job that exercises common scenarios.
• Use a staging topic or sandbox environment to exercise new versions with real consumer teams before production rollout.
• Automate compatibility checks when a new schema version is proposed in the registry (reject breaking changes unless explicitly approved).

Monitoring and Alerts

• Track consumer validation failures, schema version mismatches, and spikes in error counts after a rollout.
• Alert owners when failure rates exceed thresholds or when deprecated versions are still in use past the removal date.

Operational Checklist (Before Publishing a New Version)

1. Update authoritative schema in registry and increment version per rules.
2. Run automated compatibility and schema validation checks in CI.
3. Run publisher-side validation against the new schema.
4. Run consumer contract tests against the new schema (or notify consumers to run their tests if external).
5. Notify all stakeholders with clear migration instructions and timeline.
6. Deploy in staged rollout (sandbox → pilot consumers → full production).
7. Monitor metrics and errors; be ready to rollback within the agreed window.

Governance and Documentation

Keep a changelog for each contract with links to the registry record, published sample payloads, test results, and migration notes. Make this documentation discoverable to all relevant teams.

Optional Enhancements / Good Practices

• Include a correlationId for tracing related events across systems.
• Prefer explicit units fields rather than assuming defaults when messages cross domains.
• Use sequence numbers or idempotency keys for deduplication and ordering across unreliable transports.
• Consider CRC or checksum in metadata for quick integrity checks on the wire.
• Expose a lightweight test harness or mock broker for consumer integration tests.

Owner & Change Control Steps (Template)

Copy and fill these items when creating or updating a contract.

• ContractName:
• CurrentVersion:
• OwnerTeam/OwnerPerson:
• Consumers:
• ProposedChange Summary:
• ImpactAnalysis: list systems, breakingness, migration steps
• TestPlan: unit, integration, consumer tests
• RolloutPlan: stages, pilot consumers, monitoring
• DeprecationWindow: e.g., 90 days

Quick Example: Breaking Change Process

1. Owner files change request and updates registry with draft schema marked candidate.
2. Stakeholders review and sign off on migration plan.
3. Publisher implements dual-write (vN and vN+1) to a staging environment and runs consumer tests.
4. After pilot success, roll out to production with increased monitoring.
5. After deprecation window and confirmation all consumers migrated, remove old schema from active registry listings (archive instead of delete).

References & Tools

• Use a schema registry (Confluent Schema Registry, Apicurio, or equivalent) for authoritative schemas.
• Use JSON Schema, Avro, or Protobuf depending on your transport and performance needs; keep one canonical schema representation.
• Consumer-driven contract testing tools: Pact, Postman, custom CI validators.

Keep this template with the contract record in your domain collection so each event type has an easily discoverable, versioned source of truth.