Document: 5 of 5
Type: Architecture Decision Log
Version: 1.1
Status: Architecture Review Candidate
Compatibility: OCETS 1.1
Architecture Decision Records document why OCETS decisions were made.
The standard defines the rules. ADRs preserve the reasoning behind those rules so future maintainers can distinguish intentional design from historical accident.
Each ADR SHOULD include:
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric
Catalogue
Energy telemetry arrives from different vendors and protocols using different units, scale factors, register encodings, and firmware conventions. One inverter may report watts, another kilowatts, and a meter may expose scaled integer registers.
If unit conversion is deferred to dashboards or queries, different consumers may interpret the same value differently. This produces inconsistent visualizations, invalid comparisons, and fragile alert rules.
Each physical quantity has exactly one canonical storage unit.
Unit conversion occurs during ingestion before canonical storage.
Stored OCETS telemetry uses practical engineering units such as
kW, kWh, V, A,
Hz, degC, and percent.
Dashboards and downstream consumers can assume stable units.
Ingestion mappings must handle vendor-specific scale factors correctly and must be tested with captured source data.
Changing a canonical unit is a breaking change because retained data, dashboards, and alert rules depend on the stored meaning.
Storing vendor-native units was rejected because it pushes semantic repair into every consumer. Storing SI base units everywhere was rejected because it makes operational dashboards less practical and increases the likelihood of display-time conversion mistakes.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Plant Registry
Specification
The same metric may apply to different physical or electrical locations. For example, active power may be measured at an inverter output, grid connection, battery interface, site load, PV string, or transformer secondary.
Creating a separate metric name for each location causes metric proliferation and makes cross-system comparison difficult.
OCETS separates Metric from Measurement Point.
The Metric defines what is measured. The Measurement Point defines
where it is measured. Labels such as role,
phase, direction, string, and
mppt further qualify the measurement when needed.
Queries can compare the same metric across multiple locations without creating many metric names.
The registry must define Measurement Points explicitly and keep their identifiers stable.
Implementations must map vendor fields into both a canonical metric name and a Measurement Point, not merely rename fields.
Encoding location into metric names was rejected because it creates avoidable duplicates such as battery-specific or PV-string-specific power metrics. Relying only on device identity was rejected because one Device may expose several semantically distinct points.
Status: Accepted
Date: July 2026
Affected Documents: OCETS
Telemetry may pass through collectors, brokers, queues, processors, and databases. Each stage has a different processing time and can experience delay or retry behavior.
Using storage time or receive time as the measurement timestamp makes delayed telemetry appear to have occurred later than it did.
Telemetry timestamps represent acquisition time.
Processing time, transport time, receive time, and storage time do not replace acquisition time. Stored timestamps are represented in UTC.
Acquisition components must assign or preserve timestamps.
Pipeline delay can be monitored separately from measurement time.
Backfilled or delayed telemetry remains analytically useful because the original measurement time is retained.
Using storage time was rejected because it hides transport delay. Using dashboard render time was rejected because it changes every time data is viewed. Allowing each layer to overwrite timestamps was rejected because it destroys event ordering.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Reference Implementation
Guide
Distributed acquisition systems require consistent time. Edge collectors may run independently and continue collecting during connectivity interruptions.
Clock skew across collectors makes plant-level correlation unreliable, especially when comparing fast-changing power, frequency, and communication-health signals.
Acquisition systems synchronize against a centrally managed time service or an equivalent redundant time source.
Timestamp generation remains local to acquisition, but the local clock must be monitored and corrected.
The platform can detect timestamp skew.
Telemetry remains usable during temporary transport disruptions if local clocks remain synchronized.
Operational monitoring must include time synchronization health.
Relying on database write time was rejected for the reasons in ADR-003. Requiring a single central acquisition point was rejected because OCETS must support edge and hybrid topologies.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric
Catalogue
High-resolution telemetry is valuable for short-term diagnosis, while long-term storage requires downsampling. Different metrics require different aggregation behavior: gauges may average cleanly, counters require deltas, and states often need worst or last semantics.
Retention duration depends on operational, legal, and storage-cost policy. Downsampling semantics depend on metric meaning.
OCETS v1.1 makes downsampling semantics normative and treats retention durations as reference policy.
The metric catalogue defines aggregation behavior for each metric. Implementations may choose retention durations appropriate to their operating environment if the semantic aggregation rules are preserved.
Retention can be optimized without destroying semantic meaning.
The metric catalogue must define aggregation behavior.
Operators can adjust storage policy without creating a new OCETS version, provided they do not change metric semantics.
Mandating exact retention periods was rejected because storage constraints vary by deployment. Leaving downsampling entirely implementation-specific was rejected because it leads to invalid long-term aggregates.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Reference Implementation
Guide
Plants may be connected through different network conditions and operational models. Some installations favor central collection. Others require edge buffering, local polling, or hybrid acquisition.
Topology differences should not change telemetry semantics.
OCETS supports central, edge, and hybrid acquisition topologies.
All topologies must emit identical canonical telemetry for identical measurements.
The standard remains independent of deployment topology.
Reference implementations can evolve without changing canonical semantics.
Implementation-specific routing, buffering, and transport details remain outside the normative model.
Mandating edge acquisition was rejected because some plants are reachable and simple enough for central acquisition. Mandating central acquisition was rejected because it cannot handle every site topology or resilience requirement.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Plant Registry
Specification, Reference Implementation Guide
Manual duplication of plant, device, label, dashboard, and collector configuration causes drift. Drift leads to inconsistent labels, duplicate time series, onboarding errors, and difficult audits.
A prose-only registry definition is not enough because invalid data can still be merged or deployed.
The Plant Registry is the authoritative source of truth for logical platform objects and is schema-enforced.
Operational configuration should be generated from the registry. Registry data must be validatable before generated configuration or documentation is produced.
New plant onboarding becomes primarily a configuration task.
Registry governance becomes operationally important.
Implementations must maintain validation checks for required fields, controlled vocabularies, references, and identity scope.
Using generated collector configuration as the source of truth was rejected because generated files are implementation artifacts. Maintaining a spreadsheet-only registry was rejected because it is hard to validate rigorously and integrate into deployment workflows.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric
Catalogue
Missing data, stale data, measured zero, communication failure, device failure, and validation failure are different conditions.
If health is inferred only from process values, dashboards and automation may make incorrect assumptions. For example, missing inverter power is not the same as zero inverter power.
Telemetry health is modeled explicitly using canonical operational metrics.
Health includes device availability, communication status, collector status, freshness, timestamp skew, mapping errors, and validation errors.
Consumers can distinguish process state from telemetry pipeline state.
Implementations must collect and expose health signals.
Alerting can be based on explicit operational conditions rather than fragile inference.
Inferring health from absent samples was rejected because it cannot distinguish outage classes. Using implementation-specific process checks alone was rejected because consumers need health in the same semantic model as process telemetry.
Status: Accepted
Date: July 2026
Affected Documents: All OCETS documents
The platform may use concrete tools and vendor integrations, but those tools will evolve. Vendor register maps, collector configurations, storage backends, and dashboard frameworks change faster than the canonical information model.
Embedding tool-specific implementation details in the normative standard would make the standard unstable.
The normative standard excludes collector configuration, transport topic examples, vendor register maps, transformation scripts, dashboard definitions, and deployment details.
Those details belong in the Reference Implementation Guide or implementation-specific appendices.
The normative standard can remain stable while implementation documentation changes.
Conformance is based on emitted canonical telemetry and registry semantics, not on using a particular software stack.
Making the current implementation the standard was rejected because it would freeze incidental choices. Keeping all content in one document was rejected because it mixes durable semantics with operational recipes.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric Catalogue,
Reference Implementation Guide
Time-series systems commonly represent a series using a metric name plus labels. Some implementations also add a label that repeats the metric name.
Duplicating the metric name as both name and label creates unnecessary cardinality and introduces opportunities for contradiction.
OCETS uses the metric name itself as the canonical metric representation.
Telemetry does not need a redundant label that restates the metric name. Labels describe context such as Plant, Asset, Device, Measurement Point, role, phase, direction, string, or MPPT channel.
The model is simpler and easier to validate.
Queries should use metric names directly.
Implementations with legacy redundant labels may retain them as non-canonical implementation metadata during migration, but they are not OCETS compatibility requirements.
Keeping a redundant metric label was rejected because it adds no semantic value. Using only labels without canonical metric names was rejected because it makes storage and query behavior harder to standardize.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric Catalogue,
Reference Implementation Guide
Power sign conventions vary by vendor and by device. Battery power is especially inconsistent: some devices report discharge as positive, others report charge as positive. Grid meters may also differ on import and export signs.
Without a common convention, dashboards and derived metrics are unreliable.
OCETS defines a role-based sign convention for instantaneous power.
PV generation/export is positive. Consumer/load power is positive. Battery charging is positive and battery discharge/export is negative. Grid import into the plant is positive and grid export from the plant is negative.
Ingestion mappings must apply sign normalization before canonical storage.
The same generic metric, such as active_power, can
represent different roles without domain-specific duplicate metric
names.
Documentation and tests must make the convention explicit for each vendor mapping.
Adopting vendor-native signs was rejected because signs would vary within one platform. Making all export positive was rejected because load and battery operational views become less intuitive. Using separate metric names for charge and discharge power was rejected for instantaneous power because it fragments a single physical quantity.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Plant Registry
Specification
Energy platforms often evolve from monitoring into control, dispatch, and optimization. Those domains introduce safety, authorization, audit, failure-mode, and write-side semantics that are materially different from telemetry semantics.
Including control in v1.1 would slow down the telemetry model and risk underspecified write behavior.
OCETS v1.1 is telemetry-only.
Control commands, setpoints, dispatch semantics, actuator writes, and optimization requests are outside the normative v1.1 scope.
The v1.1 model can focus on stable telemetry semantics.
Control-capable devices can still be represented as Assets and Devices, but their write-side behavior is not standardized by v1.1.
Future control work can define separate safety and authorization requirements.
Including minimal setpoint support was rejected because even simple writes require policy and safety semantics. Ignoring control-capable equipment entirely was rejected because such equipment still emits telemetry.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric
Catalogue
Forecasts have different semantics from observed telemetry. They require issue time, validity time, horizon, model identity, confidence, and revision behavior.
Mixing forecasts into the v1.1 telemetry catalogue without those semantics would create ambiguity.
Forecast-generation models are deferred from OCETS v1.1. Externally
generated forecast Observations may use canonical Metrics with
origin=forecast only when they carry explicit issue and
validity times.
The catalogue remains focused while consumers can distinguish forecast values from measurements. Model training, confidence, revisions, and generation remain outside OCETS conformance.
Adding simple forecast metric names was rejected because it would not define enough context to compare or revise forecasts. Treating forecasts as ordinary gauges was rejected because forecast validity time is not acquisition time.
Status: Accepted
Date: July 2026
Affected Documents: All OCETS documents
Existing deployments may contain legacy names, vendor-derived field names, or locally meaningful labels. Preserving those names as normative compatibility requirements would permanently couple OCETS to historical implementation details.
Migration still matters, but it should not define the standard.
OCETS v1.1 makes a clean break from legacy and vendor-specific naming.
Legacy migration may be documented separately in implementation notes or migration guides. It is not part of the normative compatibility model.
The standard can optimize for long-term clarity rather than short-term name preservation.
Implementations must provide mapping and migration logic where existing deployments need continuity.
Conformance is evaluated against canonical output, not historical source names.
Preserving legacy names as aliases was rejected because aliases tend to become permanent compatibility burdens. Omitting migration guidance entirely was rejected because deployments still need practical transition paths.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric Catalogue,
Plant Registry Specification, Reference Implementation Guide
Plant-local collectors can remain reachable while silently losing data through clock drift, full storage, exhausted buffers, failed mapping, or upstream transport failure. Collector status alone does not establish that telemetry is current, correct, or recoverable. Conversely, standardizing every operating-system metric would turn OCETS into a general infrastructure-monitoring standard.
OCETS defines an optional Edge Collector Observability Profile. The canonical baseline covers availability, collector and pipeline state, acquisition freshness, clock synchronization, buffering, telemetry storage, transport errors, restarts, mapping, and validation. Portable CPU, memory, temperature, external-power, and backup-power signals are optional.
Hardware-specific sensors, kernel diagnostics, interface and filesystem names, certificate details, authentication logs, and configuration-integrity mechanisms remain implementation monitoring. They may support canonical state derivation but do not define canonical identity.
Operators can distinguish a healthy measured zero from a collector, clock, storage, buffering, or delivery failure. Central-only implementations remain conformant without claiming the profile. Edge implementations can expose additional diagnostics without making consumers depend on Ubuntu, Raspberry Pi, Telegraf, or another implementation choice.
Making host monitoring mandatory for every deployment was rejected because central-only topologies do not have an edge host. Guidance without a claimable profile was rejected because it cannot be tested consistently. Canonicalizing all operating-system metrics was rejected because those metrics are platform-specific and extend beyond energy telemetry continuity.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric Catalogue,
Reference Implementation Guide
A value and timestamp cannot distinguish direct acquisition from estimation, substitution, simulation, manual correction, or an invalid sample.
OCETS defines Observation as the logical telemetry record and makes quality and provenance mandatory, orthogonal properties. Storage may split the logical record if every property remains reconstructable.
Consumers can apply explicit trust policy. Ingestion and downsampling must preserve metadata without creating unbounded label cardinality.
Inferring quality from missing samples and encoding origin in metric names were rejected because both lose information and fragment canonical identity.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Plant Registry
Specification
Alarms, faults, maintenance, restarts, and acknowledgements have identity, interval, correlation, and lifecycle semantics that ordinary samples do not have.
OCETS defines a canonical Event envelope and event-type vocabulary separate from Metrics and Observations.
Implementations need a durable event representation with idempotent updates and audit history. Time-series values remain free of event lifecycle ambiguity.
Boolean alarm Metrics and free-form logs were rejected because they cannot preserve acknowledgement, correlation, or interval history consistently.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Plant Registry
Specification
The ownership hierarchy cannot represent electrical flow, connectivity, measurement, containment, control responsibility, and operational power dependencies over time.
OCETS models stable typed Relationships inside immutable, versioned physical, electrical, or telemetry Topologies. Graph endpoints are existing registered objects.
Topology remains historically interpretable and independent of diagrams. Validation must enforce endpoint type, tenant boundary, validity, symmetry, and containment-cycle rules.
Embedding anonymous graph nodes and deriving topology from names were rejected because neither provides stable identity or governed history.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Plant Registry
Specification
Portfolios and Plants need ownership, authorization, residency, and governance boundaries at platform scale.
Organization is the tenant boundary. Portfolios group Plants within one Organization; globally unique Plant identity remains unchanged.
Cross-tenant Registry relationships are invalid. Consumers can group Plants flexibly without coupling series identity to a portfolio name.
Using Portfolio as ownership and embedding tenant names in Plant IDs were rejected because portfolios change and a Plant may belong to several groupings.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Plant Registry
Specification
File-only Registry access does not scale to many clients, large registries, caching, incremental synchronization, or tenant-scoped discovery.
OCETS defines an authenticated HTTP/JSON read profile with immutable revisions, snapshots, changes, cursor pagination, filtering, ETags, and stable errors. Mutation workflows remain implementation-specific.
Clients can interoperate without making a particular database or approval system normative.
A mandatory GraphQL service and a complete write API were rejected because they constrain implementation and governance unnecessarily.
Status: Accepted
Date: July 2026
Affected Documents: All OCETS documents
Stable identities and multi-tenant APIs are unsafe without authentication, authorization, secret handling, encryption, rotation, and audit requirements.
OCETS makes security controls normative while remaining independent of a specific identity provider, certificate authority, VPN, or secret store.
Conformance requires default-deny tenant isolation, protected transport, distinct workload and human identities, rotation, least privilege, and auditable sensitive actions.
Treating network location as trust and leaving security entirely to deployments were rejected because they prevent meaningful interoperable conformance.
Status: Accepted
Date: July 2026
Affected Documents: OCETS, Canonical Metric Catalogue,
Registry API
Lifecycle status alone does not reveal when a Metric entered, changed status, or received a replacement, which makes historical interpretation and client migration unreliable.
Metric definitions are immutable and carry definition, introduction, deprecation, removal, and replacement version metadata. Incompatible meaning changes still require a new name or OCETS major version.
Catalogue releases remain reproducible and API clients can plan migrations explicitly.
Editing published definitions in place was rejected because historical telemetry would silently change meaning.