Files

Joseph Doherty 5953685ffb Seed the canonical OT schemas content under 3yearplan/schemas/ as a temporary location until a dedicated schemas repo is created (Gitea push-to-create is disabled, the dedicated repo needs a manual UI step). Initial seed contributed by the OtOpcUa team to unblock the EquipmentClassRef integration timeline (lmxopcua decision #112 ) and to provide the future cross-team owner with a concrete starting point rather than a blank slate. Marked DRAFT throughout with prominent "ownership TBD" framing in README and CONTRIBUTING — the future owner team should treat this seed as a starting point and revise format / structure / naming as the open questions in README "Open Questions" get resolved.

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>

2026-04-17 12:35:27 -04:00

2.9 KiB

Raw Permalink Blame History

Contributing

Initial seed by the OtOpcUa team. Future ownership TBD — the contribution process below is a starting suggestion the schemas-repo owner team should ratify or revise.

Workflow (proposed)

Open an issue first for any new equipment class, UNS subtree, or format change. Describe the use case + the consumer(s) that need it.
Branch + PR — work on a feature branch, open a PR against main.
CI gate validates every JSON file against the schema in format/.
Review — at least one schemas-repo maintainer + one consumer-team representative (OtOpcUa, Redpanda, or dbt depending on what changed).
Merge + tag — merge to main and create a semver tag. Consumers pin to tags.

Adding a new equipment class

Create classes/{class-id}.json (lowercase hyphenated).
Reference the class schema: "$schema": "../format/equipment-class.schema.json".
Fill in: classId, version (start at 0.1.0), displayName, vendor, applicability, signals, optionally alarms and stateModel.
Validate locally — the CI gate will reject malformed JSON or schema violations.
Open the PR with a brief description of which equipment populations are covered.

Adding a new UNS subtree

Create uns/{site-name}.json.
Reference the schema: "$schema": "../format/uns-subtree.schema.json".
Fill in: enterprise (must match the org-wide value), site, displayName, areas with lines.
Coordinate with the OtOpcUa team — every cluster at the site must declare its Enterprise and Site matching this file.

Format changes

Editing files in format/ is a breaking change for downstream consumers. Process:

Open an issue with the proposed change + rationale.
Notify all consumer teams (OtOpcUa, Redpanda, dbt, anyone else listed in docs/consumer-integration.md).
Get explicit signoff from each before merging.
Bump the major version of every affected class file simultaneously (consumers use this to detect breaking changes).

Validation

# Per-file validation
ajv validate -s format/equipment-class.schema.json -d classes/fanuc-cnc.json
ajv validate -s format/uns-subtree.schema.json -d uns/example-warsaw-west.json

# Bulk validate everything
for f in classes/*.json; do ajv validate -s format/equipment-class.schema.json -d "$f"; done
for f in uns/*.json; do ajv validate -s format/uns-subtree.schema.json -d "$f"; done

Versioning policy (proposed)

Major bump (0.x.y → 1.x.y) — breaking change: signal removed, signal renamed, dataType changed, isRequired changed false→true, alarm removed
Minor bump (x.0.y → x.1.y) — additive non-breaking: new optional signal, new alarm, new state in stateModel, displayName/description updates
Patch bump (x.y.0 → x.y.1) — documentation/clarification only: description text updates, examples added, no semantic change

Consumers pin to a major.minor in production; staging environments can track main.

2.9 KiB Raw Permalink Blame History