5953685ffb
Includes: README explaining purpose / scope / temporary-location framing / format decision, CONTRIBUTING.md with proposed workflow + per-class semver versioning policy + validation commands, format/equipment-class.schema.json defining the shape of a class template (classId, version, displayName, applicability, signals, alarms, optional stateModel), format/tag-definition.schema.json defining the shape of a single canonical signal (name, dataType, category, unit, isArray, accessLevel, writeIdempotent, isHistorized, scaling), format/uns-subtree.schema.json defining the shape of a per-site UNS subtree (enterprise + site + areas + lines), classes/fanuc-cnc.json as the worked pilot class with 16 signals + 3 alarms + suggested state-derivation notes (per OtOpcUa corrections doc D1), uns/example-warsaw-west.json as a worked UNS subtree example, docs/overview.md (what / why / lifecycle / what's NOT in this repo), docs/format-decisions.md (8 numbered decisions covering JSON Schema choice per corrections D2, per-class semver, additive-only minor bumps, _default placeholder reservation, signal-name vs UNS-segment regex distinction, stateModel-as-informational, no per-equipment overrides at this layer, applicability.drivers as OtOpcUa driver enumeration), docs/consumer-integration.md (how OtOpcUa / Redpanda / dbt each integrate). $id URLs in the JSON schemas resolve at the actual current path so validators don't 404. Top-level README adds a row to the Component Detail Files table pointing to schemas/. Corrections doc B2 (schemas-repo dependencies) marked partially RESOLVED with the seed location and a list of what still needs the plan team or cross-team owner to decide (owner team naming, dedicated repo migration, format-decision ratification, FANUC CNC pilot confirmation, CI gate setup, Redpanda + dbt consumer integration plumbing). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
43 lines
2.1 KiB
Markdown
43 lines
2.1 KiB
Markdown
# Overview
|
|
|
|
The `schemas` repo is the org's single source of truth for OT equipment definitions. Three things live here:
|
|
|
|
1. **UNS hierarchy** — per-site declarations of which Areas and Lines exist (`uns/`).
|
|
2. **Equipment-class templates** — per-class declarations of which raw signals each equipment type exposes (`classes/`).
|
|
3. **Format definitions** — JSON Schemas defining what UNS and class files must look like (`format/`).
|
|
|
|
## Why a central repo
|
|
|
|
Three OT/IT systems consume the same canonical model:
|
|
|
|
- **OtOpcUa** equipment namespace — exposes raw signals over OPC UA
|
|
- **Redpanda + Protobuf** event topics — canonical event shape on the wire
|
|
- **dbt curated layer in Snowflake** — analytics model
|
|
|
|
Without a central source, they would drift. With one repo, every consumer pulls a versioned snapshot and validates against it. Drift becomes a CI failure, not a production incident.
|
|
|
|
## Lifecycle
|
|
|
|
```
|
|
[author edits JSON in this repo]
|
|
│
|
|
▼
|
|
[CI validates against format/*.schema.json]
|
|
│
|
|
▼
|
|
[PR review by maintainer + consumer reps]
|
|
│
|
|
▼
|
|
[merge to main → tag a semver release]
|
|
│
|
|
▼
|
|
[each consumer pulls the tag and integrates per docs/consumer-integration.md]
|
|
```
|
|
|
|
## What's NOT in this repo
|
|
|
|
- **Per-equipment configuration** — which specific CNC at Warsaw West runs which program. That's per-instance config in OtOpcUa's central config DB (`lmxopcua/docs/v2/config-db-schema.md` Equipment table), not template-level material.
|
|
- **State derivation rules** — how raw signals derive into `Running` / `Idle` / `Faulted` / `Starved` / `Blocked`. That's Layer 3 logic in Aveva System Platform / Ignition. Equipment-class templates can declare which states the class supports (`stateModel.states`) but not the derivation itself.
|
|
- **Wire-format Protobuf schemas** — those are code-generated from this repo into a separate output artifact for Redpanda. The authoring source is here; the binary wire format is derived.
|
|
- **Authoritative LDAP groups, ACL grants, OPC UA security policies** — those live in the consuming systems (OtOpcUa central config DB, identity provider).
|