feat: allow setting a consumption/production sensor in the flex-model of an asset

documentation/api/change_log.rst

@@ -11,6 +11,8 @@ v3.0-31 | 2026-05-20
 - Added a unified job status endpoint ``GET /api/v3_0/jobs/<uuid>`` that returns the current execution status and a human-readable result message for any background job (scheduling, forecasting, etc.) identified by its UUID.
 - Switched from ``force_new_job_creation`` to ``force-new-job-creation`` (maintaining backwards compatibility) and added the field to `/assets/(id)/schedules/trigger` (POST) endpoint, too.
 - Support both snake_case and kebab-case fields in `/sensors/<id>/data` (GET), while only documenting the kebab-case ones.
+- The ``consumption`` and ``production`` flex-model fields for the ``StorageScheduler`` now act as output sensors: the scheduler writes the resulting power schedule to those sensors, with unit conversion and resampling applied. When only one of the two is defined, the full power profile is written (sign-inverted for the production sensor). When both are defined, the schedule is split into its non-negative (consumption) and non-positive (production) parts.
+- Added a ``sign-convention`` query parameter to ``GET /sensors/<id>/schedules/<uuid>`` with three modes: ``consumption-positive`` (default, unchanged behaviour), ``production-positive``, and ``wysiwyg`` (sign of database values and as seen in UI charts).
 
 v3.0-30 | 2026-04-15
 """"""""""""""""""""

documentation/api/notation.rst

@@ -302,3 +302,10 @@ We'd recommend to use positive power values to indicate consumption and negative
 
 Read more at :ref:`signs_of_power_beliefs` about our treatment of data, which includes data you send in, or you get from forecasts and schedules
 (hint: you are free to define the sign for your data, but it might affect how you receive your schedules).
+
+The ``GET /api/v3_0/sensors/<id>/schedules/<uuid>`` endpoint supports three sign conventions via the ``sign-convention`` query parameter:
+
+- ``consumption-positive`` (**default**): schedules are returned with consumption as positive values and production as negative values, regardless of how they are stored in the database.
+- ``production-positive``: schedules are returned with production as positive values and consumption as negative values.
+- ``wysiwyg`` (*what-you-see-is-what-you-get*): schedules are returned with the same sign as database values and as seen in the UI charts.
+  The values indicate exactly what was stored, which was itself governed by the sensor's ``consumption_is_positive`` attribute (if present) or the scheduler's default convention (which stored production as positive values in the database).

documentation/changelog.rst

@@ -23,6 +23,7 @@ New features
 * Improve UX after deleting a child asset through the UI [see `PR #2119 <https://www.github.com/FlexMeasures/flexmeasures/pull/2119>`_]
 * Improve source filtering in the sensor data GET endpoint by exposing the documented query parameters in Swagger and allowing filtering by the account linked to data sources [see `PR #2083 <https://www.github.com/FlexMeasures/flexmeasures/pull/2083>`_ and `PR #2151 <https://www.github.com/FlexMeasures/flexmeasures/pull/2151>`_]
 * Support sensor references for efficiency fields in storage flex-models [see `PR #2142 <https://www.github.com/FlexMeasures/flexmeasures/pull/2142>`_]
+* Introduce the ``consumption`` and ``production`` flex-model fields for the ``StorageScheduler`` to save schedules to [see `PR #2190 <https://www.github.com/FlexMeasures/flexmeasures/pull/2190>`_]
 * Added a unified job status endpoint ``GET /api/v3_0/jobs/<uuid>`` to retrieve the current execution status and result message for any background job [see `PR #2141 <https://www.github.com/FlexMeasures/flexmeasures/pull/2141>`_]
 * Add ``flexmeasures jobs inspect-job`` CLI command to show job status and metadata information (similar to the job status endpoint in the API) [see `PR #2202 <https://www.github.com/FlexMeasures/flexmeasures/pull/2202>`_]
 * New ``GET /api/v3_0/sources`` endpoint to list accessible data sources and defined types, with ``only_latest=true`` by default to return only the most recent version per source [see `PR #2126 <https://www.github.com/FlexMeasures/flexmeasures/pull/2126>`_]
@@ -141,6 +142,7 @@ Bugfixes
 
 
 v0.31.3 | April 11, 2026
+============================
 
 Bugfixes
 -----------

documentation/concepts/data-model.rst

@@ -79,6 +79,7 @@ A data source can be a FlexMeasures user, but also simply a named source from ou
 In FlexMeasures, data sources have a type. It is just a string which you can freely choose (we do not model them explicitly im the data model like Asset types).
 We do support some types out of the box: "scheduler", "forecaster" "reporter", "demo script" and "user".
 
+.. _beliefs:
 
 Beliefs
 ---------
@@ -156,7 +157,8 @@ More information, including code examples, is available in :ref:`annotations`.
 About signs of power & energy values
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In short: You can use any sign you want for power data.
-But the scheduler in FlexMeasures needs to know how to apply the signs. Positive (+) means consumption, negative (-) means production.
+What is recorded in the database is exactly as seen in UI charts.
+But the scheduler in FlexMeasures needs to know how to apply the signs.
 Let us explain.
 
 When beliefs are about power or energy, the sign of the value is important. It indicates whether the asset is consuming or producing.
@@ -168,12 +170,25 @@ For example, users can create PV power data with positive values indicating prod
 We allow this because we want the UI to match what is in the database, and users often desire both of these datasets to be shown as positive values.
 We assume that this is what users send in.
 
-Note that, if forecasts are created, they will have the same sign as original data.
+Note that, if forecasts are created, they will have the same sign as the original data.
 
-For schedules, the sign of resulting power data (beliefs) is being switched when data is stored (assuming consumption , and you can prevent that by setting ``sensor.attributes["consumption_is_positive"] = True``.
+For schedules, the sign of the power schedule (as :ref:`beliefs <beliefs>`) recorded in the database, and as seen in UI charts, is determined as follows:
 
+- If the flex-model contains the ``sensor`` field, and that sensor has power units (e.g. kW), the ``"consumption_is_positive"`` attribute of the sensor is used to decide the sign of the recorded data.
+  If `True`, consumption will be saved as positive, otherwise not. To clarify:
+  - If the attribute is not defined, **by default, scheduled power is recorded with production as positive values** (and consumption as negative values).
+  - To record scheduled power data with consumption as positive values, set ``sensor.attributes["consumption_is_positive"] = True``.
+  - To record scheduled power data with production as positive values (already the default, but this makes it explicit), set ``sensor.attributes["consumption_is_positive"] = False``.
+- If the flex-model contains the ``consumption`` field, scheduled power is recorded with consumption as positive values.
+  The ``"consumption_is_positive"`` attribute of the referenced sensor is set automatically to ``True``.
+- If the flex-model contains the ``production`` field, scheduled power is recorded with production as positive values.
+  The ``"consumption_is_positive"`` attribute of the referenced sensor is set automatically to ``False``.
 
-.. note:: We will soon document better what the scheduler does in detail, and how the attribute works.
+The ``GET /api/v3_0/sensors/<id>/schedules/<uuid>`` endpoint supports three sign conventions via the ``sign-convention`` query parameter:
+
+- ``consumption-positive`` (default): schedules are always returned with consumption as positive values and production as negative values.
+- ``production-positive``: schedules are returned with production as positive values and consumption as negative values.
+- ``wysiwyg`` (*what-you-see-is-what-you-get*): schedules are returned with the same sign as database values and as seen in the UI charts, indicating exactly what the scheduler stored.
 
 
 Accounts & Users

documentation/features/scheduling.rst

@@ -182,7 +182,13 @@ For more details on the possible formats for field values, see :ref:`variable_qu
 
    * - Field
      - Example value
-     - Description 
+     - Description
+   * - ``consumption``
+     - |CONSUMPTION.example|
+     - .. include:: ../_autodoc/CONSUMPTION.rst
+   * - ``production``
+     - |PRODUCTION.example|
+     - .. include:: ../_autodoc/PRODUCTION.rst
    * - ``state-of-charge``
      - |STATE_OF_CHARGE.example|
      - .. include:: ../_autodoc/STATE_OF_CHARGE.rst

flexmeasures/api/v3_0/sensors.py

@@ -65,7 +65,10 @@
 )
 from flexmeasures.data.schemas import AssetIdField, SourceIdField
 from flexmeasures.api.common.schemas.search import SearchFilterField
-from flexmeasures.data.schemas.scheduling import GetScheduleSchema
+from flexmeasures.data.schemas.scheduling import (
+    GetScheduleSchema,
+    ScheduleSignConvention,
+)
 from flexmeasures.data.schemas.units import UnitField
 from flexmeasures.data.services.sensors import get_sensor_stats
 from flexmeasures.data.services.sensors import delete_sensor as delete_sensor_and_data
@@ -1040,6 +1043,7 @@ def get_schedule(  # noqa: C901
         job_id: str,
         duration: timedelta,
         unit: str | None = None,
+        sign_convention: str = ScheduleSignConvention.CONSUMPTION_POSITIVE,
         **kwargs,
     ):
         """
@@ -1054,6 +1058,21 @@ def get_schedule(  # noqa: C901
 
             - "duration" (6 hours by default; can be increased to plan further into the future)
             - "unit" (by default, the unit of the schedule is the sensor's unit; a compatible unit can be requested)
+            - "sign-convention" (controls how power values are signed in the response; see below)
+
+            **Sign convention**
+
+            By default (``sign-convention: consumption-positive``), the endpoint always returns schedules where
+            consumption is positive and production is negative, regardless of how the values are stored in the database.
+            This is the most common convention and matches the perspective of a consumer.
+
+            Set ``sign-convention: production-positive`` to flip the sign so that production is returned as
+            positive and consumption as negative. This matches the perspective of a producer.
+
+            Set ``sign-convention: wysiwyg`` (*what-you-see-is-what-you-get*) to return the values with the same sign
+            as database values and what is seen in UI charts. The values will indicate exactly what is stored,
+            which is itself determined by the sensor's ``consumption_is_positive`` attribute (if set)
+            or by the scheduler's default storage convention (production positive in the database).
           security:
             - ApiKeyAuth: []
           parameters:
@@ -1095,6 +1114,21 @@ def get_schedule(  # noqa: C901
               example: kW
               schema:
                 type: string
+            - in: query
+              name: sign-convention
+              required: false
+              description: |
+                Sign convention applied to power values in the response.
+                - ``consumption-positive`` (default): consumption is positive, production is negative.
+                - ``production-positive``: production is positive, consumption is negative.
+                - ``wysiwyg`` (*what-you-see-is-what-you-get*): sign of database values and as seen in UI charts.
+              example: consumption-positive
+              schema:
+                type: string
+                enum:
+                  - consumption-positive
+                  - production-positive
+                  - wysiwyg
           responses:
             200:
               description: PROCESSED
@@ -1221,12 +1255,25 @@ def get_schedule(  # noqa: C901
         )
 
         sign = 1
-        if sensor.measures_power and not sensor.get_attribute(
-            "consumption_is_positive", False
-        ):
-            sign = -1
-
-        # For consumption schedules, positive values denote consumption. For the db, consumption is negative unless specified explicitly
+        if sign_convention == ScheduleSignConvention.WYSIWYG:
+            # Return values without adjusting the sign of database values.
+            # No sign inversion: what's in the DB and what is seen in UI charts is what the caller receives.
+            pass
+        elif sensor.measures_power:
+            # Determine whether the database stores consumption as positive or negative.
+            db_consumption_is_positive = sensor.get_attribute(
+                "consumption_is_positive", False
+            )
+            if sign_convention == ScheduleSignConvention.CONSUMPTION_POSITIVE:
+                # Caller wants consumption positive. Invert if DB stores it as negative.
+                if not db_consumption_is_positive:
+                    sign = -1
+            elif sign_convention == ScheduleSignConvention.PRODUCTION_POSITIVE:
+                # Caller wants production positive. Invert if DB already stores consumption positive.
+                if db_consumption_is_positive:
+                    sign = -1
+
+        # Apply sign to get the values in the requested convention
         consumption_schedule = sign * simplify_index(power_values)["event_value"]
         if consumption_schedule.empty:
             # for not in-built schedulers, we are not sure if they would store time series in the db