frequenz-api-common 0.8.9__tar.gz → 0.8.11__tar.gz

{frequenz_api_common-0.8.9 → frequenz_api_common-0.8.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-api-common
-Version: 0.8.9
+Version: 0.8.11
 Summary: Frequenz common gRPC API and bindings
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License-Expression: MIT
@@ -19,16 +19,16 @@ Requires-Python: <4,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: protobuf<8,>=6.33.6
-Requires-Dist: grpcio<2,>=1.80.0
+Requires-Dist: grpcio<2,>=1.81.1
 Provides-Extra: dev-flake8
 Requires-Dist: flake8==7.3.0; extra == "dev-flake8"
 Requires-Dist: flake8-datetimez==20.10.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
 Requires-Dist: flake8-pyproject==1.2.4; extra == "dev-flake8"
-Requires-Dist: pydoclint==0.8.3; extra == "dev-flake8"
+Requires-Dist: pydoclint==0.9.0; extra == "dev-flake8"
 Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
 Provides-Extra: dev-formatting
-Requires-Dist: black==26.3.1; extra == "dev-formatting"
+Requires-Dist: black==26.5.1; extra == "dev-formatting"
 Requires-Dist: isort==8.0.1; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
 Requires-Dist: mike==1.1.2; extra == "dev-mkdocs"
@@ -36,20 +36,20 @@ Requires-Dist: mkdocs-gen-files==0.6.1; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-literate-nav==0.6.3; extra == "dev-mkdocs"
 Requires-Dist: mkdocs-material==9.7.6; extra == "dev-mkdocs"
 Requires-Dist: mkdocstrings[python]==1.0.4; extra == "dev-mkdocs"
-Requires-Dist: frequenz-repo-config[api]==0.17.0; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[api]==0.18.0; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
-Requires-Dist: mypy==1.20.2; extra == "dev-mypy"
+Requires-Dist: mypy==2.1.0; extra == "dev-mypy"
 Requires-Dist: grpc-stubs==1.53.0.6; extra == "dev-mypy"
 Requires-Dist: frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
 Requires-Dist: nox==2026.4.10; extra == "dev-noxfile"
-Requires-Dist: frequenz-repo-config[api]==0.17.0; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[api]==0.18.0; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
-Requires-Dist: pylint==4.0.5; extra == "dev-pylint"
+Requires-Dist: pylint==4.0.6; extra == "dev-pylint"
 Requires-Dist: frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
-Requires-Dist: pytest==9.0.3; extra == "dev-pytest"
-Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.17.0; extra == "dev-pytest"
+Requires-Dist: pytest==9.1.1; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.18.0; extra == "dev-pytest"
 Provides-Extra: dev
 Requires-Dist: frequenz-api-common[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
 Dynamic: license-file

frequenz_api_common-0.8.11/RELEASE_NOTES.md

@@ -0,0 +1,10 @@
+# Frequenz Common API Release Notes
+
+## Summary
+
+This release renames the `MarketLocation` message to `MarketLocationRef`.
+
+## Upgrading
+
+Replace uses of `frequenz.api.common.v1alpha8.grid.MarketLocation` with
+`frequenz.api.common.v1alpha8.grid.MarketLocationRef`.

{frequenz_api_common-0.8.9 → frequenz_api_common-0.8.11}/proto/frequenz/api/common/v1alpha7/streaming/event.proto

@@ -15,12 +15,12 @@ enum Event {
   // Default, unspecified event
   EVENT_UNSPECIFIED = 0;
 
-  // A new dispatch has been created
+  // A new resource has been created
   EVENT_CREATED = 1;
 
-  // An existing dispatch has been updated
+  // An existing resource has been updated
   EVENT_UPDATED = 2;
 
-  // An existing dispatch has been deleted
+  // An existing resource has been deleted
   EVENT_DELETED = 3;
 }

frequenz_api_common-0.8.11/proto/frequenz/api/common/v1alpha8/grid/flexibility_service.proto

@@ -0,0 +1,171 @@
+// Frequenz definitions for grid-facing flexibility services.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.grid;
+
+// Defines the type of flexibility service associated with a flexibility
+// resource.
+//
+// A flexibility resource can represent an individual asset, an asset group, a
+// microgrid, a Gridpool, or another market-specific aggregation that provides
+// or consumes flexibility.
+//
+// Each service type represents a flexibility service, often corresponding to
+// a market product or grid-operator requirement, with specific rules for
+// activation, delivery, telemetry, and control-signal handling.
+//
+// !!! note "Naming conventions"
+//     This enum uses region-neutral terminology and maps it to common
+//     flexibility-service names used by grid system operators and market
+//     operators in different regions.
+//
+// !!! note "Service behavior"
+//     This enum classifies the service type only. Service-specific behavior
+//     such as setpoint cadence, ramping windows, activation timing, telemetry
+//     requirements, and dispatch method is defined by the service or API that
+//     consumes this enum.
+//
+enum FlexServiceType {
+  // UNSPECIFIED: Default unspecified value — must not be used.
+  FLEX_SERVICE_TYPE_UNSPECIFIED = 0;
+
+  // PRIMARY: Primary Regulation
+  //
+  // Also known as:
+  // - Frequency Containment Reserve (FCR) [Europe]
+  // - Primary Frequency Response [US]
+  // - Dynamic Containment [UK]
+  //
+  // Provides autonomous frequency response within an assigned ΔP capacity band.
+  // Participating resources adjust active power locally and in real time based
+  // on measured frequency deviations.
+  //
+  // No centralized real-time dispatch signal is required for activation. The
+  // assigned capacity band may be determined by a bid, contract, schedule,
+  // or other service commitment.
+  //
+  // During the provision period, the assigned capacity responsibility may be
+  // updated, for example when availability changes or assets are deregistered.
+  FLEX_SERVICE_TYPE_PRIMARY = 1;
+
+  // SECONDARY_POS: Secondary Upward Regulation
+  //
+  // Also known as:
+  // - Automatic Frequency Restoration Reserve Up (aFRR+) [Europe]
+  // - Regulation Up [US, PJM]
+  // - Dynamic Regulation Up [UK]
+  //
+  // Supports the grid by increasing net export or reducing net import:
+  // - increasing generation or battery discharge,
+  // - decreasing consumption or battery charging.
+  //
+  // Secondary upward regulation is typically activated through recurring
+  // explicit control instructions or ΔP setpoints.
+  //
+  // Unlike primary regulation, activation is signal-based rather than purely
+  // autonomous. Participating resources are expected to follow received control
+  // instructions within the required ramping and delivery constraints.
+  FLEX_SERVICE_TYPE_SECONDARY_POS = 2;
+
+  // SECONDARY_NEG: Secondary Downward Regulation
+  //
+  // Also known as:
+  // - Automatic Frequency Restoration Reserve Down (aFRR-) [Europe]
+  // - Regulation Down / RegD Down [US, PJM]
+  // - Dynamic Regulation Down [UK]
+  //
+  // Supports the grid by reducing net export or increasing net import:
+  // - decreasing generation or battery discharge,
+  // - increasing consumption or battery charging.
+  //
+  // Secondary downward regulation is typically activated through recurring
+  // explicit control instructions or ΔP setpoints.
+  //
+  // Unlike primary regulation, activation is signal-based rather than purely
+  // autonomous. Participating resources are expected to follow received control
+  // instructions within the required ramping and delivery constraints.
+  FLEX_SERVICE_TYPE_SECONDARY_NEG = 3;
+
+  // MANUAL_POS: Manual Upward Reserve
+  //
+  // Also known as:
+  // - mFRR+ / Replacement Reserve Up [Europe]
+  // - Contingency Reserve Up [US]
+  //
+  // Supports the grid by increasing net export or reducing net import:
+  // - increasing generation or battery discharge,
+  // - decreasing consumption or battery charging.
+  //
+  // Manual upward reserve is typically activated through explicit control
+  // instructions or setpoints.
+  //
+  // Compared to secondary regulation, activation is usually less frequent and
+  // may follow manual, semi-automated, or event-driven operator processes.
+  FLEX_SERVICE_TYPE_MANUAL_POS = 4;
+
+  // MANUAL_NEG: Manual Downward Reserve
+  //
+  // Also known as:
+  // - mFRR– / Replacement Reserve Down [Europe]
+  // - Contingency Reserve Down [US]
+  //
+  // Supports the grid by reducing net export or increasing net import:
+  // - decreasing generation or battery discharge,
+  // - increasing consumption or battery charging.
+  //
+  // Manual downward reserve is typically activated through explicit control
+  // instructions or setpoints.
+  //
+  // Compared to secondary regulation, activation is usually less frequent and
+  // may follow manual, semi-automated, or event-driven operator processes.
+  FLEX_SERVICE_TYPE_MANUAL_NEG = 5;
+
+  // REPLACEMENT_RESERVE: Replacement Reserve
+  //
+  // Also known as:
+  // - Replacement Reserve (RR) [Europe]
+  // - Supplemental Reserve [US]
+  //
+  // Provides slower reserve capacity to restore operational balance or replace
+  // previously activated balancing capacity.
+  //
+  // Replacement reserve can support the grid in either direction, depending on
+  // the relevant market rules or grid-operator requirements:
+  // - upward reserve increases net export or reduces net import,
+  // - downward reserve reduces net export or increases net import.
+  //
+  // The activation process and control-instruction semantics are defined by the
+  // concrete service rules. Compared to primary and secondary regulation,
+  // activation is typically slower and less continuous.
+  FLEX_SERVICE_TYPE_REPLACEMENT_RESERVE = 6;
+
+  // DEMAND: Demand Response
+  //
+  // Also known as:
+  // - Emergency Demand Response
+  // - Interruptible Load
+  // - Flexible Load or Load Curtailment
+  //
+  // Provides load-side flexibility by changing consumption in response to
+  // market rules, grid-operator requirements, or a specific flexibility
+  // service.
+  //
+  // Demand response most commonly supports the grid by reducing net import:
+  // - decreasing consumption,
+  // - shifting consumption to another time period,
+  // - or temporarily interrupting flexible loads.
+  //
+  // Some demand-response products may also support increasing net import, for
+  // example to absorb excess generation or relieve local grid constraints.
+  //
+  // Activation is typically event-based or instruction-based rather than
+  // autonomous frequency response. Activation timing, duration, and control
+  // behavior are service-specific.
+  FLEX_SERVICE_TYPE_DEMAND = 7;
+}

{frequenz_api_common-0.8.9 → frequenz_api_common-0.8.11}/proto/frequenz/api/common/v1alpha8/grid/market_location.proto

@@ -142,7 +142,7 @@ message MarketLocationId {
 // - UK: MPAN
 // - Australia: NMI
 // - US: ESI-ID
-message MarketLocation {
+message MarketLocationRef {
   // Market area in which the Market Location is registered.
   frequenz.api.common.v1alpha8.market.MarketArea market_area = 1;
 

frequenz_api_common-0.8.11/proto/frequenz/api/common/v1alpha8/grid/provision_duration.proto

@@ -0,0 +1,102 @@
+// Frequenz definitions for provision durations and periods used by
+// grid-facing flexibility services.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.grid;
+
+import "google/protobuf/timestamp.proto";
+
+// Defines standard provision durations for flexibility services.
+//
+// A provision duration is the duration of a single provision period. In many
+// markets, this corresponds to the delivery block or service interval for which
+// a flexibility service is contracted, committed, or delivered.
+//
+// Provision durations are modeled as an enum because only a fixed set of
+// provision periods is supported by the relevant services, markets, and
+// operator integrations. This makes invalid durations unrepresentable and
+// keeps validation behavior consistent across APIs.
+//
+// !!! note "Duration vs. resolution"
+//     This field defines the duration of a single provision period. In market
+//     terms, this is often the delivery block or product block for the
+//     flexibility service. It does not define the cadence or resolution of
+//     telemetry samples, control instructions, or setpoint updates.
+//
+enum ProvisionDuration {
+  // UNSPECIFIED: Default value — must not be used in production messages.
+  PROVISION_DURATION_UNSPECIFIED = 0;
+
+  // 5_MIN: 5-minute delivery window (planned for future reconstruction of
+  // ancillary service markets).
+  PROVISION_DURATION_5_MIN = 1;
+
+  // 15_MIN: 15-minute delivery window (common in balancing energy markets
+  // and secondary regulation).
+  PROVISION_DURATION_15_MIN = 2;
+
+  // 30_MIN: 30-minute delivery block (used in some scheduling or redispatch
+  // services).
+  PROVISION_DURATION_30_MIN = 3;
+
+  // 60_MIN: Hourly provision period (e.g., for day-ahead markets or system
+  // dispatch).
+  PROVISION_DURATION_60_MIN = 4;
+
+  // 120_MIN: 2-hour blocks, less commonly used but possible in some markets.
+  PROVISION_DURATION_120_MIN = 5;
+
+  // 240_MIN: 4-hour block (e.g., German and EU primary regulation tenders).
+  PROVISION_DURATION_240_MIN = 6;
+
+  // 1440_MIN: Full-day delivery period (e.g., capacity or commitment-based
+  // products).
+  PROVISION_DURATION_1440_MIN = 7;
+}
+
+// Represents the time period during which the flexibility market contract is
+// delivered.
+//
+// This defines the contractual length of a provision period. Valid start
+// times are determined by the combination of duration, flexibility service,
+// delivery area, and market-specific rules
+//
+message ProvisionPeriod {
+  // Start UTC timestamp representing the beginning of the provision period.
+  //
+  // This timestamp is inclusive. The end of the provision period is derived
+  // from `start_time` and `duration`.
+  //
+  // !!! note "Start Time Constraints"
+  //     The start time must align with the provision duration and the market
+  //     rules for the selected `FlexServiceType` and delivery area.
+  //
+  //     Unless stricter market-specific rules apply, the following default
+  //     alignment is used:
+  //
+  //     - 15-minute durations must start at :00, :15, :30, or :45.
+  //     - 30-minute durations must start at :00 or :30.
+  //     - 60-minute durations must start at :00 past the hour.
+  //     - 120-minute durations must start on an even UTC hour
+  //       (00:00, 02:00, 04:00, ...).
+  //     - 240-minute durations must start on a UTC hour divisible by 4
+  //       (00:00, 04:00, 08:00, 12:00, ...).
+  //     - 1440-minute durations must start at the daily boundary defined by
+  //       the relevant market rules for the selected delivery area. If no
+  //       market-specific rule applies, this defaults to 00:00 UTC.
+  //
+  //     Market-specific rules may further restrict valid start times. For
+  //     example, a 4-hour product may only support predefined auction blocks,
+  //     and a full-day product may follow the delivery-day definition of the
+  //     relevant market.
+  google.protobuf.Timestamp start_time = 1;
+
+  // The length of the provision period.
+  ProvisionDuration duration = 2;
+}

frequenz_api_common-0.8.11/proto/frequenz/api/common/v1alpha8/gridpool/gridpool.proto

@@ -0,0 +1,103 @@
+// Frequenz gridpool definition.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.gridpool;
+
+// Gridpool contains details of a specific Gridpool.
+//
+// A Gridpool is a virtual balancing, trading, and operating pool. It combines
+// Gridpool members and other position contributions into a unified operational
+// and commercial position.
+//
+// A Gridpool is attached to a parent balancing group, market account, or
+// scheduling entity. Conceptually, it functions as a virtual sub-balancing
+// group: it aggregates measured, forecasted, scheduled, contractual, flexible,
+// and virtual effects into a position that can be forecasted, scheduled,
+// traded, balanced, reported, optimized, or used for flexibility services.
+//
+// A Gridpool does not necessarily have a standalone settlement identity with a
+// grid operator. Physical settlement and imbalance accounting may occur
+// through the parent balancing group, market account, or scheduling entity.
+//
+// Gridpool members are explicit assignments of entities or relationships to a
+// Gridpool. Members describe what belongs to the Gridpool structurally. They
+// may include:
+//
+//   • Market Locations: market-facing metering or settlement points
+//     representing consumption, generation, import, export, or other
+//     market-relevant energy flows.
+//   • Microgrids: single-site energy systems containing multiple assets, such
+//     as batteries, PV, generators, flexible loads, or other controllable
+//     components, typically operated through a local edge controller.
+//   • FlexClusters or distributed flexible asset groups: distributed pools of
+//     flexible assets, such as stand-alone batteries, home storage systems,
+//     PV-battery deployments, EV chargers, or other controllable assets.
+//
+// Gridpool contributions describe how members or other inputs affect the
+// Gridpool's operational, commercial, balance-relevant, or tradable position.
+// Contributions may include:
+//
+//   • measured consumption or generation from Market Locations,
+//   • flexibility availability from Microgrids or distributed flexible assets,
+//   • energy transfer schedules,
+//   • contractual positions,
+//   • and virtual contributions.
+//
+// A Gridpool member does not necessarily contribute to every service,
+// direction, or time period. For example, a Microgrid may provide
+// flexibility without having an export Market Location managed by Frequenz,
+// or a Market Location may contribute measured consumption without
+// providing controllable flexibility.
+//
+// Virtual contributions are synthetic or model-derived volumes used for
+// forecasting, strategy development, hedging, or virtual trading. They do not
+// correspond to physical assets, Microgrids, or Market Locations and are
+// independent of the physical flexibility range of the Gridpool. A Gridpool may
+// therefore have virtual contributions even if it has no physical contributors
+// for a specific service or time period.
+//
+// Gridpools bring physical, contractual, flexible, scheduled, and virtual
+// contributions together into a single position:
+//
+// ```text
+// Parent Balancing Group / Market Account / Scheduling Entity
+// └── Gridpool  (virtual sub-balancing group)
+//     ├── Gridpool members (Physical contributors)
+//     │     ├── Market Locations (metering or settlement points)
+//     │     ├── Microgrids (DER sites such as batteries, PV, generators,
+//     │     │   and flexible loads; typically controlled via edge controller)
+//     │     └── FlexClusters or distributed flexible asset groups
+//     ├── Scheduled and contractual contributions
+//     │     ├── Energy transfer schedules
+//     │     └── Contracted positions
+//     └── Virtual contributions
+//           └── Synthetic or model-derived volumes for forecasting,
+//               hedging, strategy development, or virtual trading
+// ```
+//
+// A Gridpool is not a physical site and does not imply a single delivery area.
+// Members and contributions of the same Gridpool may belong to different
+// delivery areas, bidding zones, regional markets, ISO/TSO regions, or nodes.
+//
+// The members and contributions of a Gridpool define its operational, physical,
+// flexible, and financial profile. A Gridpool's aggregated consumption,
+// production, schedules, forecasts, contracts, flexibility, and virtual
+// positions determine its balance-relevant and tradable position.
+//
+// Gridpool members, services, schedules, application variables, and
+// contributor-specific details are modeled as separate resources by APIs
+// that expose Gridpool topology and service configuration.
+//
+message Gridpool {
+  // Unique identifier of the Gridpool.
+  uint64 id = 1;
+
+  // Human-readable name of the Gridpool.
+  string name = 2;
+}

frequenz_api_common-0.8.11/proto/frequenz/api/common/v1alpha8/identity/resource_uri.proto

@@ -0,0 +1,167 @@
+// Domain Resource URI definitions used across Frequenz APIs.
+//
+// Resource URIs identify domain resources such as access owners, operators,
+// flexibility groups, control groups, or other resources that participate in
+// energy, flexibility, grid-operation, or market workflows.
+//
+// Copyright 2025 Frequenz Energy-as-a-Service GmbH
+//
+// Licensed under the MIT License (the "License");
+// you may not use this file except in compliance with the License.
+
+syntax = "proto3";
+
+package frequenz.api.common.v1alpha8.identity;
+
+// Classifies the type of resource identified by a `ResourceUri`.
+//
+// The URI scheme identifies the general namespace, while the `type` field
+// provides the domain-specific interpretation. For example, `group://...`
+// identifies a group resource; when used with `RESOURCE_URI_TYPE_FLEX_GROUP`,
+// that group is interpreted as a flexibility group.
+//
+// !!! note "URI scheme vs. resource type"
+//     URI schemes and resource types do not need to be one-to-one.
+//     For example:
+//     - A URI like `access-owner://frequenz` with
+//       `RESOURCE_URI_TYPE_ACCESS_OWNER` identifies a flexibility market
+//       access owner.
+//     - A URI like `operator://50hertz` with
+//       `RESOURCE_URI_TYPE_OPERATOR` identifies an operator or control-system
+//       authority.
+//     - A URI like `group://frequenz/secondary/fsp_q3` with
+//       `RESOURCE_URI_TYPE_FLEX_GROUP` identifies a flexibility group.
+//
+enum ResourceUriType {
+  // UNSPECIFIED: Default unspecified value — must not be used in production
+  // messages.
+  RESOURCE_URI_TYPE_UNSPECIFIED = 0;
+
+  // ACCESS_OWNER: Flexibility market access owner URI.
+  //
+  // Identifies the entity that holds or represents the market access rights
+  // under which flexibility services are offered, activated, or settled.
+  //
+  // An access owner may define or authorize flexibility groups and may
+  // represent microgrids, Gridpools, asset groups, or other flexibility
+  // resources toward market operators, grid operators, or flexibility
+  // platforms.
+  //
+  // Depending on the market model, this role may be referred to as a
+  // flexibility service provider, balancing service provider, aggregator, or
+  // virtual power plant operator. In this API, the generic term is access
+  // owner.
+  RESOURCE_URI_TYPE_ACCESS_OWNER = 1;
+
+  // OPERATOR: Operator URI.
+  //
+  // Identifies an entity or system authorized to operate, coordinate, validate,
+  // or issue control instructions for grid-facing or market-facing
+  // integrations.
+  //
+  // An operator may represent a grid operator, market operator, flexibility
+  // platform, gateway, or control-system authority. Unlike an access owner, an
+  // operator does not necessarily hold flexibility market access rights. It may
+  // instead act as the external or internal authority that exchanges setpoints,
+  // telemetry, status information, or validation signals with the platform.
+  //
+  // Typical examples include transmission system operators (TSOs),
+  // distribution system operators (DSOs), market operators, flexibility
+  // platforms, or gateway systems such as GridLink.
+  RESOURCE_URI_TYPE_OPERATOR = 2;
+
+  // FLEX_GROUP: Flexibility group URI.
+  //
+  // Identifies a logical group of microgrids or assets that can jointly
+  // participate in a flexibility service.
+  //
+  // !!! note "What is a flexibility group?"
+  //     A flexibility group represents a logical group of microgrids or assets
+  //     that can jointly participate in flexibility services.
+  //
+  //     Instruction delivery, telemetry interpretation, and delivery evaluation
+  //     are determined by the concrete participation context, such as the
+  //     flexibility group, service type, and provision period.
+  //
+  // !!! note "Terminology across markets"
+  //     Different markets use different terms for the concept of a
+  //     flexibility group:
+  //     - Europe: "Pool" or "Flexibility Service Provider Group"
+  //     - US: "Aggregated Resource", "DER Aggregation", "Composite Resource"
+  //     - UK: "Balancing Unit (BU)", "VLP Group", "Asset Group"
+  //
+  // !!! note "Examples for flexibility group usage"
+  //     - A group of microgrids committed together to provide FCR capacity in a
+  //       specific delivery area.
+  //     - A group of controllable batteries used to follow an aFRR activation
+  //       signal as one aggregated flexibility unit.
+  //     - A group of flexible loads participating in a demand-response product
+  //       for congestion relief.
+  RESOURCE_URI_TYPE_FLEX_GROUP = 3;
+
+  // GROUP: Generic group URI.
+  //
+  // Identifies a logical aggregation of assets, microgrids, controllable
+  // components, or other resources that are addressed as one unit.
+  //
+  // A group is intentionally context-neutral. It can be used whenever the API
+  // needs to refer to an aggregated resource scope without assigning a specific
+  // market, regulatory, or product meaning to that aggregation.
+  //
+  // !!! note "Generic group vs. flexibility group"
+  //     Use `RESOURCE_URI_TYPE_GROUP` when the group is merely the addressed
+  //     scope for telemetry, setpoints, control, routing, status reporting, or
+  //     another operational interaction.
+  //
+  //     Use `RESOURCE_URI_TYPE_FLEX_GROUP` when the group specifically
+  //     represents a flexibility-market or provision-registration concept, such
+  //     as a pool used for bid placement, reserve provisioning, activation, or
+  //     delivery validation.
+  //
+  // !!! note "Examples for generic group usage"
+  //     - A controllable asset group used by GridGuard, such as all batteries,
+  //       all PV inverters, or another DER subset in a microgrid.
+  //     - A GridLink routing scope used to exchange telemetry, setpoints,
+  //       communication status, or activation acknowledgements.
+  //     - A curtailment or grid-compliance group defined by an operator or
+  //       control-system integration.
+  RESOURCE_URI_TYPE_GROUP = 4;
+}
+
+// Represents a typed URI to identify a resource in the Frequenz ecosystem.
+//
+// !!! format "Structure"
+//     URIs must follow the format:
+//     ```
+//     <scheme>://<authority>/<path>...
+//     ```
+//
+//     Examples:
+//     - `access-owner://frequenz` → flexibility market access owner
+//     - `operator://50hertz` → operator or control-system authority
+//     - `group://frequenz/primary/pool-1` → flexibility group
+//
+// !!! example
+//     ```
+//     ResourceUri {
+//       uri: "group://frequenz/secondary/fsp_q3",
+//       type: RESOURCE_URI_TYPE_FLEX_GROUP
+//     }
+//     ```
+//
+message ResourceUri {
+  // Full URI string, including scheme, authority, and optional path.
+  string uri = 1;
+
+  // Expected domain-specific resource type for validation.
+  //
+  // The resource type is used to validate that `uri` identifies the expected
+  // kind of resource. For example, a value of `RESOURCE_URI_TYPE_FLEX_GROUP`
+  // requires a URI that identifies a flexibility group, such as one using the
+  // `group://` scheme according to the URI conventions of this API.
+  //
+  // This field is intentionally explicit instead of being inferred only from
+  // the URI string, so clients and servers can reject mismatches early and make
+  // the expected resource category clear in API messages.
+  ResourceUriType type = 2;
+}

{frequenz_api_common-0.8.9 → frequenz_api_common-0.8.11}/proto/frequenz/api/common/v1alpha8/streaming/event.proto

@@ -15,12 +15,12 @@ enum Event {
   // Default, unspecified event
   EVENT_UNSPECIFIED = 0;
 
-  // A new dispatch has been created
+  // A new resource has been created
   EVENT_CREATED = 1;
 
-  // An existing dispatch has been updated
+  // An existing resource has been updated
   EVENT_UPDATED = 2;
 
-  // An existing dispatch has been deleted
+  // An existing resource has been deleted
   EVENT_DELETED = 3;
 }

frequenz_api_common-0.8.11/py/frequenz/api/common/v1alpha8/identity/__init__.py

@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Grid bindings for Frequenz common gRPC API."""