SingleTimeSeries

Package: InfrastructureTimeSeriesOpenAPIModels · Source: TimeSeries/SingleTimeSeries.json

A static time series on a regular grid: values at initial_timestamp + k * resolution. One of a closed set of six canonical time series types owned by the data layer. This schema records the association and its metadata; the dense values live in the store named by uri.

Properties

Property	Type	Required	Unit	Description
association_id	integer	yes	—	Surrogate id of this association, minted by the store that holds it. Assigned once when the association is created and never changed: renaming the series or reassigning its owner leaves it alone, so a consumer may persist it as a durable reference. Ids are never reused, and they are store-local — resolve one against the same store the document was exported from, not against an independently built store. Assigned by the store, never by a document author.
owner_id	integer	yes	—	ID of the owning component or supplemental attribute. The producing data layer allocates both from one id stream, so an owner_id never collides across the two categories; owner_category remains required because the store’s catalog contract still supports independent streams from other producers, and it is still the store’s disambiguator.
owner_type	string	yes	—	Type name of the owning entity. Descriptive, not part of the series’ identity.
owner_category	string (OwnerCategory)	yes	—	Whether the owner is a component or a supplemental attribute.
time_series_type	string	yes	—	Discriminator. Fixed to SingleTimeSeries for this schema, pinned with const to match this repo’s existing discriminators (Core/common.json’s curve_type), which generate a plain string literal in both toolchains.
name	string	yes	—	Time series name (e.g. max_active_power). Part of the series’ identity, and often carrying a disambiguating suffix; component_field records what the values are for.
features	TimeSeriesFeatures	yes	—	User-defined key/value tags that are part of the series’ identity: two series differing only by a feature are distinct series. Feature names that collide with a field of a series or of the tuple addressing one are rejected.
uri	string	yes	—	Locator for the dense data, unique within one store. No required format — typically a file path or an HDF5 dataset path; the backing store decides what it means and resolves it (infrastore uses its content hash as this value). Never parsed or interpreted here. This layer records where the values are, never the values.
data_hash	string	—	—	Content hash of the stored array: SHA-256, hex-encoded. Optional — not every producer computes it.
element_type	string	yes	—	What one timestep’s values mean and how they are laid out. The physical dtype of the stored bytes derives from this and is not recorded separately. Unlike units and quantity_kind this is not a user-facing label — the writing package derives it from the array.
element_shape	array of integer	yes	—	Per-step element shape: the trailing dims after time. An empty array means a scalar element.
array_shape	array of integer	—	—	Full native shape of the stored array, in the order the store holds it: the first axis is the array’s length and the trailing axes end with element_shape. Static types are [length, *element_shape]; a deterministic forecast stacks windows as [horizon_count, count, *element_shape]; probabilistic and scenarios forecasts add a percentile or scenario axis in front of that. Optional, and redundant for the static types, where it is exactly [length] + element_shape. It earns its place on the forecasts, whose array layout is a convention the producing package owns rather than a rule this layer enforces, so the stored geometry cannot be reconstructed from horizon, count, percentiles, and scenario_count alone. A consumer that has it should prefer it; one that does not falls back to those fields, which is exact for the static types and a best effort for the forecasts.
units	string	—	—	Unit label for the series values. Set by whoever creates the series and returned unchanged; not part of the series’ identity, so two series differing only in this label are duplicates. Meaningless on its own when unit_system is a per-unit basis, where the values are dimensionless. By convention drawn from the unit vocabulary in Core/units.json, though this field is a free-text label the store does not validate against it.
quantity_kind	string	—	—	Kind of physical quantity the values measure (e.g. ActivePower, ReactivePower, ElectricalEnergy). Coarser than units but finer than a dimension: ActivePower, ReactivePower, and ApparentPower share the dimension {M:1,L:2,T:-3}, so a dimension cannot tell them apart and a quantity kind can. It is also the only record of what the values measure when unit_system is a per-unit basis.
unit_system	string (UnitSystem)	—	—	Basis the series values are already expressed in. A declaration, not a conversion: nothing here rescales values, and converting a COMPONENT_BASE series back to natural units needs the owning component’s base_power. Absent means unspecified, which is deliberately not the same as NATURAL_UNITS.
time_reference	string	—	—	How this series’ timestamps were spelled, so a read hands back what the write declared instead of relabelling everything UTC. Absent means unspecified, which is not a claim the timestamps were written as UTC.
component_field	string	—	—	The field on the owning component or supplemental attribute whose value these values are the time-varying form of (e.g. max_active_power, rating). Free-form: it names a field in the consumer’s own object model. Records what the values are for, where name only says which series they are.
application_data	string	—	—	Opaque, package-owned payload (typically JSON) carried verbatim for an application to reconstruct its own domain objects. Never parsed or interpreted here, and end users are not expected to set it. Element typing does not belong here — that is element_type.
initial_timestamp	string	yes	—	First timestamp of the regular grid; every later step lands at initial_timestamp + k * resolution. An RFC3339 string with at most 3 fractional-second digits: the store’s floor is one millisecond, matching Julia’s millisecond-precision DateTime.
resolution	string	yes	—	Cadence of the regular grid. Always present for a SingleTimeSeries, and part of the series’ identity.
length	integer	yes	—	Number of timesteps.