Skip to content

Commit c62067f

Browse files
tiyash-basu-frequenztiyash-basu-frequenz
committed
Re-create the v1 package with the contents of the v0.6.x branch
This commit re-creates the `v1` package with the contents of the `v0.6.x` branch, which is the latest stable version of the API. The previous `v1` package has been renamed to `v1alpha7`. This means that any client or server code that was using the v0.6.x branch can now use the main branch without any changes, as the `v1` package now contains the same contents as the `v0.6.x` branch. Signed-off-by: Tiyash Basu <[email protected]>
1 parent f4a33e8 commit c62067f

File tree

27 files changed

+1849
-5
lines changed

27 files changed

+1849
-5
lines changed

‎RELEASE_NOTES.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@
7676

7777
- The type of the field `metrics.MetricSample.connection` has been changed from `string` to `metrics.MetricConnection`. The latter is a newly added message that provides a better categorization of the connection type.
7878

79-
- The `v1` package has been renamed to `v1alpha7`.
79+
- The `v1` package has been renamed to `v1alpha7`. The current `v1` package now consists of the contents the same directory from the v0.6.x branch, which is the latest stable version of the API.
8080

8181
## New Features
8282

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

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Frequenz definitions of grids as entites participating in trading.
2+
//
3+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
4+
//
5+
// Licensed under the MIT License (the "License");
6+
// you may not use this file except in compliance with the License.
7+
8+
syntax = "proto3";
9+
10+
package frequenz.api.common.v1.grid;
11+
12+
// CodeType specifies the type of identification code used for uniquely
13+
// identifying various entities such as delivery areas, market participants, and
14+
// grid components within the energy market. This enumeration aims to offer
15+
// compatibility across different jurisdictional standards.
16+
//
17+
// !!! note "Understanding Code Types"
18+
// Different regions or countries may have their own standards for uniquely
19+
// identifying various entities within the energy market. For example, in
20+
// Europe, the Energy Identification Code (EIC) is commonly used for this
21+
// purpose.
22+
//
23+
// !!! info "Extensibility"
24+
// New code types can be added to this enum to accommodate additional
25+
// regional standards, enhancing the API's adaptability.
26+
//
27+
// !!! caution "Validation Required"
28+
// The chosen code type should correspond correctly with the `code` field in
29+
// the relevant message objects, such as `DeliveryArea` or `Counterparty`.
30+
// Failure to match the code type with the correct code could lead to
31+
// processing errors.
32+
//
33+
enum EnergyMarketCodeType {
34+
// Unspecified type. This value is a placeholder and should not be used.
35+
ENERGY_MARKET_CODE_TYPE_UNSPECIFIED = 0;
36+
37+
// European Energy Identification Code Standard.
38+
ENERGY_MARKET_CODE_TYPE_EUROPE_EIC = 1;
39+
40+
// North American Electric Reliability Corporation identifiers.
41+
ENERGY_MARKET_CODE_TYPE_US_NERC = 2;
42+
}
43+
44+
// DeliveryArea represents the geographical or administrative region, usually
45+
// defined and maintained by a Transmission System Operator (TSO), where
46+
// electricity deliveries for a contract occur.
47+
//
48+
// The concept is important to energy trading as it delineates the agreed-upon
49+
// delivery location. Delivery areas can have different codes based on the//
50+
// jurisdiction in which they operate.
51+
//
52+
// !!! note "Jurisdictional Differences"
53+
// This is typically represented by specific codes according to local
54+
// jurisdiction. In Europe, this is represented by an EIC
55+
// (Energy Identification Code).
56+
message DeliveryArea {
57+
// Code representing the unique identifier for the delivery area.
58+
string code = 1;
59+
60+
// Type of code used for identifying the delivery area itself.
61+
EnergyMarketCodeType code_type = 2;
62+
}

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// Frequenz definitions of the time increment used for electricity
2+
// deliveries and trading.
3+
//
4+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
5+
//
6+
// Licensed under the MIT License (the "License");
7+
// you may not use this file except in compliance with the License.
8+
9+
syntax = "proto3";
10+
11+
package frequenz.api.common.v1.grid;
12+
13+
import "google/protobuf/timestamp.proto";
14+
15+
// DeliveryDuration represents the time increment, in minutes,
16+
// used for electricity deliveries and trading. These durations
17+
// serve as the basis for defining the delivery period in contracts,
18+
// and they dictate how energy is scheduled and delivered to meet
19+
// contractual obligations.
20+
//
21+
// !!! note "Compatibility Constraints"
22+
// Not all delivery durations are universally
23+
// compatible with all delivery areas or markets.
24+
//
25+
enum DeliveryDuration {
26+
// Default value, indicates that the duration is unspecified.
27+
DELIVERY_DURATION_UNSPECIFIED = 0;
28+
29+
// 5-minute duration
30+
DELIVERY_DURATION_5 = 1;
31+
32+
// 15-minute contract duration.
33+
DELIVERY_DURATION_15 = 2;
34+
35+
// 30-minute contract duration.
36+
DELIVERY_DURATION_30 = 3;
37+
38+
// 1-hour contract duration.
39+
DELIVERY_DURATION_60 = 4;
40+
}
41+
42+
// DeliveryPeriod represents the time period during which the contract
43+
// is delivered. It is defined by a start timestamp and a duration.
44+
message DeliveryPeriod {
45+
// Start UTC timestamp represents the beginning of the delivery period.
46+
// This timestamp is inclusive, meaning that the delivery period starts
47+
// from this point in time.
48+
//
49+
// !!! note
50+
// Delivery period start time constraints:
51+
// - 5-minute durations must start at times that are multiples of
52+
// 5 minutes past the hour.
53+
// - 15-minute durations must start at :00, :15, :30, or
54+
// :45 past the hour.
55+
// - 30-minute durations must start at :00 or :30 past the hour.
56+
// - 60-minute durations must start at :00 past the hour.
57+
google.protobuf.Timestamp start = 1;
58+
59+
// The length of the delivery period.
60+
DeliveryDuration duration = 2;
61+
}

‎proto/frequenz/api/common/v1/location.proto‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Geographical co-ordinates of a place.
2+
//
3+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
4+
//
5+
// Licensed under the MIT License (the "License");
6+
// you may not use this file except in compliance with the License.
7+
8+
syntax = "proto3";
9+
10+
package frequenz.api.common.v1;
11+
12+
// A pair of geographical co-ordinates, representing the location of a place.
13+
message Location {
14+
// Latitude ranges from -90 (South) to 90 (North)
15+
float latitude = 1;
16+
17+
// Longitude ranges from -180 (West) to 180 (East)
18+
float longitude = 2;
19+
20+
// Country ISO 3166-1 Alpha 2
21+
string country_code = 3;
22+
}

‎proto/frequenz/api/common/v1/market/energy.proto‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Frequenz definitions of energy.
2+
//
3+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
4+
//
5+
// Licensed under the MIT License (the "License");
6+
// you may not use this file except in compliance with the License.
7+
8+
syntax = "proto3";
9+
10+
package frequenz.api.common.v1.market;
11+
12+
import "frequenz/api/common/v1/types/decimal.proto";
13+
14+
// Represents a single unit of electricity.
15+
//
16+
// !!! note
17+
// The unit of energy is denominated in MWh, which is a unit of energy
18+
// representing total output over a period.(Megawatt-hours). This differs
19+
// from MW (Megawatts), a unit of power representing the rate of energy
20+
// production or consumption.
21+
message Energy {
22+
// Energy unit in Megawatthours (MWh).
23+
frequenz.api.common.v1.types.Decimal mwh = 1;
24+
}

‎proto/frequenz/api/common/v1/market/power.proto‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Frequenz definitions of power.
2+
//
3+
// Copyright 2024 Frequenz Energy-as-a-Service GmbH
4+
//
5+
// Licensed under the MIT License (the "License");
6+
// you may not use this file except in compliance with the License.
7+
8+
syntax = "proto3";
9+
10+
package frequenz.api.common.v1.market;
11+
12+
import "frequenz/api/common/v1/types/decimal.proto";
13+
14+
// Represents a single unit of power.
15+
//
16+
// !!! note
17+
// The power unit is denominated in MW (Megawatts), which is a unit of
18+
// power representing the rate of energy production or consumption at any
19+
// given moment. This differs from MWh (Megawatt-hours), which measures
20+
// the total amount of energy delivered or consumed over a period.
21+
//
22+
// Example:
23+
// A power plant running at 10 MW for 1 hour generates 10 MWh of energy.
24+
//
25+
// This message standardizes the representation of power in MW across all
26+
// market applications.
27+
message Power {
28+
// Power amount in Megawatts (MW).
29+
frequenz.api.common.v1.types.Decimal mw = 1;
30+
}

‎proto/frequenz/api/common/v1/market/price.proto‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
// Frequenz definitions of price for electricity trading.
2+
//
3+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
4+
//
5+
// Licensed under the MIT License (the "License");
6+
// you may not use this file except in compliance with the License.
7+
8+
syntax = "proto3";
9+
10+
package frequenz.api.common.v1.market;
11+
12+
import "frequenz/api/common/v1/types/decimal.proto";
13+
14+
// Represents a monetary price for electricity trading, including
15+
// the amount and currency. The currency used should align with the
16+
// delivery area's standard currency.
17+
//
18+
// !!! caution "Validation Required"
19+
// It's essential to ensure that the currency aligns with the
20+
// standard currency of the associated delivery area. Failure to
21+
// do so may result in the API service rejecting the request due to currency
22+
// mismatches.
23+
//
24+
// !!! info "Relation to Delivery Area"
25+
// The currency specified is intrinsically related to the delivery area
26+
// for the contract. Make sure the chosen currency is compatible with
27+
// the delivery area's currency standards.
28+
//
29+
message Price {
30+
// List of supported currencies.
31+
//
32+
// !!! info "Extensibility"
33+
// New currencies can be added to this enum to support additional markets.
34+
enum Currency {
35+
CURRENCY_UNSPECIFIED = 0;
36+
CURRENCY_USD = 1;
37+
CURRENCY_CAD = 2;
38+
CURRENCY_EUR = 3;
39+
CURRENCY_GBP = 4;
40+
CURRENCY_CHF = 5;
41+
CURRENCY_CNY = 6;
42+
CURRENCY_JPY = 7;
43+
CURRENCY_AUD = 8;
44+
CURRENCY_NZD = 9;
45+
CURRENCY_SGD = 10;
46+
}
47+
48+
// The amount of the price.
49+
frequenz.api.common.v1.types.Decimal amount = 1;
50+
51+
// The currency in which the price is denominated.
52+
Currency currency = 2;
53+
}

‎proto/frequenz/api/common/v1/metrics/bounds.proto‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Definitions for bounds.
2+
//
3+
// Copyright:
4+
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
5+
//
6+
// License:
7+
// MIT
8+
9+
syntax = "proto3";
10+
11+
package frequenz.api.common.v1.metrics;
12+
13+
// A set of lower and upper bounds for any metric.
14+
// The units of the bounds are always the same as the related metric.
15+
message Bounds {
16+
// The lower bound.
17+
// If absent, there is no lower bound.
18+
optional float lower = 1;
19+
20+
// The upper bound.
21+
// If absent, there is no upper bound.
22+
optional float upper = 2;
23+
}

0 commit comments

Comments
 (0)