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>
4.2 KiB
Format Decisions
Why the schemas repo looks the way it does. Each decision is open for the schemas-repo owner team to revisit.
D1 — JSON Schema (Draft 2020-12) as the authoring format
Alternatives considered: Protobuf (.proto), YAML, custom DSL.
Choice: JSON Schema.
Why:
- Idiomatic for .NET 10 (System.Text.Json + JsonSchema.Net) — OtOpcUa reads templates with no extra dependencies
- Idiomatic for CI tooling — every CI runner can
jqand validate JSON Schema without extra toolchain (ajv,jsonschema, etc.) - Best authoring experience: text format, mergeable in git, structured diffing, IDE autocomplete via the
$schemareference - Validation at multiple layers: operator-visible Admin UI errors in OtOpcUa, schemas-repo CI gates, downstream consumer runtime validation
- Protobuf is better for wire serialization (size, speed, generated code) but worse for authoring (binary, requires
.protocompiler, poor merge story in git) - Where wire-format efficiency matters (Redpanda events), we code-generate Protobuf from the JSON Schema source. One-way derivation is simpler than bidirectional sync.
D2 — Per-class versioning, semver
Alternatives considered: whole-repo versioning, no versioning.
Choice: each class file has its own version field (semver); the repo also tags overall releases.
Why:
- Different classes evolve at different rates (FANUC CNC may stabilize while Modbus PLC catalog grows)
- Consumers can pin per-class for fine-grained compatibility (e.g.
fanuc-cnc@0.1.0+modbus-plc@0.3.2) - Repo-level tags exist to bundle a known-good combination for consumers that want one anchor
D3 — Strict additive policy on minor bumps
Why: removes ambiguity. If I see class@1.3.0, I know its signal set is a strict superset of class@1.0.0 (and class@1.x.y for any earlier x.y). Breaking changes only happen at major-version boundaries.
D4 — _default reserved as placeholder for unused UNS levels
Imported from lmxopcua/docs/v2/plan.md decision #108.
Why: some sites have no Area-level distinction (single-building sites). Rather than letting the UNS path have inconsistent depth across sites, we mandate 5 levels always with _default as the placeholder. Downstream consumers can rely on path depth.
D5 — Tag names use PascalCase or snake_case (class's choice), NOT UNS-segment regex
Why: UNS path segments (Enterprise/Site/Area/Line/Equipment) are infrastructure-level identifiers — they go on the wire of every browse, every URI, every dashboard filter. The regex (^[a-z0-9-]{1,32}$) reflects that constraint.
Signal names (level 6) are vocabulary-level identifiers — they live inside an equipment node. Keeping them in PascalCase or snake_case (e.g. RunState, actual_feedrate) is more readable for operators looking at OPC UA browse output, and matches OPC UA SDK conventions which expect identifier-style names rather than URL-safe slugs.
D6 — stateModel is informational, not authoritative
Why: state derivation lives at Layer 3 (System Platform / Ignition). Placing the derivation rules in the schemas repo would create dual sources of truth (and the schemas-repo version would inevitably drift). Instead, the class template lists which states the class supports + an informational note about what the rough mapping looks like; Layer 3 owns the actual derivation logic.
D7 — No per-equipment overrides at this layer
Why: per-equipment config (which specific CNC has which program, etc.) is OtOpcUa's central config DB concern. Mixing per-instance config with per-class definitions in this repo would muddy the separation and cause the repo to grow with deployment-specific data instead of staying small + reusable.
D8 — applicability.drivers lists OtOpcUa drivers explicitly
Why: the schemas repo is OT-side-focused. The OtOpcUa driver enumeration is the closest thing to a canonical "how do you get raw data from this equipment" vocabulary that exists across the org. If a future class is populated by a non-OtOpcUa source, the field becomes optional or extends. For now, listing OtOpcUa driver IDs makes the consumer-side validation (per lmxopcua/docs/v2/plan.md decision #111 — driver type ↔ namespace kind) trivial.