operations · data schema · v0.1.0

Plant Issue Intake Schema

Canonical structure for capturing a reported plant problem an agent can route and reason about.

Executive summary

Normalizes a reported plant issue into typed fields (area, equipment, symptom, severity, time, available data, reporter) so an AI agent can triage and request the right follow-up. Capture only — the schema authorizes no action, and a safetyRelevant flag forces routing to human authority.

Machine-readable contract: /schemas/plant-issue-intake.schema.json · Used by: troubleshooting-agent, shift-handover-agent

Fields

Field	Type	Required	Description	Allowed values
`issueId`	string	No	Optional unique id.	—
`area`	enum	Yes	Plant area.	quarry, crusher, raw-mill, kiln, cooler, finish-mill, packing, utilities, lab, other
`equipment`	string	No	Specific equipment / functional location.	—
`symptom`	string	Yes	Short description of the problem.	—
`severity`	enum	Yes	Reporter-assessed severity (advisory).	low, medium, high, critical
`observedAt`	string (date-time)	Yes	ISO 8601 timestamp.	—
`dataAvailable`	array<enum>	No	Data the reporter can supply.	—
`reportedBy`	string	Yes	Name or role of reporter.	—
`shift`	enum	No	Shift.	day, swing, night, unknown
`freeText`	string	No	Additional context.	—
`safetyRelevant`	boolean	No	If true, route to human authority instead of recommending action.	—

Full JSON Schema

The machine-readable contract is served at /schemas/plant-issue-intake.schema.json. Key points: additionalProperties: false (unknown fields are rejected), required fields are area, symptom, severity, observedAt, reportedBy, and area/severity/shift/dataAvailable are constrained to enums.

Valid example

Valid instance

{
  "issueId": "ISS-2026-0142",
  "area": "kiln",
  "equipment": "Kiln 1 burning zone",
  "symptom": "Free lime trending up over last 3 samples",
  "severity": "high",
  "observedAt": "2026-06-25T14:30:00Z",
  "dataAvailable": [
    "free-lime",
    "kiln-bzt",
    "feed-rate"
  ],
  "reportedBy": "Control room operator",
  "shift": "day",
  "freeText": "BZT looked low after fuel change at 13:10.",
  "safetyRelevant": false
}

Invalid example (and why)

Invalid instance

{
  "area": "kil n",
  "symptom": "free lime up",
  "severity": "urgent",
  "reportedBy": "operator"
}

Why it fails: area is not in the allowed enum (typo "kil n"), severity "urgent" is not an allowed value (use critical), and required observedAt is missing.

Example agent advisory response (not part of this schema)

What an agent should produce from an intake record: a routed, advisory summary that authorizes nothing. This is illustrative output, not a schema instance.

Advisory triage response (illustrative)

{
  "issueIdRef": "ISS-2026-0142",
  "summary": "Free lime trending up over the last 3 samples; possible burning/chemistry or sampling cause.",
  "confirmFirst": [
    "Re-sample/re-run free lime",
    "Verify BZT pyrometer and feed/weighfeeder"
  ],
  "candidateAreasToReview": [
    {
      "area": "burning-zone / chemistry",
      "see": "/troubleshooting/high-free-lime"
    },
    {
      "area": "kiln stability",
      "see": "/troubleshooting/kiln-upset"
    }
  ],
  "missingData": [
    "LSF/SM/AM from latest verified XRF",
    "free lime test method"
  ],
  "routing": "Authorized operations + process/QC engineering",
  "authorizes": "nothing — advisory only; control and release decisions require human authority",
  "safetyRelevant": false
}

Versioning

Semantic version in version. Additive changes (new optional fields) bump the minor version; any breaking change (new required field, removed/renamed field, tightened enum) bumps the major version and should ship under a new $id.

AI agent use cases

Parse a free-text problem report into this structure to drive a troubleshooting flow.
Validate an incoming issue record before acting on it.
Detect safetyRelevant=true and switch to routing-to-human behavior.

Pages:low c3s