Manufacturing Data Contract & API Template

Purpose

This template helps teams define minimal, versioned data contracts for events and records exchanged between OT, MES/SCADA and analytics or IT systems. Use it to make integrations predictable, maintainable, and testable—reducing one-off adapters, unit/timestamp mismatches, hidden logic, and integration drift.

How to use this template

• Copy one contract per event or record type (for example: machine.status.changed, production.batch.completed, or sensor.temperature.reading).
• Fill every metadata field. Keep descriptions actionable and concise.
• Publish contract documents in a version-controlled location and notify consumers when versions change.

Template

Header

• Event / Record name: Friendly, dotted name (example: line.{lineId}.cycle.completed)
• Contract ID: Unique identifier (e.g. urn:org:contracts:production.cycle.v1)
• Schema version: vMAJOR.MINOR (see Versioning Policy below)
• Author / Owner: Team, role, and contact (email or ticket queue)
• Created date and Last modified
• Scope: Which plants/systems produce this event and which teams consume it

Event metadata (recommended)

Standardize these fields in every event to make downstream processing reliable.

• event_id (string): Globally unique identifier for the event.
• event_name (string): Contract-level event name.
• source (object): { source_type, source_id, plant_id, line_id } — where the event originated.
• timestamp_utc (string, ISO 8601): UTC timestamp. Always use UTC; include timezone only if needed.
• schema_version (string): Contract schema version that produced this payload.
• sequence (optional, integer): Monotonic sequence when ordering matters.

Schema (fields and types)

List each field with: name, type, units (if relevant), allowed range or enumeration, nullable?, default, and description. Prefer explicit primitive types (string, integer, number/float, boolean, object, array) and specify ISO formats for timestamps.

Example JSON-like contract excerpt: { "event_name": "production.batch.completed", "schema_version": "v1.0", "payload": { "batch_id": "string", "product_code": "string", "quantity": "integer", "good_count": "integer", "start_time_utc": "ISO8601 string", "end_time_utc": "ISO8601 string", "duration_seconds": "number", "unit": "string (e.g. pieces)", "notes": "string (nullable)" } }

Sampling and aggregation rules

Describe producer-side sampling, cardinality expectations, and recommended consumer aggregation windows.

• Sampling frequency (e.g. 1s, 10s, event-driven). Example: sensor.temperature.reading emitted once every 10s or on delta >= 0.5°C.
• Aggregation guidance: if consumers need 1-minute averages, state that and include formula (e.g. average of values in time window).
• Downsampling and rollups: who is responsible (edge/publisher or analytics). Define expected summary fields (min, max, avg, count).
• Idempotency guidance for replays or duplicates (use event_id + sequence + timestamp to de-duplicate).

Retention / TTL

State how long raw and aggregated records are retained and where (edge device, MES, historian, analytics). Example:

• Raw events: 90 days in analytics, 1 year in site historian.
• Aggregates: 3 years at 1-hour resolution.
• Sensitive PII (if any): never retained beyond X days and must be encrypted at rest.

Versioning policy

Use MAJOR.MINOR semantics:

• MAJOR – incompatible changes (consumers MUST upgrade). Examples: rename or remove required fields, change type incompatibly.
• MINOR – additive, backward-compatible changes (consumers may ignore new fields). Examples: new optional field, new enum values if consumers can handle unexpected values.
• Patch (optional) – bug fixes that do not change schema semantics (e.g. clarifying description).
• Deprecation timeline: declare deprecation version, announce, and give a minimum migration window (e.g. 90 days) before removal.

Compatibility rules and examples

• Allowed backward-compatible changes: adding optional fields, adding enum values with default handling, adding optional nested objects.
• Disallowed without MAJOR bump: renaming fields, changing required <-> optional, changing data types in incompatible ways, changing units without explicit conversion field.
• Unit and timestamp rules: always declare units in field metadata (e.g. temperature_C). Timestamps must be ISO8601 UTC unless otherwise justified.

Consumer acceptance tests (CATs)

Provide automated and manual checks consumers can run to validate a producer is compliant. At minimum include:

1. Schema validation: payload validates against the published schema for schema_version (use a JSON Schema or similar).
2. Field-level checks: required fields are present and types match; units match expectations.
3. Timestamp checks: timestamp_utc present and within expected skew (e.g. < 2 minutes difference from processing system time for near-real-time events).
4. Cardinality tests: expected event frequency is within tolerance (e.g. 60 ± 10 events per minute per device).
5. Idempotency / dedupe: replay a previously recorded event and verify consumers do not double-count when dedupe logic is applied.
6. End-to-end sample: produce one canonical test event and verify it arrives in consumer system, is parsed, and populates the expected downstream metric/dashboard.

Operational and governance checklist

• Contract published in central registry and version-controlled repository (link).
• Owner and backup owner assigned.
• Notification list for schema changes (email, ticketing, or subscription).
• Acceptance tests automated in CI where possible.
• Security requirements noted: transport encryption (TLS), authentication (mTLS, API keys), access controls.
• Privacy / compliance notes: whether the contract contains PII or regulated data.

Lightweight API guidance (if applicable)

For event publishing endpoints or record APIs include:

• Endpoint path and method (e.g. POST /api/v1/events/production)
• Authentication required and expected headers (e.g. Authorization: Bearer <token>)
• Content type (application/json), max payload size, and rate limits.
• Expected response codes and meanings (200/202 accepted, 400 validation error, 401 unauthorized, 422 schema validation failed).

Change log (example)

• v1.0 – Initial published contract. (2026-01-12). Owner: OT Integrations Team.
• v1.1 – Added optional field notes and clarified units for duration_seconds. (2026-04-02).

Examples and common patterns

Include a couple of short, concrete examples specific to your environment (machine telemetry, batch completion, alarm events). Prefer one-line examples that show how standard metadata and payload fields appear together.

Related resources

• Organization schema registry / contract repository (link)
• JSON Schema examples and validation tool links
• Onboarding guide for new consumers

Quick checklist for producers

• Have you set event metadata and schema_version?
• Are timestamps in UTC and units explicit?
• Is there an owner and contact for the contract?
• Are consumer acceptance tests defined and runnable?
• Have you published the contract to the central registry and notified consumers?

ImageSearchPhrase: data contract template