Manufacturing Data Contract & Event Model Template

Overview

This template helps teams agree on a minimal, versioned data contract for an operational data feed (events or telemetry) between OT systems (PLC, RTU, SCADA, equipment controllers), MES/MOM, analytics platforms, and other IT consumers. Use it to reduce brittle point-to-point adapters, mismatched units or timestamps, hidden business logic, and unclear ownership.

How to use this template

Copy this template into your project or domain, fill every required field, attach a machine-readable schema (JSON Schema, Avro, Protobuf), and register the contract in a schema registry or configuration repo. Keep the document small and pragmatic—implementers will rely on the sample schema and examples.

Template Sections (fill these out)

1. Feed ID & Purpose — short stable identifier, human-friendly name, and the business/operational purpose the feed serves.
2. Contract Versioning — semantic version, change policy, and compatibility guarantees.
3. Event Type(s) / Topic — names of events or topics, routing hints, and allowed producers/consumers.
4. Machine-readable Schema — link to JSON Schema/Avro/Protobuf and canonical example payloads.
5. Field Definitions — table of fields, types, units, required/optional, allowed values, cardinality, and examples.
6. Frequency & Sample Rate — expected cadence, sampling policies, and burst behavior.
7. Latency & SLA — expected delivery latency, SLOs, and measurement method.
8. Ordering & Deduplication — sequence numbers, idempotency keys, clocks, and monotonicity guarantees.
9. Timestamp & Timezone Rules — canonical timestamp field(s) and format (ISO 8601 with timezone recommended).
10. Retention & Storage — retention period, archival policy, and downstream storage expectations.
11. Error-handling Semantics — validation failure behavior, retry policy, dead-letter rules, and error codes.
12. Security & Authorization — transport (MQTT/TCP/HTTP/kafka), TLS expectations, auth method, and sensitive fields handling.
13. Monitoring & Alerts — metrics to expose (ingest rate, validation errors, latency), expected alerts, and dashboards.
14. Onboarding & Testing — test harness, sample data, conformance tests, and acceptance criteria.
15. Contact & Ownership — producer, primary contact, consumer owners, and escalation path.
16. Change Log — chronological record of versions, dates, authors, and summary of changes.

Detailed fields and examples

1. Feed ID & Purpose

FeedID: equipment.status.v1
Purpose: Provide near-real-time equipment operational state to MES and analytics for OEE, utilization, and downtime correlation.

2. Contract Versioning

Version: 1.0.0 (semver-like). Backwards-compatible additive changes allowed within patch/minor; breaking changes require major version bump and migration plan. Each published schema must include a stable URL and checksum.

3. Event Type / Topic

EventType: EquipmentStatus
Topic / Channel: plantA.equipment.status
Allowed producers: PLC-Gateway-01, EdgeAgent-02
Allowed consumers: MES, OEE-Service, Analytics-Stream

4. Machine-readable Schema (required)

Provide a canonical JSON Schema link (example):
https://schemas.mycompany.local/equipment/status/1.0.0/schema.json
Attach the schema file to version control and reference its URL and checksum here.

5. Field Definitions (table format — populate each row)

• fieldName — equipmentId
• type — string
• unit — n/a
• required — true
• description — unique equipment identifier consistent with asset registry
• example — EQP-12345

Repeat for every field. Important fields to include:

• eventId (string, required): unique event UUID or idempotency key
• eventType (string, required): should match Contract EventType
• eventVersion (string, required): schema version
• timestamp (string, required): ISO-8601 with timezone, the canonical event timestamp
• sourceTimestamp (string, optional): original device timestamp if different
• equipmentId (string, required)
• state (string, required): enumerated states (Running, Idle, Fault, Maintenance)
• stateReason (string, optional): short reason code or reference to status table
• sequenceNumber (integer, optional): monotonic per equipment to detect reordering
• metrics (object, optional): measured values (speed, power_kw, temperature_c)

6. Frequency & Sample Rate

Expected cadence: event per state change, plus heartbeat every 10s. Burst policy: producers may emit a short burst on startup; consumers should tolerate brief bursts but alert on sustained high-rate deviations.

7. Latency & SLA

SLO: 95% of events delivered within 5 seconds of event.timestamp for on-prem consumers; 99% within 30 seconds across WAN (if applicable). Specify measurement window and monitoring query.

8. Ordering & Deduplication

Provide sequenceNumber per equipment and eventId for idempotency. If messages may be redelivered, consumers must deduplicate on eventId. Document whether the transport preserves ordering.

9. Timestamp & Timezone

Use ISO 8601 (RFC 3339) with explicit timezone/offset, e.g. 2026-08-27T14:05:00Z. If device clocks are unreliable, include both deviceTime and serverIngestTime and document correction method.

10. Retention & Storage

Producers: keep raw telemetry for 30 days. Consumers: store summarized or aggregated events per downstream policy. Archive raw events after 90 days to cold storage.

11. Error-handling Semantics

Validation failures: producer must not silently drop events without reporting. Transport-level retries permitted with exponential backoff (max 5 retries). Failed messages after retries land in dead-letter topic with reason codes and raw payload.
Error codes (examples): 100 = schema validation error, 200 = authentication failure, 300 = malformed payload.

12. Security & Authorization

Transport: MQTT v5 over TLS or Kafka with mTLS. Authentication: mutual TLS or oauth2 client credentials. Sensitive fields: none in this schema; if present, mark and encrypt or redact as required.

13. Monitoring & Alerts

Expose metrics: events_ingested_per_minute, validation_errors_per_minute, avg_latency_seconds. Alert conditions: validation_errors > 1% sustained for 15 minutes, latency > SLA for 10 minutes, producer offline > 5 minutes.

14. Onboarding & Testing

Onboarding steps:

1. Producer registers feed and provides sample payloads.
2. Consumer runs conformance tests against published schema (include test harness link).
3. Staging traffic for 48–72 hours with monitoring enabled.
4. Signed agreement on SLAs and cutover window.

15. Contact & Ownership

Producer team: Plant Controls (email: controls@company.example)
Consumer team(s): MES Integration (mes-int@company.example), Analytics (data-ops@company.example)
Escalation: on-call engineer list and phone.

16. Change Log

Version 1.0.0 — 2026-08-27 — Initial stable contract — Author: Controls Team

Minimal example payload (EquipmentStatus)

{ "eventId": "8f14e45f-ea1c-4a6a-9f3b-123456789abc", "eventType": "EquipmentStatus", "eventVersion": "1.0.0", "timestamp": "2026-08-27T14:05:00Z", "equipmentId": "EQP-12345", "state": "Running", "stateReason": "", "sequenceNumber": 15842, "metrics": { "speed_rpm": 1200, "power_kw": 15.2 } }

Attach this JSON to the schema registry and use it in conformance tests.

Mapping and Integration Guidance

1) Map device native codes to canonical enums early at the edge so downstream consumers see stable values. 2) Normalize units at the contract boundary and document original units if needed. 3) Avoid embedding business logic in adapters—publish raw, annotated state and let downstream services interpret it.

Common pitfalls and how to avoid them

• Unspecified timezones — enforce ISO timestamps with offsets.
• Hidden unit mismatches — require units in schema and examples.
• Undocumented retry behavior — document producer and transport retry rules.
• No versioning policy — include explicit version and compatibility statement.
• No owner — list producer and consumer owners with escalation path.

Next steps & checklist before signing the contract

1. Attach machine-readable schema and checksum.
2. Run conformance tests using provided example payloads.
3. Publish policy for breaking changes and migration plan.
4. Configure monitoring and alerts per the Monitoring section.
5. Agree on retention and privacy requirements.

Appendix — Suggested schema practices

- Prefer explicit field names over nested opaque blobs for core contract fields.
- Use nullable fields rather than optional absent keys when downstream systems prefer fixed schemas.
- Maintain a schema registry and require every consumer to reference schema URL + checksum.