// 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;
}
