Add a message representing delivery-areas

This commit adds the following definition:
`DeliveryArea`: A delivery area is a geographical or administrative
region, usually defined and maintained by a Transmission System
Operator (TSO), where electricity deliveries for a contract occur.

Signed-off-by: Tiyash Basu <[email protected]>

Author: tiyash-basu-frequenz

RELEASE_NOTES.md

@@ -53,6 +53,8 @@
 - Added a message `ComponentConnection` to represent electrical connection
   between two components installed in a microgrid.
 
+- Added a message `DeliveryArea` to represent a market contract delivery area.
+
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->

proto/frequenz/api/common/v1/grid.proto

@@ -0,0 +1,62 @@
+// Frequenz definitions of grids as entites participating in trading.
+//
+// Copyright 2023 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.v1.grid;
+
+// CodeType specifies the type of identification code used for uniquely
+// identifying various entities such as delivery areas, market participants, and
+// grid components within the energy market. This enumeration aims to offer
+// compatibility across different jurisdictional standards.
+//
+// !!! note "Understanding Code Types"
+//     Different regions or countries may have their own standards for uniquely
+//     identifying various entities within the energy market. For example, in
+//     Europe, the Energy Identification Code (EIC) is commonly used for this
+//     purpose.
+//
+// !!! info "Extensibility"
+//     New code types can be added to this enum to accommodate additional
+//     regional standards, enhancing the API's adaptability.
+//
+// !!! caution "Validation Required"
+//     The chosen code type should correspond correctly with the `code` field in
+//     the relevant message objects, such as `DeliveryArea` or `Counterparty`.
+//     Failure to match the code type with the correct code could lead to
+//     processing errors.
+//
+enum EnergyMarketCodeType {
+  // Unspecified type. This value is a placeholder and should not be used.
+  ENERGY_MARKET_CODE_TYPE_UNSPECIFIED = 0;
+
+  // European Energy Identification Code Standard.
+  ENERGY_MARKET_CODE_TYPE_EUROPE_EIC = 1;
+
+  // North American Electric Reliability Corporation identifiers.
+  ENERGY_MARKET_CODE_TYPE_US_NERC = 2;
+}
+
+// DeliveryArea represents the geographical or administrative region, usually
+// defined and maintained by a Transmission System Operator (TSO), where
+// electricity deliveries for a contract occur.
+//
+// The concept is important to energy trading as it delineates the agreed-upon
+// delivery location. Delivery areas can have different codes based on the//
+// jurisdiction in which they operate.
+//
+// !!! note "Jurisdictional Differences"
+//     This is typically represented by specific codes according to local
+//     jurisdiction. In Europe, this is represented by an EIC
+//     (Energy Identification Code).
+message DeliveryArea {
+  // Code representing the unique identifier for the delivery area.
+  string code = 1;
+
+  // Type of code used for identifying the delivery area itself.
+  EnergyMarketCodeType code_type = 2;
+}

pytests/test_common.py

@@ -49,3 +49,16 @@ def test_module_import_metrics_electrical() -> None:
     from frequenz.api.common.v1.metrics import electrical_pb2_grpc
 
     assert electrical_pb2_grpc is not None
+
+
+def test_module_import_grid() -> None:
+    """Test that the modules can be imported."""
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1 import grid_pb2
+
+    assert grid_pb2 is not None
+
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1 import grid_pb2_grpc
+
+    assert grid_pb2_grpc is not None