rating set tiers and durations

[catkins-miso]

Maybe the right solution here is to think of the names, i.e., normal, emergency, load shed like we've been talking about for the facility names, but the duration is the really important thing. PJM has four tiers--two emergency ones, short- and long-term, and MISO uses only one of them since the other doesn't accommodate our emergency duration. The RC could validate that there's an acceptable rating for each of their tiers. This provides flexibility down the road if a given Ratings Provider operates with different tiers; our tariff requires they give us a normal/emergency/load shed, not that they don't have stuff in between.

[caindy]

@getorymckeag To make the suggestion above concrete. Here's a sketch of what an example might look like. It doesn't reuse the the current schemas properly, and there's just one proposal here as an example. I also ended up proposing something here for #9

{ "forecast-header": {
    "prevailing-emergency-durations": [
        { "name": "emergency", "minutes": 120},
        { "name": "load shed", "minutes": 15}
    ],
    "power-system-objects": [
      {
        "receiver-primary-identifier": "8badf00d",
        "alternate-identifiers": [
            {
                "name": "LLBEAN1",
                "authority": "TO1"
            },
            {
                "name": "LL BEAN 1 1",
                "authority": "MISO",
                "mrid": "8badf00d"
            }
        ]
      }
    ]
  }, //forecast-header
  "proposals": {
    "8badf00d": {
      "emergency-durations": [
          { "name": "emergency", "minutes": 240},
          { "name": "load shed", "minutes": 15}
      ],
      "periods": [
        {
          "begins": "2024-02-01T06:00-0800",
          "ends": "2024-02-01T07:00-0800",
          "continuous-operating-limit": { "mva": 150 },
          "emergency-operating-limits": {
            // this is a proper map whose allowed keys are
            // the name attributes in `emergency-durations`
            "emergency": { "mva": 150 },
            "load shed": { "mva": 110 }
          }
        },
        {
          "begins": "2024-02-01T07:00-0800",
          "ends": "2024-02-01T08:00-0800",
          "continuous-operating-limit": { "mva": 151 },
          "emergency-operating-limits": {
            "emergency": { "mva": 151 },
            "load shed": { "mva": 111 }
          }
        }
      ] // periods
    } // 8badf00d
  } // proposals
}

There are a few use cases around extensibility that I'm considering:

• An RC adds a new required duration: for example, an RC without both short- and long-term emergency makes that shift.
• Facilities with differing emergency durations: It's reasonable to allow for this
• Mapping RC to RC: Different RCs have different emergency tiers that define a duration. Each RC must select among those provided by their neighboring RC for the duration that best aligns with their need.
• system intact / continuous / normal: The need/presence of this value is invariant. It makes sense to pull it up and treat the other parts of the "rating set" as what they are--emergency ratings.
• runtime authorization: Even though we allow for flexibility in naming conventions, the receiver can grab the receiver-primary-identifier values from the power-system-object array to perform authorization without parsing the rest of the message. Depending on the situation, this could return a 422 and indicate the 8badf00d is unknown, returning the alternate names in the response. Typically, this would happen if new equipment was added, changed ownership, and/or an identifier was updated. Hopefully it is caught in a lower environment, but it should behave the same in prod.

[caindy]

Defining a schema for a Map is problematic. We could use additionalProperties but that has purported problems with generators and gives us Map<string, LimitValue> when we really want is closer to Map<EmergencyDuration, LimitValue>.

{ "forecast-header": {
    "default-emergency-durations": [
        { "name": "emergency", "minutes": 120},
        { "name": "load shed", "minutes": 15}
    ],
    "power-system-objects": [
      {
        "receiver-primary-identifier": "8badf00d",
        "alternate-identifiers": [
            {
                "name": "LLBEAN1",
                "authority": "TO1"
            },
            {
                "name": "LL BEAN 1 1",
                "authority": "MISO",
                "mrid": "8badf00d"
            }
        ]
      }
    ]
  }, //forecast-header
  "ratings": {
    "8badf00d": {
      "emergency-durations": [
          { "name": "emergency", "minutes": 240},
          { "name": "load shed", "minutes": 15}
      ],
      "periods": [
        {
          "begins": "2024-02-01T06:00-0800",
          "ends": "2024-02-01T07:00-0800",
          "continuous-operating-limit": { "mva": 100 },
          "emergency-operating-limits": [
            { "duration-name": "emergency", "limit":  { "mva": 110 } },
            { "duration-name": "load shed", "limit":  { "mva": 150 } }
         ]
        },
        {
          "begins": "2024-02-01T07:00-0800",
          "ends": "2024-02-01T08:00-0800",
          "continuous-operating-limit": { "mva": 101 },
          "emergency-operating-limits": [
            { "duration-name": "emergency", "limit":  { "mva": 111 } },
            { "duration-name": "load shed", "limit":  { "mva": 151 } }
         ]
        }
      ] // periods
    } // 8badf00d
  } // proposals
}

[catkins-miso]

This could have been closed by #46, yet I think we can clean-up the examples we have so far and make sure they reconcile with that design.