Field versioning¶

Field versioning and history¶

Why versioning is necessary¶

A field may be called “Stress 0–10” today and “Stress 1–5” later. If the existing definition were simply overwritten, older values would no longer have an unambiguous interpretation.

Steady therefore separates:

physical field ID: a concrete version,
logicalId: the same domain metric across several versions.

flowchart LR
    F1[stress<br/>Version 1<br/>id: stress] -->|Type or scale changed| F2[stress<br/>Version 2<br/>id: stress-xyz]
    F1 -. logicalId: stress .- F2
    F1 -->|retired / supersededBy| F2

When a new version is created¶

When historical values exist and a versioned property changes, the old field is retired and a replacement is created. These properties include:

labels and section,
type and options,
minimum, maximum, step and unit,
goal direction and target range,
default value and analytics permission.

How analytics handles versions¶

Explorer and analytics find all fields with the same logicalId. When reading a day, the field version whose ID is actually present in the daily entry is used.

flowchart TD
    E[Daily entry] --> K{Which field ID is present?}
    K --> V1[old version]
    K --> V2[new version]
    V1 --> L[shared logical metric]
    V2 --> L
    L --> A[aggregation]

Important for future changes¶

A new analytical property must be added to the list of versioned properties when changing it would alter historical meaning. Otherwise a new configuration could retroactively evaluate older data differently.

Field versioning¶