Manufacturing API & Event-Model Template

Purpose

This template provides minimal, practical JSON event schemas and API contract guidance to make OT→IT integrations predictable and resilient. It targets teams building lightweight event-based integrations between equipment/PLC/edge gateways, MES, and IT systems (dashboards, historians, analytics, ML pipelines).

Design principles

• Keep events small and focused: one fact or state change per event.
• Include stable, common metadata so consumers can reliably correlate and filter.
• Prefer additive (non‑breaking) schema changes. Version schemas explicitly.
• Treat the contract as the integration: define types, required fields, types, and example payloads.
• Validate at the producer and consumer boundaries and maintain a schema registry where possible.

Common metadata (recommended)

Include this metadata on every event so consumers can correlate, trace, and filter across systems.

• event_type: logical name, e.g. "run_state.changed"
• schema_version: semantic version or schema id, e.g. "1.0"
• timestamp: ISO 8601 UTC ("2024-08-01T14:03:00Z")
• asset_id: canonical identifier for the machine/equipment
• site_id: optional plant/facility identifier
• operator_id: optional operator or user id
• shift_id: optional shift identifier if tracked
• correlation_id: GUID for tracing related events through workflows
• source: component that emitted the event (edge, gateway, PLC adapter)
• idempotency_key: optional token for deduplication when replaying

Topic / endpoint naming conventions

Use consistent naming so integrations can subscribe or filter easily:

• Message broker topic style: manufacturing.{site_id}.{asset_type}.{event_type}
• REST webhook endpoint: POST /api/v1/events with an HTTP header X-Event-Type or event_type field

Sample event schemas (minimal, practical examples)

1) Run State (machine mode)

When to emit: on mode change (e.g., Running → Idle → Maintenance)

{
  "event_type": "run_state.changed",
  "schema_version": "1.0",
  "timestamp": "2024-08-01T14:03:00Z",
  "asset_id": "pump-42",
  "site_id": "plant-a",
  "source": "edge-gateway-7",
  "correlation_id": "8f14e45f-cec6-4b2b-9b2d-0123456789ab",
  "payload": {
    "previous_state": "idle",
    "current_state": "running",
    "reason": "operator_start",
    "mode_details": {
      "speed_rpm": 1200,
      "setpoint": 1100
    }
  }
}

2) Production Counter (part produced)

When to emit: when a part is completed or a cycle count increments

{
  "event_type": "production.counter",
  "schema_version": "1.0",
  "timestamp": "2024-08-01T14:05:23Z",
  "asset_id": "cell-3-press-1",
  "site_id": "plant-a",
  "operator_id": "op-23",
  "correlation_id": "b6d81b36-...",
  "payload": {
    "part_id": "widget-100",
    "serial_number": "SN-000123",
    "count": 1,
    "cycle_time_ms": 4520,
    "quality_pass": true
  }
}

3) Quality Escape / Defect Event

When to emit: when a defect is detected that may require rework or customer notification

{
  "event_type": "quality.escape",
  "schema_version": "1.0",
  "timestamp": "2024-08-01T14:12:10Z",
  "asset_id": "vision-station-2",
  "site_id": "plant-a",
  "operator_id": "qc-12",
  "correlation_id": "c1a1f...",
  "payload": {
    "part_id": "widget-100",
    "serial_number": "SN-000124",
    "defect_code": "surface-scratch",
    "severity": "minor",
    "image_url": "https://store.example.com/images/defect/SN-000124.jpg",
    "action_taken": "quarantined"
  }
}

4) Maintenance Event (fault, start, stop)

When to emit: on detection of faults, start of planned maintenance, completion

{
  "event_type": "maintenance.event",
  "schema_version": "1.0",
  "timestamp": "2024-08-01T14:20:00Z",
  "asset_id": "compressor-7",
  "site_id": "plant-a",
  "source": "edge-adapter-3",
  "correlation_id": "d9f2f2...",
  "payload": {
    "maintenance_type": "unplanned",
    "event_subtype": "fault_reported",
    "fault_code": "E-502",
    "description": "overtemperature",
    "severity": "high",
    "reported_by": "sensor-23"
  }
}

Validation, schema management, and compatibility

• Define JSON Schema (or Avro/Protobuf) for each event_type and store in a schema registry.
• Producers must validate outbound events against the schema. Consumers should validate inbound events.
• Follow compatibility rules: adding optional fields is compatible; removing or renaming required fields is breaking.
• Use schema_version to signal minor/major changes. Consider using a numeric schema id alongside semantic versions.
• Maintain a changelog for each schema and document migration guidance for consumers.

Security, transport, and delivery

• Use TLS for REST/webhook and mTLS or secure brokers for message buses.
• Authenticate senders (OAuth2 client credentials, certificates) and authorize by asset/topic.
• Prefer at-least-once delivery with idempotency_key for deduplication, or exactly-once semantics where the platform supports it.

Operational tips and adoption checklist

1. Agree on canonical asset_id and site_id formats with OT and MES teams.
2. Publish the JSON Schema files and examples in a central registry or repo.
3. Implement producer-side validation and consumer-side contract tests (integration tests that assert schema compatibility).
4. Define a lightweight change process: classification (minor/major), impact assessment, notification window, and backward compatibility rules.
5. Start with a small set of events (the four above) and expand as use cases mature.
6. Instrument metrics: publish counts of events, validation errors, consumer rejections, and processing latency.

Mapping to MES / IT use cases

Examples of downstream uses:

• Production_counter -> update KPIs, OEE calculations, traceability records
• Run_state -> update equipment status dashboards and trigger scheduling adjustments
• Quality_escape -> open quality incidents, attach images, route to QA
• Maintenance_event -> create or update work orders and maintenance logs

Next steps and templates

Use the above schemas as a starting point. Copy them into your schema registry, generate JSON Schema artifacts, and produce example events from an edge gateway. Track schema_version and publish a brief contract document describing required fields and compatibility rules for each event_type.

Tip: start with the smallest useful payload for each event. Add richer payloads later as optional fields once consumers are ready.