--- title: "OCETS Architecture Decision Records" version: "1.1" status: "Architecture Review Candidate" release: "July 2026" identifier: "OCETS-ADR-1.1" --- # OCETS Architecture Decision Records **Document:** 5 of 5 **Type:** Architecture Decision Log **Version:** 1.1 **Status:** Architecture Review Candidate **Compatibility:** OCETS 1.1 ## 1. Purpose 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. ## 2. ADR Format Each ADR SHOULD include: - identifier; - title; - status; - date; - context; - decision; - consequences; - alternatives considered; - affected documents. ## ADR-001: Canonical Units **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue ### Context 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. ### Decision 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`. ### Consequences 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. ### Alternatives Considered 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. ## ADR-002: Measurement Points **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Plant Registry Specification ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-003: Timestamp Assignment **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-004: Central Time Service **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Reference Implementation Guide ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-005: Retention and Downsampling **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-006: Acquisition Topologies **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Reference Implementation Guide ### Context 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. ### Decision OCETS supports central, edge, and hybrid acquisition topologies. All topologies must emit identical canonical telemetry for identical measurements. ### Consequences 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. ### Alternatives Considered 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. ## ADR-007: Schema-Enforced Registry as Source of Truth **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Plant Registry Specification, Reference Implementation Guide ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-008: Telemetry Health as First-Class Telemetry **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-009: Implementation Separation **Status:** Accepted **Date:** July 2026 **Affected Documents:** All OCETS documents ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-010: Metric Name Only Representation **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue, Reference Implementation Guide ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-011: Role-Based Power Sign Convention **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue, Reference Implementation Guide ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-012: Telemetry-Only v1.1 Scope **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Plant Registry Specification ### Context 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. ### Decision OCETS v1.1 is telemetry-only. Control commands, setpoints, dispatch semantics, actuator writes, and optimization requests are outside the normative v1.1 scope. ### Consequences 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. ### Alternatives Considered 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. ## ADR-013: Forecast Generation Deferral **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue ### Context 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. ### Decision 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. ### Consequences The catalogue remains focused while consumers can distinguish forecast values from measurements. Model training, confidence, revisions, and generation remain outside OCETS conformance. ### Alternatives Considered 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. ## ADR-014: Legacy Clean Break **Status:** Accepted **Date:** July 2026 **Affected Documents:** All OCETS documents ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-015: Edge Collector Observability Boundary **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue, Plant Registry Specification, Reference Implementation Guide ### Context 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. ### Decision 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. ### Consequences 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. ### Alternatives Considered 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. ## ADR-016: Observation Quality and Provenance **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue, Reference Implementation Guide ### Context A value and timestamp cannot distinguish direct acquisition from estimation, substitution, simulation, manual correction, or an invalid sample. ### Decision 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. ### Consequences Consumers can apply explicit trust policy. Ingestion and downsampling must preserve metadata without creating unbounded label cardinality. ### Alternatives Considered Inferring quality from missing samples and encoding origin in metric names were rejected because both lose information and fragment canonical identity. ## ADR-017: Events Are Separate from Metrics **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Plant Registry Specification ### Context Alarms, faults, maintenance, restarts, and acknowledgements have identity, interval, correlation, and lifecycle semantics that ordinary samples do not have. ### Decision OCETS defines a canonical Event envelope and event-type vocabulary separate from Metrics and Observations. ### Consequences Implementations need a durable event representation with idempotent updates and audit history. Time-series values remain free of event lifecycle ambiguity. ### Alternatives Considered Boolean alarm Metrics and free-form logs were rejected because they cannot preserve acknowledgement, correlation, or interval history consistently. ## ADR-018: Versioned Relationship Graphs **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Plant Registry Specification ### Context The ownership hierarchy cannot represent electrical flow, connectivity, measurement, containment, control responsibility, and operational power dependencies over time. ### Decision OCETS models stable typed Relationships inside immutable, versioned physical, electrical, or telemetry Topologies. Graph endpoints are existing registered objects. ### Consequences Topology remains historically interpretable and independent of diagrams. Validation must enforce endpoint type, tenant boundary, validity, symmetry, and containment-cycle rules. ### Alternatives Considered Embedding anonymous graph nodes and deriving topology from names were rejected because neither provides stable identity or governed history. ## ADR-019: Organization as Tenant Boundary **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Plant Registry Specification ### Context Portfolios and Plants need ownership, authorization, residency, and governance boundaries at platform scale. ### Decision Organization is the tenant boundary. Portfolios group Plants within one Organization; globally unique Plant identity remains unchanged. ### Consequences Cross-tenant Registry relationships are invalid. Consumers can group Plants flexibly without coupling series identity to a portfolio name. ### Alternatives Considered Using Portfolio as ownership and embedding tenant names in Plant IDs were rejected because portfolios change and a Plant may belong to several groupings. ## ADR-020: Read-Only Registry API Profile **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Plant Registry Specification ### Context File-only Registry access does not scale to many clients, large registries, caching, incremental synchronization, or tenant-scoped discovery. ### Decision 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. ### Consequences Clients can interoperate without making a particular database or approval system normative. ### Alternatives Considered A mandatory GraphQL service and a complete write API were rejected because they constrain implementation and governance unnecessarily. ## ADR-021: Normative Security Baseline **Status:** Accepted **Date:** July 2026 **Affected Documents:** All OCETS documents ### Context Stable identities and multi-tenant APIs are unsafe without authentication, authorization, secret handling, encryption, rotation, and audit requirements. ### Decision OCETS makes security controls normative while remaining independent of a specific identity provider, certificate authority, VPN, or secret store. ### Consequences Conformance requires default-deny tenant isolation, protected transport, distinct workload and human identities, rotation, least privilege, and auditable sensitive actions. ### Alternatives Considered Treating network location as trust and leaving security entirely to deployments were rejected because they prevent meaningful interoperable conformance. ## ADR-022: Immutable Versioned Metric Definitions **Status:** Accepted **Date:** July 2026 **Affected Documents:** OCETS, Canonical Metric Catalogue, Registry API ### Context Lifecycle status alone does not reveal when a Metric entered, changed status, or received a replacement, which makes historical interpretation and client migration unreliable. ### Decision 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. ### Consequences Catalogue releases remain reproducible and API clients can plan migrations explicitly. ### Alternatives Considered Editing published definitions in place was rejected because historical telemetry would silently change meaning.