Manufacturing Data Contract Template (Events & Telemetry)

Manufacturing Data Contract — Events & Telemetry

Use this template to create a concise, versioned contract between an OT data producer (PLC, gateway, historian, edge device) and an MES/IT consumer. The contract reduces ambiguity about event semantics, payload shape, units, timing, delivery expectations, and change control so downstream systems can rely on signals without brittle point‑to‑point adapters.

1. Contract Header

Provide a short structured header so anyone can quickly identify scope and status.

2. Glossary & Event Semantics

Define key terms so semantics are shared (examples below). Keep this short but authoritative.

• Event: A discrete occurrence with defined semantics (e.g., motor-start, overload, product-complete).
• Telemetry: Regularly sampled measurements (e.g., temperature, vibration) often used for trending and analytics.
• SchemaVersion: Version identifier embedded in the payload that indicates the payload structure.
• IdempotencyKey: A value that allows consumers to detect and ignore duplicate deliveries of the same logical event.

3. Event Types and Example Schemas

List every event type or telemetry feed covered by this contract. Include a short human description, naming convention, topic/route example, and a machine-ready JSON Schema or example payload.

Example: EquipmentTelemetry.sample_vibration (telemetry)

Topic: plant/{plantId}/equipment/{equipmentId}/telemetry/vibration

{
  "schemaVersion": "1.0.0",
  "eventType": "telemetry.vibration",
  "plantId": "PLANT-A",
  "equipmentId": "EQ-12345",
  "timestamp": "2025-01-15T14:32:05.123Z",
  "sequenceNumber": 4521,
  "value": 3.42,
  "unit": "mm/s RMS",
  "status": "OK"
}

Notes:

• schemaVersion follows contract versioning rules (see section on versioning).
• timestamp must be ISO 8601 UTC string; see timestamp rules.
• Include unit exactly as agreed (avoid ambiguous units).

Example: EquipmentEvent.motor_start (event)

{
  "schemaVersion": "1.0.0",
  "eventType": "equipment.motor_start",
  "plantId": "PLANT-A",
  "equipmentId": "EQ-12345",
  "timestamp": "2025-01-15T14:32:05.123Z",
  "idempotencyKey": "motorStart|EQ-12345|2025-01-15T14:32:05.123Z|seq-9876",
  "initiator": "operator-joe",
  "metadata": { "mode": "auto" }
}

4. Timestamp & Idempotency Rules

Clear timestamp and duplicate-detection rules avoid mismatches across time zones and ordering assumptions.

• Use UTC ISO 8601 timestamps with millisecond precision where available (e.g., 2025-01-15T14:32:05.123Z).
• Producer MUST include a monotonically increasing sequenceNumber per device or logical stream when the transport/queue preserves ordering. State how sequence gaps should be treated.
• When ordering cannot be guaranteed, include idempotencyKey that uniquely identifies the logical event. Provide a deterministic construction pattern (see example above).
• Define duplicate detection window: e.g., consumers will treat duplicates (same idempotencyKey) within 7 days as duplicates and drop them; producers must not reuse keys after retirement window expires.
• If device clocks are unreliable, prefer producer-assigned monotonic sequence numbers plus a server-assigned ingestion timestamp.

5. Delivery SLA and Retry Behavior

Specify expectations for latency, delivery guarantees, acknowledgements, and retry strategy so both sides can design appropriately.

• Delivery model: Best effort, at-least-once, or exactly-once (note: exactly-once is usually implemented via idempotency plus consumer deduplication).
• Latency SLA: Typical and maximum acceptable end-to-end delivery time (example: telemetry expected within 5s typical, 30s max under normal network conditions).
• Acknowledgements: When applicable, define acknowledgement semantics (e.g., consumer returns 2xx on valid receipt; non-2xx triggers retry behavior).
• Retry policy: Exponential backoff starting at 2s, doubling, up to a max interval (e.g., 5 minutes) and a max retry window (e.g., 24 hours). Define what happens after max retries (dead-letter, alert to owner).
• Ordering guarantees: If preserving order is required, specify partitioning strategy (e.g., partition by equipmentId) and what to do on reorder cases.
• Throughput and burst handling: Specify expected peak events/sec per producer and acceptable behavior during overload (drop oldest telemetry, backpressure signals, or queueing limits).

6. Transport & Security Notes

Briefly note allowed transports and security expectations — do not replace a security audit. Include references to certificates, mutual TLS, VPN, ACLs, or messaging ACLs as required.

• Allowed transports: Kafka topic naming scheme, MQTT topic path, HTTP(S) POST to ingestion endpoint, AMQP — specify exact endpoint URIs and topic names.
• Authentication: e.g., Mutual TLS client certs or OAuth2 token with scope ingest:plantA.
• Authorization: consumers must be listed in ACLs; producers must be registered and have keys/certs rotated according to policy.
• Encryption: TLS 1.2+ in transit. At-rest encryption requirements if applicable.
• Rate limiting and quotas: specify per-producer limits and behavior when quotas are exceeded.

7. Data Retention, Privacy & Compliance

Document how long raw events are kept, aggregated, or purged and which fields are considered sensitive.

• Retention policy examples: raw telemetry retained 90 days, aggregated summaries retained 3 years.
• PII & Personal Data: declare fields that may contain personal data (operator IDs) and required handling (hashing, pseudonymization).
• Regulatory requirements: reference relevant regulations (e.g., industry-specific traceability rules) and encryption/audit needs.

8. Ownership, Contacts & Support

Assign clear owners for producer and consumer responsibilities.

• Data Producer Owner: Name, team, email, escalation path.
• Data Consumer Owner: Name, team, email, escalation path.
• Support SLA: Response time for incidents affecting ingestion (e.g., 2 hours for P1).

9. Change Process & Versioning Policy

Prevent accidental breaking changes by defining how versions change and how deprecation is announced.

• Versioning: Use semantic versioning for contract and a separate payload schemaVersion. MAJOR change = breaking, requires migration plan and downtime window; MINOR = additive/non-breaking; PATCH = backwards-compatible fixes.
• Deprecation policy: Announce deprecation of a MAJOR version at least 90 days before retirement. Maintain compatibility strategies or provide transformation adapters.
• Change request process: How consumers request changes (ticket system, RFC), who reviews, acceptance criteria, and communication channels.
• Compatibility matrix: Maintain a short matrix showing which consumer versions are compatible with which producer versions.

10. Mapping and Units

Supply explicit unit and scale conventions to avoid mismatches.

• Specify canonical units (SI preferred). Example: vibration = mm/s RMS, temperature = Celsius with one decimal place.
• Provide transformation guidance for legacy systems that emit different units or scales.
• Timestamp timezone: UTC only; do not use local time strings.

11. Test Plan & Acceptance Criteria

Include concrete tests every implementation must pass before a consumer begins to rely on the contract.

Automated Schema Validation

• Producer must provide a JSON Schema (or Avro/Protobuf equivalent). Consumer must validate incoming messages against the schema and reject or quarantine invalid messages.

Functional Acceptance Tests (examples)

1. Schema conformance: Send a set of valid and invalid example messages; consumer validates that valid messages are accepted and invalid ones are rejected or quarantined with error details.
2. Timestamp handling: Send messages with correct UTC timestamps, future timestamps, and slightly out-of-order timestamps—verify consumer correctly orders or handles them according to contract rules.
3. Idempotency / Deduplication: Send duplicate messages with identical idempotencyKey; verify consumer processes only one event.
4. Sequence gap handling: Intentionally omit a sequence number and later send it; verify detection, logging, and recovery behavior.
5. Latency and throughput tests: Simulate expected and peak loads; verify average and worst-case ingestion latency meets SLA.
6. Failure & retry tests: Simulate transient consumer failures; verify producer retry policy and consumer dedup behavior.
7. Security tests: Verify authentication, certificate validation, and authorization checks.

Acceptance Criteria Checklist

• JSON Schema provided and agreed.
• Five example valid and three example invalid payloads provided.
• Successful end-to-end test meeting latency SLA under normal load.
• Duplicate suppression verified within configured duplicate window.
• Owners and escalation contacts documented.

12. Test Vectors & Examples

Provide concrete example messages that implementers can use in their test harness.

// Valid telemetry example
{
  "schemaVersion": "1.0.0",
  "eventType": "telemetry.vibration",
  "plantId": "PLANT-A",
  "equipmentId": "EQ-12345",
  "timestamp": "2025-01-15T14:32:05.123Z",
  "sequenceNumber": 4521,
  "value": 3.42,
  "unit": "mm/s RMS",
  "status": "OK"
}

// Invalid example (missing unit)
{
  "schemaVersion": "1.0.0",
  "eventType": "telemetry.vibration",
  "plantId": "PLANT-A",
  "equipmentId": "EQ-12345",
  "timestamp": "2025-01-15T14:32:05.123Z",
  "sequenceNumber": 4521,
  "value": 3.42
}
  

13. Monitoring, Observability & Alerts

Define monitoring metrics and alert thresholds so the team detects contract violations early.

• Key metrics: ingestion latency percentiles (p50/p95/p99), message schema validation failure rate, duplicate rate, sequence gap rate, per-producer throughput.
• Alerts: schema validation rate > 1% sustained over 10m, ingestion latency p99 > SLA, duplicate rate spike above baseline.
• Dashboards: Provide at least one example dashboard layout and required metrics.

14. Rollout & Migration Plan

Explain how producer or consumer upgrades will be coordinated to avoid breaking running systems.

• Staged rollout: test → pre-prod → production. Use feature flags or parallel publishing when practical.
• Backwards compatibility: Producers must support previous MINOR versions during migration window unless otherwise agreed.
• Fallback: Define graceful degradation if new fields are missing or consumers discover unknown extra fields.

15. Appendix — Example Contract History

Keep a changelog table for transparency.

Quick Implementation Checklist

• Complete contract header and sign-off by owners.
• Attach machine-readable JSON Schema and example payloads.
• Agree SLA, retry, and duplicate detection windows.
• Run functional acceptance tests and publish results.
• Publish contact list and monitoring dashboards.

Notes: This template is a practical starting point. Teams should tailor retention, security, and SLA numbers to their operational realities and compliance needs. This contract does not replace site engineering, vendor implementation, security audits, or regulatory compliance checks.