3yearplan/schemas/CONTRIBUTING.md

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)

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

Adding a new equipment class

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

Adding a new UNS subtree

1. Create uns/{site-name}.json.
2. Reference the schema: "$schema": "../format/uns-subtree.schema.json".
3. Fill in: enterprise (must match the org-wide value), site, displayName, areas with lines.
4. 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:

1. Open an issue with the proposed change + rationale.
2. Notify all consumer teams (OtOpcUa, Redpanda, SnowBridge, anyone else listed in docs/consumer-integration.md).
3. Get explicit signoff from each before merging.
4. 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.