Feat: make soc-min and soc-max canonical with sensor defaults

[BelhsanHmida]

Description

• Make soc-min and soc-max the canonical fields for fixed and dynamic storage SoC boundaries.
• Allow dynamic soc-min / soc-max values through sensor references and time-series specifications.
• Add a generic default field to sensor references for filling missing sensor values.
• Keep soc-minima and soc-maxima supported as deprecated legacy aliases.
• Reject ambiguous combinations of canonical and legacy dynamic fields.
• Preserve backwards compatibility for fixed SoC bounds and fixed-plus-legacy configurations.
• Make scalar soc-min / soc-max follow the default SoC relaxation behavior.
• Reject default: null.
• Update the API, UI, scheduling documentation, changelog, and OpenAPI specifications.
• Allow configuring sensor-reference fallbacks through the flex-model UI
• Add changelog entry

Look & Feel

N/A

Example API flex-model shape:

{
  "soc-at-start": "12 kWh",
  "soc-min": {
    "sensor": 300,
    "default": "10 kWh"
  },
  "soc-max": {
    "sensor": 301,
    "default": "25 kWh"
  },
  "power-capacity": "5 kW"
}

How to test

• pytest:

uv run pytest \
  flexmeasures/data/schemas/tests/test_sensor.py \
  flexmeasures/data/schemas/tests/test_scheduling.py \
  flexmeasures/data/models/planning/tests/test_storage.py \
  flexmeasures/data/models/planning/tests/test_utils_fresh_db.py \
  tests/documentation/test_openapi_spec.py

• Manual API-style check:
  Use a storage flex-model where soc-min and soc-max are dynamic sensor references with defaults:

{
  "flex-model": {
    "soc-at-start": "12 kWh",
    "soc-min": {
      "sensor": 300,
      "default": "10 kWh"
    },
    "soc-max": {
      "sensor": 301,
      "default": "25 kWh"
    },
    "power-capacity": "5 kW"
  }
}

Expected behavior: soc-min and soc-max are treated as dynamic SoC boundaries, missing sensor values are filled with the provided default values, default: null is rejected, and scalar soc-min / soc-max are soft by default when SoC relaxation is active.

Further Improvements

• Handle recurring SoC limits separately in Recurring SoC limits #2255.

Related Items

• Closes Make soc-minima and soc-maxima the default, simplifying usage #2251
• Related to Feat/retire fallback scheduler #2252
• Related follow-up: Recurring SoC limits #2255

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or other license that is incompatible with FlexMeasures

[Copilot]

Pull request overview

This PR updates FlexMeasures’ storage flex-model schema to make soc-min / soc-max the canonical fields for both fixed and dynamic SoC boundaries, adds a default fallback to sensor references for filling missing values, and keeps soc-minima / soc-maxima as deprecated legacy aliases (including OpenAPI + docs updates).

Changes:

• Extend VariableQuantityField / SensorReference to support a default fallback quantity and apply it when fetching belief series
• Route dynamic soc-min / soc-max payloads to the internal dynamic-boundary handling while rejecting ambiguous combinations with legacy aliases
• Update tests, docs, and regenerated OpenAPI specs/examples to reflect the new canonical behavior and deprecations

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
flexmeasures/ui/static/openapi-specs.json	Regenerated OpenAPI specs/examples for canonical soc-min / soc-max, default fallback, and deprecated aliases
flexmeasures/data/schemas/tests/test_sensor.py	Add tests for deserializing/serializing sensor references with default
flexmeasures/data/schemas/tests/test_scheduling.py	Add schema tests for soc-min / soc-max dynamic sensor refs with default, plus mutual exclusivity cases
flexmeasures/data/schemas/sensors.py	Implement default handling in VariableQuantityField + SensorReference and update time series schema examples
flexmeasures/data/schemas/scheduling/storage.py	Switch soc_min / soc_max to VariableQuantityField, deprecate legacy metadata, and map dynamic canonical fields to legacy dynamic keys post-load
flexmeasures/data/schemas/scheduling/metadata.py	Update field descriptions/examples to document canonical dynamic behavior and mark legacy aliases deprecated
flexmeasures/data/schemas/scheduling/init.py	Update UI schema text for SoC boundaries and legacy alias labeling
flexmeasures/data/models/planning/utils.py	Apply SensorReference.default to fill missing values in queried belief series
flexmeasures/data/models/planning/tests/test_utils_fresh_db.py	Add integration test ensuring default fills missing belief slots
flexmeasures/data/models/planning/tests/test_solver.py	Extend solver tests to cover canonical dynamic soc-min / soc-max and time-series cases
flexmeasures/data/models/planning/storage.py	Update internal comment to reflect new deserialization routing for dynamic soc-max
flexmeasures/api/v3_0/sensors.py	Update API example payload to use canonical soc-min sensor reference with default
flexmeasures/api/v3_0/assets.py	Update API example payload to use canonical soc-min for time-series specs
documentation/features/scheduling.rst	Update scheduling docs to describe dynamic soc-min / soc-max relaxation behavior and legacy aliases
documentation/api/introduction.rst	Update API introduction note on default relaxation behavior for dynamic SoC boundaries

[BelhsanHmida]

A couple of follow-up questions:

1. I implemented default on the generic sensor reference schema rather than special-casing it for soc-min / soc-max. This means other fields that accept sensor references could also use default now. Is that an acceptable API shape, or should fallback defaults be restricted to dynamic SoC bounds only?

2. Fixed scalar soc-min / soc-max remain hard physical limits, while dynamic soc-min / soc-max are mapped to the existing relaxed soc-minima / soc-maxima scheduler path. Is that the distinction we want?

3. I kept fixed soc-min / soc-max together with legacy soc-minima / soc-maxima valid for backwards compatibility. Should we keep allowing that, or should it eventually warn/reject?

4. I treat default: null the same as omitting default. Is that acceptable?

5. I marked soc-minima and soc-maxima as deprecated in docs/OpenAPI metadata, but did not add runtime deprecation warnings when users still send them. Is metadata-only deprecation enough for this PR, or should we also emit runtime warnings for legacy soc-minima / soc-maxima usage?

[Flix6x]

A couple of follow-up questions:

Here are my answers.

1. I implemented default on the generic sensor reference schema rather than special-casing it for soc-min / soc-max. This means other fields that accept sensor references could also use default now. Is that an acceptable API shape, or should fallback defaults be restricted to dynamic SoC bounds only?

That's actually great. This will be very useful for other fields, too, and the PR title+description, changelog entry and docs should reflect that.

2. Fixed scalar soc-min / soc-max remain hard physical limits, while dynamic soc-min / soc-max are mapped to the existing relaxed soc-minima / soc-maxima scheduler path. Is that the distinction we want?

Not quite. In v1 we are moving to relaxing constraints by default (this already landed on main). So also a scalar soc-min/max should be a soft limit, unless the user explicitly turns off the soc relaxation (by setting either relax-constraints or relax-soc-constraints to False).

(Effectively, before this PR the user had the possibility of setting both hard and soft constraints for SoC limits, and now they have to pick one.)

3. I kept fixed soc-min / soc-max together with legacy soc-minima / soc-maxima valid for backwards compatibility. Should we keep allowing that, or should it eventually warn/reject?

Keep the support. No rejection, no warning, just a deprecation notice in the docs.

4. I treat default: null the same as omitting default. Is that acceptable?

Probably cleaner to use Marshmallow's defaults here, which are required=False, allow_none=False. Do you have a reason to explicitly allow null values?

5. I marked soc-minima and soc-maxima as deprecated in docs/OpenAPI metadata, but did not add runtime deprecation warnings when users still send them. Is metadata-only deprecation enough for this PR, or should we also emit runtime warnings for legacy soc-minima / soc-maxima usage?

It's enough. No runtime warnings needed right now.

[BelhsanHmida]

@Flix6x Thanks for the clarification. I addressed all five points:

• Kept default on the generic sensor-reference schema and updated the PR description, changelog, docs, OpenAPI, and UI accordingly.
• Scalar soc-min / soc-max now follow the default SoC relaxation behavior.
• Kept fixed bounds together with legacy soc-minima / soc-maxima for backwards compatibility.
• default: null is now rejected with required=False and allow_none=False.
• Legacy aliases remain supported with documentation/OpenAPI deprecation only; no runtime warnings were added.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33648802 | 📁 Comparing 3e0c6ae against latest (60cfda8)

  🔍 Preview build  

54 files changed · + 4 added · ± 50 modified

+ Added

• _autosummary/flexmeasures.data.models.planning.devices.html
• _autosummary/flexmeasures.data.models.planning.soc_projection.html
• _autosummary/flexmeasures.data.schemas.scheduling.utils.html
• host/multi-tenancy.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• getting-started.html
• http-routingtable.html
• index.html
• py-modindex.html
• _autodoc/RELAX_CONSTRAINTS.html
• _autodoc/RELAX_SOC_CONSTRAINTS.html
• _autodoc/SOC_MAX.html
• and 40 more...