openapi: 3.0.3 info: title: Transmission Ratings and Operating Limits Information Exchange (TROLIE) x-logo: altText: TROLIE logo url: images/TROLIE-horizontal-color.svg description: | This specification defines a set of operations for the exchange of power system ratings and limits between entities that own and operate the electric power system in North America. In particular, it is designed to support the exchange of Ambient Adjusted Ratings (AARs), pursuant to FERC Order 881. It is published as a community standard to facilitate interoperability in these exchanges. The specification conceives of the exchange as being between two primary entities: * A [Ratings Provider](https://trolie.energy/concepts#ratings-provider) is an entity that is responsible for providing ratings on some set of power system resources, e.g., Transmission Facilities, typically a Transmission Owner or Transmission Operator. The ratings are provided to a Clearinghouse Provider whose is responsible for determining the operating limits of the power system resources. * The [Clearinghouse Provider](https://trolie.energy/concepts#clearinghouse-provider) is typically a Transmission Provider (FERC) and a Reliability Coordinator (NERC). Adjacent Clearinghouse Providers exchange ratings in order to establish operating limit values for the power system resources that are shared between them. A Ratings Provider is assumed by this specification to have pre-coordinated with a Clearinghouse Provider to identify the former's Ratings Obligation, i.e., the set of power system resources for which they will provide ratings. Additionally, the Ratings Provider will have similarly pre-coordinated the definition of their Monitoring Sets, i.e., their power system limits of interest. The nature and method of pre-coordination is out-of-scope for this specification. Note that this API makes a strict distinction between the terms rating and limit. Colloquially, these terms are often used interchangeably. However, in the context of this specification, they have distinct meanings. At a high-level, the specification defines an exchange where ratings go in and limits come out. A Clearinghouse is a function for determining the operating limits from the ratings it has on-hand, including those that are proposed by Ratings Providers and any applicable time-bound static ratings. This interaction diagram highlights the primary requests and responses that are defined in this spec. Note that not all of the operations will be supported by every implementation. Primary Interactions with Ratings Provider version: 1.1.0 contact: name: TROLIE Maintainers email: maintainers@trolie.energy url: https://trolie.energy license: name: Community Specification License 1.0 url: https://spdx.org/licenses/Community-Spec-1.0.html servers: - url: https://trolie.example.com security: - oauth2-primary-flow: [] tags: - name: Real-Time description: | If permitted by the Clearinghouse Provider, its Ratings Providers can use these functions to exchange real-time ratings, supplementing or replacing traditional telemetry protocols like ICCP. These ratings are based on real-time measurements of ambient conditions and will be used by Transmission Providers for real-time grid operations processes, including state estimation and real-time markets. The clearing of real-time ratings may be more frequent than for forecast ratings, but the frequency is the prerogative of the Clearinghouse Provider. These ratings may be either AARs or DLRs. - name: Forecasting description: | The Forecasting API operations define the exchange of forecasted ratings, including the 240-hour-ahead forecasted AAR data exchange required by FERC Order 881. The operations support submitting rating proposals, querying in-use limits, and monitoring the health and validity of submissions against the Rating Provider's obligations. - name: Seasonal description: | Seasonal ratings are static ratings associated with extended durations, typically months. These are typically used in both planning and operations. Power system resources that are exempt from providing AARs generally operate at a seasonal rating. Even for resources using dynamic ratings, a seasonal rating is still necessary. This acts as a recourse when a dynamic rating is unavailable. For example, a dynamic rating might be unavailable during communication outages or for forecasts beyond the ten-day period required by FERC Order 881. - name: Seasonal Overrides description: | A Seasonal Override instructs the system to use a temporary static rating instead of any concurrent Seasonal Rating for a resource. A typical use case is a so-called 'de-rate' due to a temporary clearance issue for a transmission facility that is exempt from providing AARs. Exempt facilities typically operate at a seasonal rating. However, instead of updating the seasonal rating schedule, a Ratings Provider can send a Seasonal Override. During the override period, the Clearinghouse uses the Seasonal Override rating instead of any scheduled seasonal ratings. For resources required to provide AARs, a Ratings Provider would issue a Temporary AAR Exception to address temporary conditions requiring a static rating. - name: Temporary AAR Exceptions description: | A [Temporary AAR Exception](https://trolie.energy/concepts#temporary-aar-exception) is provided by the Ratings Provider when a Ratings Obligation cannot be fulfilled, due to some temporary operating condition impacting the related power system resource. This could occur in various scenarios: * An equipment failure. * An unforeseen condition on a related part of the power grid. * Some ambient condition that is not part of the model is heating the line, like a wildfire. * Something in the surrounding environment is affecting the amount that a line is allowed to sag. For example, this may occur for lines over rivers when very large ships pass under them A Temporary AAR Exception serves two main purposes: documenting the reason for the exception and providing a temporary rating value set. It is employed in three distinct circumstances: 1. Firstly, Order 881 mandates documentation and archival of all use of alternate ratings in lieu of AARs. Ratings Providers should continue to provide real-time and forecast ratings for the affected resource, but these should match the rating provided with the Temporary AAR Exception while the latter is in effect. This temporary rating, and the reason that it occurred, must be captured in history regardless of the provided ratings. The reason and the end date of the effective window may be updated after the object has been created, up to a configurable threshold. If the Ratings Providers provides ratings that deviate from the static Temporary AAR Exception rating, the Clearinghouse Provider must decide whether to use those or the static rating. The Clearinghouse Provider advise its Ratings Providers on how it will choose ahead of time. This specification recommends using the dynamic rating provided, but it does not mandate it. 2. Secondly, Temporary AAR Exceptions apply when the Clearinghouse Provider is generating forecast rating proposals on behalf of the Ratings Provider, e.g., when lookup tables are provided ahead of time by the Ratings Provider. Since there is no external ratings, the Clearinghouse Provider wouldn't otherwise know that a temporary static rating is needed. 3. Finally, for facilities where dynamic ratings are provided, it is possible that a communications outage or other issue could prevent the Clearinghouse Provider from receiving the dynamic ratings. In this case, the Clearinghouse Provider would use a Temporary AAR Exception rating. - name: Monitoring Sets description: | [Monitoring Sets](https://trolie.energy/concepts#monitoring-sets) are named sets of power system resources that may be used to filter ratings and limits returned by queries against these APIs. How Monitoring Sets are defined is beyond the scope of the TROLIE specification, and it is assumed that the sender and receiver have predefined the appropriate Monitoring Sets. - name: limit-type description: x-displayName: Limit Type paths: /limits/forecast-snapshot: get: operationId: getLimitsForecastSnapshot summary: Limits Forecast Snapshot tags: - Forecasting parameters: - $ref: '#/components/parameters/offset-period-start' - $ref: '#/components/parameters/period-end' - $ref: '#/components/parameters/query-filter' - $ref: '#/components/parameters/resource-id-filter' - $ref: '#/components/parameters/static-only' - $ref: '#/components/parameters/temporal-resolution' description: | Returns the latest Limits Forecast the clearinghouse has produced. This content of the response varies significantly based on the media type requested. * `application/vnd.trolie.forecast-limits-snapshot.v1+json` simply includes the limits. * For use cases that require understanding *how* the limits were determined, the media type `application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json` is available; it contains the ratings proposals and other factors used to generate the limits. Both of these media types support the `include-psr-header` parameter. This is a boolean parameter that defaults to `true`. When set to `false`, the `power-system-resource` header is omitted. This can result in smaller payloads when the client already knows the resource ids in use by the Clearinghouse Provider. ```http GET /limits/forecast-snapshot HTTP/1.1 Accept: application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json; include-psr-header=false ``` ### Slim Format The `application/vnd.trolie.forecast-limits-snapshot-slim.v1+json` media type may be used to request a more concise representation of the data. The media type parameter `limit-type` is required to specify the type of limit being requested, for example: ```http GET /limits/forecast-snapshot HTTP/1.1 Accept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power ``` Additionally, the `inputs-used` parameter may be set to `true` to include the inputs used to generate the forecast. ```http GET /limits/forecast-snapshot HTTP/1.1 Accept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true ``` Note this format is much more concise but requires significant care in processing. See [Using Slim Media Types](../example-narratives/using-slim-media-types) for more details. Clients SHOULD perform Conditional `GET` using the `If-None-Match` header and the `ETag` of a previous `GET` response to poll this endpoint. Rate limiting is done on a per Ratings Provider basis, so requests from independent clients used by the same provider count against the same quota. responses: '200': description: The requested operating forecast snapshot is returned. content: application/vnd.trolie.forecast-limits-snapshot.v1+json: schema: $ref: '#/components/schemas/forecast-limits-snapshot' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mw: 160 pf: 1 emergency-operating-limits: - duration-name: LTE limit: mw: 170 pf: 1 - duration-name: STE limit: mw: 180 pf: 1 - duration-name: DAL limit: mw: 190 pf: 1 application/vnd.trolie.forecast-limits-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/forecast-limits-snapshot-elide-psr' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mw: 160 pf: 1 emergency-operating-limits: - duration-name: LTE limit: mw: 170 pf: 1 - duration-name: STE limit: mw: 180 pf: 1 - duration-name: DAL limit: mw: 190 pf: 1 application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/forecast-limits-snapshot-slim' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' ends: '2023-07-12T18:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - - 160 - 1 - 170 - 1 - 180 - 1 - 190 - 1 - - 161 - 1 - 171 - 1 - 181 - 1 - 191 - 1 - - - 140 - 1 - 150 - 1 - 160 - 1 - 170 - 1 - - 141 - 1 - 151 - 1 - 161 - 1 - 171 - 1 application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true: schema: $ref: '#/components/schemas/forecast-limits-snapshot-slim-inputs-used' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' ends: '2023-07-12T18:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - - 160 - 1 - 170 - 1 - 180 - 1 - 190 - 1 - - 161 - 1 - 171 - 1 - 181 - 1 - 191 - 1 - - - 140 - 1 - 150 - 1 - 160 - 1 - 170 - 1 - - 141 - 1 - 151 - 1 - 161 - 1 - 171 - 1 inputs-used: - name: dry bulb temperature (Fahrenheit) unit: degF values: - - 50 - 51 - 52 - 53 - - 46.1 - 46.5 - 47.1 - 48 application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json: schema: $ref: '#/components/schemas/forecast-limits-detailed-snapshot' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL-RC last-updated: '2024-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: X-AMPL-RC mrid: 8badf00d limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2023-07-12T16:00:00-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 160 - duration-name: STE limit: mva: 165 - duration-name: DAL limit: mva: 170 inputs-used: - name: wind-speed unit: mph value: 5.2 - name: wind-direction unit: degrees value: 277.5 - name: temperature unit: F value: 72.1 temporary-aar-exceptions: - id: https://trolie.example.com/temporary-aar-exceptions/1234 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/forecast-limits-detailed-snapshot-elide-psr' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL-RC last-updated: '2024-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2023-07-12T16:00:00-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 160 - duration-name: STE limit: mva: 165 - duration-name: DAL limit: mva: 170 temporary-aar-exceptions: - id: https://trolie.example.com/temporary-aar-exceptions/1234 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406' '422': description: Unprocessable Content. The requested `temporal_resolution` is not supported. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/problem+json: schema: type: object allOf: - properties: supported-values: type: array maxItems: 100 items: $ref: '#/components/schemas/schema' - $ref: '#/components/schemas/problem' required: - supported-values example: type: //trolie.example.com/spec/client-errors/422/unsupported-temporal-resolution title: Unsupported Temporal Resolution status: 422 detail: The requested `temporal-resolution` 'PT1M' is not supported. Please choose from the list of supported values. instance: /forecast?temporal-resolution=PT1M supported-values: - PT1H - P1D - P1W - P1M '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:operating-snapshot /limits/forecast-snapshot/{period}: get: operationId: getHistoricalLimitsForecastSnapshot summary: Historical Limits Forecast Snapshot tags: - Forecasting parameters: - $ref: '#/components/parameters/offset-period-start' - $ref: '#/components/parameters/period-end' - $ref: '#/components/parameters/query-filter' - $ref: '#/components/parameters/resource-id-filter' - $ref: '#/components/parameters/static-only' - $ref: '#/components/parameters/temporal-resolution' - name: period description: | Returns the Forecast Limits snapshot for the period requested rather than the current snapshot. in: path required: true schema: $ref: '#/components/schemas/period-start' description: | Obtain the Limits Forecast the Transmission Provider used or is currently using in Operations as of the period requested. See the [Limits Forecast Snapshot](#tag/Forecasting/operation/getLimitsForecastSnapshot) operation for more information. responses: '200': description: The requested operating forecast snapshot is returned. content: application/vnd.trolie.forecast-limits-snapshot.v1+json: schema: $ref: '#/components/schemas/forecast-limits-snapshot' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mw: 160 pf: 1 emergency-operating-limits: - duration-name: LTE limit: mw: 170 pf: 1 - duration-name: STE limit: mw: 180 pf: 1 - duration-name: DAL limit: mw: 190 pf: 1 application/vnd.trolie.forecast-limits-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/forecast-limits-snapshot-elide-psr' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mw: 160 pf: 1 emergency-operating-limits: - duration-name: LTE limit: mw: 170 pf: 1 - duration-name: STE limit: mw: 180 pf: 1 - duration-name: DAL limit: mw: 190 pf: 1 application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/forecast-limits-snapshot-slim' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' ends: '2023-07-12T18:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - - 160 - 1 - 170 - 1 - 180 - 1 - 190 - 1 - - 161 - 1 - 171 - 1 - 181 - 1 - 191 - 1 - - - 140 - 1 - 150 - 1 - 160 - 1 - 170 - 1 - - 141 - 1 - 151 - 1 - 161 - 1 - 171 - 1 application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true: schema: $ref: '#/components/schemas/forecast-limits-snapshot-slim-inputs-used' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' ends: '2023-07-12T18:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - - 160 - 1 - 170 - 1 - 180 - 1 - 190 - 1 - - 161 - 1 - 171 - 1 - 181 - 1 - 191 - 1 - - - 140 - 1 - 150 - 1 - 160 - 1 - 170 - 1 - - 141 - 1 - 151 - 1 - 161 - 1 - 171 - 1 inputs-used: - name: dry bulb temperature (Fahrenheit) unit: degF values: - - 50 - 51 - 52 - 53 - - 46.1 - 46.5 - 47.1 - 48 application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json: schema: $ref: '#/components/schemas/forecast-limits-detailed-snapshot' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL-RC last-updated: '2024-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: X-AMPL-RC mrid: 8badf00d limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2023-07-12T16:00:00-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 160 - duration-name: STE limit: mva: 165 - duration-name: DAL limit: mva: 170 inputs-used: - name: wind-speed unit: mph value: 5.2 - name: wind-direction unit: degrees value: 277.5 - name: temperature unit: F value: 72.1 temporary-aar-exceptions: - id: https://trolie.example.com/temporary-aar-exceptions/1234 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/forecast-limits-detailed-snapshot-elide-psr' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL-RC last-updated: '2024-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2023-07-12T16:00:00-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 160 - duration-name: STE limit: mva: 165 - duration-name: DAL limit: mva: 170 temporary-aar-exceptions: - id: https://trolie.example.com/temporary-aar-exceptions/1234 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406' '410': $ref: '#/components/responses/410-problem' '422': description: Unprocessable Content. The requested `temporal_resolution` is not supported. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/problem+json: schema: type: object allOf: - properties: supported-values: type: array maxItems: 100 items: $ref: '#/components/schemas/schema' - $ref: '#/components/schemas/problem' required: - supported-values example: type: //trolie.example.com/spec/client-errors/422/unsupported-temporal-resolution title: Unsupported Temporal Resolution status: 422 detail: The requested `temporal-resolution` 'PT1M' is not supported. Please choose from the list of supported values. instance: /forecast?temporal-resolution=PT1M supported-values: - PT1H - P1D - P1W - P1M '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:operating-snapshot /limits/regional/forecast-snapshot: get: operationId: getRegionalLimitsForecastSnapshot summary: Regional Limits Forecast Snapshot tags: - Forecasting parameters: - $ref: '#/components/parameters/offset-period-start' - $ref: '#/components/parameters/period-end' - $ref: '#/components/parameters/query-filter' - $ref: '#/components/parameters/resource-id-filter' - $ref: '#/components/parameters/static-only' - $ref: '#/components/parameters/temporal-resolution' description: | Similar to [getLimitsForecastSnapshot](#tag/Forecasting/operation/getLimitsForecastSnapshot), except that it specifically returns only the latest **regionally** limiting ratings ([RLRs](https://trolie.energy/concepts#regionally-limiting-rating)) used by the Transmission Provider. This is explicitly designed to be used when reconciling forecasts between Transmission Providers in order to generate globally limiting ratings ([GLRs](https://trolie.energy/concepts#globally-limiting-rating)) for general use. See the article on [RC-to-RC Reconciliation](https://trolie.energy/articles/RC-to-RC-reconciliation.html) for more details. Outside of this use case, most users should use [getLimitsForecastSnapshot](#tag/Forecasting/operation/getLimitsForecastSnapshot) to get globally limiting ratings. Clients SHOULD perform Conditional `GET` using the `If-None-Match` header and the `ETag` of a previous `GET` response to poll this endpoint. Rate limiting is done on a per Ratings Provider basis, so requests from independent clients used by the same provider count against the same quota. responses: '200': description: The requested operating forecast snapshot is returned. content: application/vnd.trolie.forecast-limits-snapshot.v1+json: schema: $ref: '#/components/schemas/forecast-limits-snapshot' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mw: 160 pf: 1 emergency-operating-limits: - duration-name: LTE limit: mw: 170 pf: 1 - duration-name: STE limit: mw: 180 pf: 1 - duration-name: DAL limit: mw: 190 pf: 1 application/vnd.trolie.forecast-limits-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/forecast-limits-snapshot-elide-psr' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mw: 160 pf: 1 emergency-operating-limits: - duration-name: LTE limit: mw: 170 pf: 1 - duration-name: STE limit: mw: 180 pf: 1 - duration-name: DAL limit: mw: 190 pf: 1 application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/forecast-limits-snapshot-slim' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' ends: '2023-07-12T18:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - - 160 - 1 - 170 - 1 - 180 - 1 - 190 - 1 - - 161 - 1 - 171 - 1 - 181 - 1 - 191 - 1 - - - 140 - 1 - 150 - 1 - 160 - 1 - 170 - 1 - - 141 - 1 - 151 - 1 - 161 - 1 - 171 - 1 application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true: schema: $ref: '#/components/schemas/forecast-limits-snapshot-slim-inputs-used' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' ends: '2023-07-12T18:00:00-07:00' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - - 160 - 1 - 170 - 1 - 180 - 1 - 190 - 1 - - 161 - 1 - 171 - 1 - 181 - 1 - 191 - 1 - - - 140 - 1 - 150 - 1 - 160 - 1 - 170 - 1 - - 141 - 1 - 151 - 1 - 161 - 1 - 171 - 1 inputs-used: - name: dry bulb temperature (Fahrenheit) unit: degF values: - - 50 - 51 - 52 - 53 - - 46.1 - 46.5 - 47.1 - 48 application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json: schema: $ref: '#/components/schemas/forecast-limits-detailed-snapshot' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL-RC last-updated: '2024-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: X-AMPL-RC mrid: 8badf00d limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2023-07-12T16:00:00-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 160 - duration-name: STE limit: mva: 165 - duration-name: DAL limit: mva: 170 inputs-used: - name: wind-speed unit: mph value: 5.2 - name: wind-direction unit: degrees value: 277.5 - name: temperature unit: F value: 72.1 temporary-aar-exceptions: - id: https://trolie.example.com/temporary-aar-exceptions/1234 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/forecast-limits-detailed-snapshot-elide-psr' example: snapshot-header: begins: '2023-07-12T16:00:00-07:00' source: provider: X-AMPL-RC last-updated: '2024-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 limits: - resource-id: 8badf00d periods: - period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2023-07-12T16:00:00-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id period-start: '2023-07-12T16:00:00-07:00' period-end: '2023-07-12T17:00:00-07:00' continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 160 - duration-name: STE limit: mva: 165 - duration-name: DAL limit: mva: 170 temporary-aar-exceptions: - id: https://trolie.example.com/temporary-aar-exceptions/1234 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406' '422': description: Unprocessable Content. The requested `temporal_resolution` is not supported. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/problem+json: schema: type: object allOf: - properties: supported-values: type: array maxItems: 100 items: $ref: '#/components/schemas/schema' - $ref: '#/components/schemas/problem' required: - supported-values example: type: //trolie.example.com/spec/client-errors/422/unsupported-temporal-resolution title: Unsupported Temporal Resolution status: 422 detail: The requested `temporal-resolution` 'PT1M' is not supported. Please choose from the list of supported values. instance: /forecast?temporal-resolution=PT1M supported-values: - PT1H - P1D - P1W - P1M '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:regional-operating-snapshot post: operationId: postRegionalLimitsForecastSnapshot summary: Update Regional Limits Forecast Snapshot tags: - Forecasting parameters: [] description: | Update the Regional Limits Forecast with a Regional Limits Forecast Snapshot from an adjacent Transmission Provider (Reliability Coordinator) that does not conform to the TROLIE peering profile as described in [RC-to-RC Reconciliation](https://trolie.energy/articles/RC-to-RC-reconciliation.html). responses: '202': description: | The update was accepted for later processing. Updates to ratings may need to undergo additional validation and propagation to other systems. content: application/vnd.trolie.rating-forecast-proposal-status.v1+json: schema: $ref: '#/components/schemas/forecast-proposal-status' example: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' incomplete-obligation-count: 1 incomplete-obligations: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d invalid-proposal-count: 1 proposal-validation-errors: - message: The `resource-forecast-proposal` for `8badf00d` is incomplete. resource-id: 8badf00d headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '406': $ref: '#/components/responses/406-problem' '409': description: Conflict with Forecast Window content: application/problem+json: schema: $ref: '#/components/schemas/problem' example: type: //trolie.example.com/spec/client-errors/409/forecast-Window-closed title: 'Conflict: Forecast Window Closed' status: 409 detail: The proposed forecast was late. The first hour of the forecast was 2025-05-07T12:00:00-0500, and it was received at 2025-05-07T11:23:45-0500, but the Forecast Window closed at 2025-05-07T11:00:00-0500. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': description: Unprocessable Content content: application/problem+json: schema: $ref: '#/components/schemas/problem' example: type: //trolie.example.com/spec/client-errors/422/invalid-units title: 'Unprocessable Entity: Invalid Units' status: 422 detail: The proposal for 8badf00d at 2025-05-07T12:00:00Z specified `mw` so Active Power is assumed, but this exchange requires the power factor `pf` be specified as well. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:regional-operating-snapshot requestBody: $ref: '#/components/requestBodies/requestBody' /rating-proposals/realtime: get: operationId: getRealTimeProposalStatus summary: Real-Time Proposals Status description: | Retrieves the status of a real-time ratings proposal. The response is limited to the requestor's current proposal. Note this status resource is also returned for each `postRealTimeProposal` call. The anticipated use case for this endpoint is to monitoring proposal submissions: Clients can use this operation to independently verify that their proposal submission process is functioning correctly. This is particularly useful for scenarios where a separate monitoring job is set up to check the status of proposals. Rate limiting is applied per Ratings Provider, meaning requests from multiple clients associated with the same provider count towards the same quota. To optimize network traffic and server load, clients should perform conditional GET requests with the `If-None-Match` header and the `ETag` from a previous response. tags: - Real-Time responses: '200': description: OK content: application/vnd.trolie.rating-realtime-proposal-status.v1+json: schema: $ref: '#/components/schemas/real-time-proposal-status' example: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 incomplete-obligation-count: 1 incomplete-obligations: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d invalid-proposal-count: 1 proposal-validation-errors: - message: Submitted continuous rating value of 2000MVA is greater than the upper reasonability limit of 1300MVA resource-id: 8badf00d headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '406': $ref: '#/components/responses/406-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:realtime-proposals post: operationId: postRealTimeProposal summary: Submit Real-Time Rating Proposal description: | Some Clearinghouse Providers will support real-time ratings submissions through this operation. The API mechanics are different than forecasts, as there is no implicitly created time window to modify. Ratings providers simply `POST` new values as they are measured and/or computed. Rules for usage however are similar to forecasts; real-time proposals do not have to contain every resource for which the Ratings Provider is responsible. Data may be broken into batches across the Rating Provider's footprint. Status of the real-time proposals also includes an indication of incomplete obligations, much like forecast. However, the meaning of this is somewhat different, as it simply indicates data that is either completely missing, or is considered stale by the Clearinghouse Provider, likely due to simply not receiving a value within a reasonable period, such as an hour. There are two supported media types for Real-Time Ratings proposals. * `application/vnd.trolie.rating-realtime-proposal.v1+json` allows the Ratings Provider to combine different limit types, such as `apparent-power` (MVA) and `current` (MW), in a single proposal. * `application/vnd.trolie.rating-realtime-proposal-slim.v1+json` for proposals that only require a single limit type, e.g., `apparent-power`. Clients *MUST* specify that [limit-type](#tag/limit-type) as a media type parameter. For example, ```http POST /ratings-proposals/realtime HTTP/1.1 Content-Type: application/vnd.trolie.rating-realtime-proposal-slim.v1+json; limit-type=apparent-power ``` Note that this format is much more concise but requires significant care in serialization/deserialization. For details, see [Using Slim Media Types](../example-narratives/using-slim-media-types). tags: - Real-Time requestBody: required: true content: application/vnd.trolie.rating-realtime-proposal.v1+json: schema: $ref: '#/components/schemas/realtime-proposal' example: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d ratings: - resource-id: 8badf00d continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 170 application/vnd.trolie.rating-realtime-proposal-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/realtime-proposal-slim' examples: No Inputs Provided: summary: No Inputs Provided in the Real-Time Proposal value: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d ratings: - - 160 - 170 - - 155 - 160 responses: '202': description: | Accepted. The update was accepted for later processing by the Clearinghouse. Updates to ratings may need to undergo additional validation and propagation to other systems. Be sure to check the `incomplete-obligation-count` value is zero; if it is non-zero, the Clearinghouse Provider does not have a valid and non-stale real-time rating for one or more Ratings Obligations. Providers should impute recourse ratings as necessary to ensure their proposals are complete, i.e., the entire Ratings Obligation is met. content: application/vnd.trolie.rating-realtime-proposal-status.v1+json: schema: $ref: '#/components/schemas/real-time-proposal-status' example: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 incomplete-obligation-count: 1 incomplete-obligations: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d invalid-proposal-count: 1 proposal-validation-errors: - message: Submitted continuous rating value of 2000MVA is greater than the upper reasonability limit of 1300MVA resource-id: 8badf00d headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '406': $ref: '#/components/responses/406-problem' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': description: | Unprocessable Content. The Real-Time Ratings Proposal may not utilize units that are not permitted by the Clearinghouse Provider. Check the response for details. content: application/problem+json: schema: $ref: '#/components/schemas/problem' examples: invalid-units: summary: Invalid Units Provided in Real-Time Proposal value: type: //trolie.example.com/spec/client-errors/422/invalid-units title: 'Unprocessable Entity: Invalid Units' status: 422 detail: The proposal for 8badf00d at 2025-05-07T12:00:00Z specified `mw` so Active Power is assumed, but this exchange requires the power factor `pf` be specified as well. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:realtime-proposals /limits/realtime-snapshot: get: operationId: getRealTimeLimits description: | Obtain the System Operating Limits in-use by the Transmission Provider. Clients SHOULD perform Conditional `GET` using the `If-None-Match` header and the `ETag` of a previous `GET` response to poll this endpoint. Rate limiting is done on a per Ratings Provider basis, so requests from independent clients used by the same provider count against the same quota. summary: Limits Real Time Snapshot tags: - Real-Time parameters: - $ref: '#/components/parameters/query-filter' - $ref: '#/components/parameters/resource-id-filter' responses: '200': description: The System Operating Limits snapshot is returned. content: application/vnd.trolie.realtime-limits-snapshot.v1+json: schema: $ref: '#/components/schemas/realtime-limits-snapshot' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d limits: - resource-id: 8badf00d continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 application/vnd.trolie.realtime-limits-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/realtime-limits-snapshot-elide-psr' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 limits: - resource-id: 8badf00d continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json: schema: $ref: '#/components/schemas/realtime-limits-detailed-snapshot' example: snapshot-header: source: provider: X-AMPL-RC last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 5 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d limits: - resource-id: 8badf00d additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 175 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2025-07-12T14:10:12-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 - resource-id: 8badf00d-UTILITY-B-SEG-id source: last-updated: '2025-07-12T14:10:12-07:00' provider: UTILITY-B origin-id: 8badf00d-UTILITY-B-correlation-id continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 166 - duration-name: STE limit: mva: 171 - duration-name: DAL limit: mva: 175 temporary-aar-exceptions: - id: 284928-2025-07-12T16:00:00-07:00 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/realtime-limits-detailed-snapshot-elide-psr' example: snapshot-header: source: provider: X-AMPL-RC last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 5 limits: - resource-id: 8badf00d additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 175 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2025-07-12T14:10:12-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 - resource-id: 8badf00d-UTILITY-B-SEG-id source: last-updated: '2025-07-12T14:10:12-07:00' provider: UTILITY-B origin-id: 8badf00d-UTILITY-B-correlation-id continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 166 - duration-name: STE limit: mva: 171 - duration-name: DAL limit: mva: 175 temporary-aar-exceptions: - id: 284928-2025-07-12T16:00:00-07:00 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' application/vnd.trolie.realtime-limits-snapshot-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/realtime-limits-snapshot-slim' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - 160 - 170 - - 155 - 160 application/vnd.trolie.realtime-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true: schema: $ref: '#/components/schemas/realtime-limits-snapshot-slim-inputs-used' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - 160 - 170 - - 155 - 160 inputs-used: - name: dry bulb temperature (Fahrenheit) unit: degF values: - 50 - 51 headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' description: Not Acceptable (Content negotiation failed) content: application/problem+json: schema: $ref: '#/components/schemas/problem' examples: Compression Required: summary: Only compressed responses are supported value: type: //trolie.example.com/spec/client-errors/406/compression-required title: 'Not Acceptable: Accept-Encoding Required' status: 406 detail: 'This resource must be compressed with one of the following algorithms: gzip, deflate, br.' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:operating-snapshot /limits/regional/realtime-snapshot: get: operationId: getRegionalRealTimeLimits description: | Similar to [getRealTimeLimits](#tag/Real-Time/operation/getRealTimeLimits), except that it specifically returns only the latest **regionally** limiting ratings ([RLRs](https://trolie.energy/concepts#regionally-limiting-rating)) used by the Transmission Provider. This is explicitly designed to be used when reconciling real-time ratings between Transmission Providers in order to generate globally limiting ratings ([GLRs](https://trolie.energy/concepts#globally-limiting-rating)) for general use. See the article on [RC-to-RC Reconciliation](https://trolie.energy/articles/RC-to-RC-reconciliation.html) for more details. Outside of this use case, most users should use [getRealTimeLimits](#tag/Real-Time/operation/getRealTimeLimits) to get globally limiting ratings. Clients SHOULD perform Conditional `GET` using the `If-None-Match` header and the `ETag` of a previous `GET` response to poll this endpoint. Rate limiting is done on a per Ratings Provider basis, so requests from independent clients used by the same provider count against the same quota. summary: Regional Limits Real Time Snapshot tags: - Real-Time parameters: - $ref: '#/components/parameters/query-filter' - $ref: '#/components/parameters/resource-id-filter' responses: '200': description: The System Operating Limits snapshot is returned. content: application/vnd.trolie.realtime-limits-snapshot.v1+json: schema: $ref: '#/components/schemas/realtime-limits-snapshot' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d limits: - resource-id: 8badf00d continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 application/vnd.trolie.realtime-limits-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/realtime-limits-snapshot-elide-psr' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 limits: - resource-id: 8badf00d continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json: schema: $ref: '#/components/schemas/realtime-limits-detailed-snapshot' example: snapshot-header: source: provider: X-AMPL-RC last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 5 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d limits: - resource-id: 8badf00d additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 175 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2025-07-12T14:10:12-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 - resource-id: 8badf00d-UTILITY-B-SEG-id source: last-updated: '2025-07-12T14:10:12-07:00' provider: UTILITY-B origin-id: 8badf00d-UTILITY-B-correlation-id continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 166 - duration-name: STE limit: mva: 171 - duration-name: DAL limit: mva: 175 temporary-aar-exceptions: - id: 284928-2025-07-12T16:00:00-07:00 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/realtime-limits-detailed-snapshot-elide-psr' example: snapshot-header: source: provider: X-AMPL-RC last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 5 limits: - resource-id: 8badf00d additional-data: vendor-specific-data: {} continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 175 provenance: - resource-id: 8badf00d proposals-considered: - resource-id: 8badf00d-UTILITY-A-SEG-id source: last-updated: '2025-07-12T14:10:12-07:00' provider: UTILITY-A origin-id: 8badf00d-UTILITY-A-correlation-id continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 - resource-id: 8badf00d-UTILITY-B-SEG-id source: last-updated: '2025-07-12T14:10:12-07:00' provider: UTILITY-B origin-id: 8badf00d-UTILITY-B-correlation-id continuous-operating-limit: mva: 150 emergency-operating-limits: - duration-name: LTE limit: mva: 166 - duration-name: STE limit: mva: 171 - duration-name: DAL limit: mva: 175 temporary-aar-exceptions: - id: 284928-2025-07-12T16:00:00-07:00 source: origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67 provider: UTILITY-A last-updated: '2025-07-12T16:00:00-07:00' resource: resource-id: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 overrides: - continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 reason: TOI 20250701-01 start-time: '2025-07-01T00:00:00-07:00' application/vnd.trolie.realtime-limits-snapshot-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/realtime-limits-snapshot-slim' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - 160 - 170 - - 155 - 160 application/vnd.trolie.realtime-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true: schema: $ref: '#/components/schemas/realtime-limits-snapshot-slim-inputs-used' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d limits: - - 160 - 170 - - 155 - 160 inputs-used: - name: dry bulb temperature (Fahrenheit) unit: degF values: - 50 - 51 headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' description: Not Acceptable (Content negotiation failed) content: application/problem+json: schema: $ref: '#/components/schemas/problem' examples: Compression Required: summary: Only compressed responses are supported value: type: //trolie.example.com/spec/client-errors/406/compression-required title: 'Not Acceptable: Accept-Encoding Required' status: 406 detail: 'This resource must be compressed with one of the following algorithms: gzip, deflate, br.' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:operating-snapshot /rating-proposals/forecast: get: operationId: getRatingForecastProposalStatus summary: Obtain forecast proposal status description: | Used to obtain the status of the Ratings Forecast proposal. The response is implicitly restricted to the requesting Ratings Provider's obligation. Accordingly, the caller can use this endpoint to check the state of their proposal submission. Note that the same status object is returned for each `patchRatingForecastProposal`, so this endpoint may seem redundant. However, an anticipated use case for this `GET` endpoint is to support supervisor processes that are setup by the client to independently ensure the provider's process for rating submission if functioning properly. For example, the Rating Provider might have one program responsible for producing and submitting Ratings Forecasts via `patchRatingForecastProposal`, while having a separate monitoring job that checks this endpoint regularly. Clients SHOULD perform Conditional `GET` using the `If-None-Match` header and the `ETag` of a previous `GET` response to poll this endpoint. Rate limiting is done on a per Ratings Provider basis, so requests from independent clients used by the same provider count against the same quota. tags: - Forecasting responses: '200': description: OK content: application/vnd.trolie.rating-forecast-proposal-status.v1+json: schema: $ref: '#/components/schemas/forecast-proposal-status' example: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' incomplete-obligation-count: 1 incomplete-obligations: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d invalid-proposal-count: 1 proposal-validation-errors: - message: The `resource-forecast-proposal` for `8badf00d` is incomplete. resource-id: 8badf00d headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '406': $ref: '#/components/responses/406-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:forecast-proposals patch: operationId: patchRatingForecastProposal summary: Submit a Forecast Proposal description: | In every Forecast Window, a new area-wide Forecast Proposal is created on the TROLIE server of the Clearinghouse Provider. Each Ratings Provider then `PATCH`es the area-wide proposal with the forecasts for their respective Ratings Obligations. Any unmet Ratings Obligations will result in the Clearinghouse Provider using an appropriate Recourse Rating for those unmet obligations. For Ratings Providers with a natural split in their Ratings Obligations, e.g., geographic or control areas, the `PATCH` semantics afford the ability to submit multiple Forecast Proposals containing just proposals for the relevant resources, if they choose to do so. This affordance can also be leveraged to split a large proposal into one or more parts in cases where that is advantageous from a performance or reliable delivery perspective. There are two supported media types for a Real-Time Ratings proposals. `application/vnd.trolie.rating-forecast-proposal.v1+json` allows the Ratings Provider to combine different limit types, such as `apparent-power` (MVA) and `current` (MW), in a single proposal. `application/vnd.trolie.rating-forecast-proposal-slim.v1+json` for proposals that only require a single limit type, e.g., `apparent-power`. Clients *MUST* specify that [limit-type](#tag/limit-type) as a media type parameter. For example, ```http PATCH /ratings-proposals/forecast HTTP/1.1 Content-Type: application/vnd.trolie.rating-forecast-proposal-slim.v1+json; limit-type=apparent-power ``` Note that this format is much more concise but requires significant care in serialization/deserialization. For details, see [Using Slim Media Types](../example-narratives/using-slim-media-types). tags: - Forecasting responses: '202': description: | The update was accepted for later processing. Updates to ratings may need to undergo additional validation and propagation to other systems. content: application/vnd.trolie.rating-forecast-proposal-status.v1+json: schema: $ref: '#/components/schemas/forecast-proposal-status' example: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' incomplete-obligation-count: 1 incomplete-obligations: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d invalid-proposal-count: 1 proposal-validation-errors: - message: The `resource-forecast-proposal` for `8badf00d` is incomplete. resource-id: 8badf00d headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '406': $ref: '#/components/responses/406-problem' '409': description: Conflict with Forecast Window content: application/problem+json: schema: $ref: '#/components/schemas/problem' example: type: //trolie.example.com/spec/client-errors/409/forecast-Window-closed title: 'Conflict: Forecast Window Closed' status: 409 detail: The proposed forecast was late. The first hour of the forecast was 2025-05-07T12:00:00-0500, and it was received at 2025-05-07T11:23:45-0500, but the Forecast Window closed at 2025-05-07T11:00:00-0500. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': description: Unprocessable Content content: application/problem+json: schema: $ref: '#/components/schemas/problem' example: type: //trolie.example.com/spec/client-errors/422/invalid-units title: 'Unprocessable Entity: Invalid Units' status: 422 detail: The proposal for 8badf00d at 2025-05-07T12:00:00Z specified `mw` so Active Power is assumed, but this exchange requires the power factor `pf` be specified as well. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:forecast-proposals requestBody: required: true content: application/vnd.trolie.rating-forecast-proposal.v1+json: schema: $ref: '#/components/schemas/array-max-monitored-elements_forecast-proposal' example: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d ratings: - resource-id: 8badf00d periods: - period-start: '2025-11-01T01:00:00-05:00' period-end: '2025-11-01T02:00:00-05:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 170 - period-start: '2025-11-01T01:00:00-06:00' period-end: '2025-11-02T02:00:00-06:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 170 application/vnd.trolie.rating-forecast-proposal-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/forecast-proposal-slim' examples: No Inputs Provided: summary: No Inputs Provided in the Forecast Proposal value: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' ends: '2025-11-01T05:00:00-05:00' default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d ratings: - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 140 - 145 - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 140 - 145 Dry Bulb Temp Provided: summary: Dry Bulb Temp Provided in the Forecast Proposal value: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' ends: '2025-11-01T05:00:00-05:00' default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d ratings: - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 140 - 145 - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 140 - 145 inputs-used: - name: dry bulb temperature (Fahrenheit) unit: degF values: - - 50 - 51 - 52 - 53 - - 46.1 - 46.5 - 47.1 - 48 /seasonal-ratings/snapshot: get: operationId: getSeasonalRatingsSnapshot description: Retrieve the nominal and seasonal ratings. summary: Get Seasonal Ratings tags: - Seasonal parameters: - $ref: '#/components/parameters/query-filter' - $ref: '#/components/parameters/resource-id-filter' responses: '200': description: OK content: application/vnd.trolie.seasonal-rating-snapshot.v1+json: schema: $ref: '#/components/schemas/seasonal-ratings-snapshot' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d ratings: - resource-id: segmentX periods: - period-start: '2024-04-01T01:00:00Z' period-end: '2024-07-01T01:00:00Z' season-name: spring continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 application/vnd.trolie.seasonal-rating-snapshot-detailed.v1+json: schema: $ref: '#/components/schemas/seasonal-ratings-snapshot-detailed' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d ratings: - resource-id: LINE1 periods: - period-start: '2024-04-01T01:00:00Z' period-end: '2024-07-01T01:00:00Z' season-name: spring continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 proposals-considered: - resource-id: 8badf00d period-start: '2024-04-01T01:00:00Z' period-end: '2024-07-01T01:00:00Z' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 season-name: spring continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 application/vnd.trolie.seasonal-rating-snapshot-detailed.v1+json; include-psr-header=false: schema: $ref: '#/components/schemas/seasonal-ratings-snapshot-detailed-elide-psr' example: snapshot-header: source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 ratings: - resource-id: LINE1 periods: - period-start: '2024-04-01T01:00:00Z' period-end: '2024-07-01T01:00:00Z' season-name: spring continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 proposals-considered: - resource-id: 8badf00d period-start: '2024-04-01T01:00:00Z' period-end: '2024-07-01T01:00:00Z' source: provider: X-AMPL last-updated: '2023-07-12T16:00:00-07:00' origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00 season-name: spring continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 180 headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:operating-snapshot /rating-proposals/seasonal: get: operationId: getSeasonalRatingProposalStatus summary: Obtain seasonal rating proposal status description: | Used to obtain the status of the Seasonal Ratings proposal. The response is implicitly restricted to the requesting Ratings Provider's obligation. Accordingly, the caller can use this endpoint to check the state of their proposal submission. Note that the same status object is returned for each `patchSeasonalRatingsProposal`, so this endpoint may seem redundant. However, an anticipated use case for this `GET` endpoint is to support supervisor processes that are setup by the client to independently ensure the provider's process for rating submission if functioning properly. For example, the Rating Provider might have one program responsible for producing and submitting Seasonal Ratings via `patchSeasonalRatingsProposal`, while having a separate monitoring job that checks this endpoint regularly. Clients SHOULD perform Conditional `GET` using the `If-None-Match` header and the `ETag` of a previous `GET` response to poll this endpoint. Rate limiting is done on a per Ratings Provider basis, so requests from independent clients used by the same provider count against the same quota. tags: - Seasonal responses: '200': description: OK content: application/vnd.trolie.seasonal-ratings-proposal-status.v1+json: schema: $ref: '#/components/schemas/seasonal-ratings-proposal-status' examples: complete: summary: Status reflects no errors or outstanding obligations value: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 incomplete-obligation-count: 0 incomplete-obligations: [] invalid-proposal-count: 0 proposal-validation-errors: [] incomplete: summary: Status reflects outstanding obligations value: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 incomplete-obligation-count: 1 incomplete-obligations: - resource-id: 8badf00d obligation-period-begins: '2024-01-01T00:00:00-05:00' obligation-period-ends: '2024-01-01T00:00:00-05:00' periods: - season-name: WINTER begins: '2024-01-01T00:00:00-05:00' invalid-proposal-count: 0 proposal-validation-errors: [] headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '406': $ref: '#/components/responses/406-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:seasonal-proposals patch: operationId: patchSeasonalRatingsProposal summary: Submit a Seasonal Ratings proposal description: | This operation allows the Ratings Provider to provide a partial or complete updates of their Seasonal Ratings that will be used by the Clearinghouse Provider to determine the Seasonal Ratings Schedule. tags: - Seasonal responses: '202': description: | The update was accepted for later processing. Updates to ratings may need to undergo additional validation and propagation to other systems. content: application/vnd.trolie.seasonal-ratings-proposal-status.v1+json: schema: $ref: '#/components/schemas/seasonal-ratings-proposal-status' examples: complete: summary: Status reflects no errors or outstanding obligations value: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 incomplete-obligation-count: 0 incomplete-obligations: [] invalid-proposal-count: 0 proposal-validation-errors: [] incomplete: summary: Status reflects outstanding obligations value: source: provider: UTILITY-A last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 incomplete-obligation-count: 1 incomplete-obligations: - resource-id: 8badf00d obligation-period-begins: '2024-01-01T00:00:00-05:00' obligation-period-ends: '2024-01-01T00:00:00-05:00' periods: - season-name: WINTER begins: '2024-01-01T00:00:00-05:00' invalid-proposal-count: 0 proposal-validation-errors: [] headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '406': $ref: '#/components/responses/406-problem' '409': description: Conflict with Seasonal Ratings Schedule content: application/problem+json: schema: $ref: '#/components/schemas/problem' headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': $ref: '#/components/responses/422-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:seasonal-proposals requestBody: description: | There are two supported media types for a Seasonal Ratings proposals. `application/vnd.trolie.seasonal-ratings-proposal.v1+json` allows the Ratings Provider to combine different limit types, such as `apparent-power` (MVA) and `current` (MW), in a single proposal. `application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json` for proposals that only require a single limit type, e.g., `apparent-power`. Clients *MUST* specify that [limit-type](#tag/limit-type) as a media type parameter. For example, ```http PATCH /rating-proposals/seasonal HTTP/1.1 Content-Type: application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power ``` Note that this format is much more concise but requires significant care in serialization/deserialization. For details, see the schema description for the [seasonal ratings proposal of an individual resource](#schema/seasonal-proposals-slim) which is the description for each element of the `ratings` array. required: true content: application/vnd.trolie.seasonal-ratings-proposal.v1+json: schema: $ref: '#/components/schemas/seasonal-ratings-proposal' example: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID ratings: - resource-id: 8badf00d periods: - season-name: WINTER period-start: '2024-11-15T00:00:00-05:00' period-end: '2025-03-01T00:00:00-05:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - season-name: SPRING period-start: '2025-03-01T00:00:00-05:00' period-end: '2025-06-15T00:00:00-05:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - season-name: SUMMER period-start: '2025-06-15T00:00:00-05:00' period-end: '2025-09-01T00:00:00-05:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - season-name: FALL period-start: '2025-09-01T00:00:00-05:00' period-end: '2025-11-15T00:00:00-05:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/seasonal-ratings-proposal-slim' example: proposal-header: source: last-updated: '2024-11-20T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID default-seasonal-schedule: schedule: - season-name: WINTER begins: '2024-11-15T00:00:00-05:00' - season-name: SPRING begins: '2025-03-01T00:00:00-05:00' - season-name: SUMMER begins: '2025-06-15T00:00:00-05:00' - season-name: FALL begins: '2025-09-01T00:00:00-05:00' ends: '2025-11-15T00:00:00-05:00' ratings: - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 155 - 160 - - - 161 - 171 - - 156 - 161 - - 146 - 151 - - 156 - 161 /seasonal-overrides: get: operationId: getSeasonalOverrides description: | Search for Seasonal Overrides. Will return any Seasonal Overrides that overlap with the start/end period. Clients SHOULD perform Conditional `GET` using the `If-None-Match` header and the `ETag` of a previous `GET` response. summary: Get Seasonal Overrides tags: - Seasonal Overrides parameters: - $ref: '#/components/parameters/period-start-query' - $ref: '#/components/parameters/period-end' - $ref: '#/components/parameters/query-filter' - $ref: '#/components/parameters/segment-filter' responses: '200': description: The requested seasonal ratings are returned. content: application/vnd.trolie.seasonal-override-set.v1+json: schema: $ref: '#/components/schemas/seasonal-override-set' example: - source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/seasonal-overrides/513a7cb3-5d3c-4b7e-849c-e4015846db53 id: 513a7cb3-5d3c-4b7e-849c-e4015846db53 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: Increased vegetation proximity headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:seasonal-overrides post: operationId: createSeasonalOverride description: | Create a new seasonal override summary: | Create a new seasonal override tags: - Seasonal Overrides requestBody: required: true content: application/vnd.trolie.seasonal-override.v1+json: schema: $ref: '#/components/schemas/seasonal-override-request' example: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: 513a7cb3-5d3c-4b7e-849c-e4015846db53 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: Increased vegetation proximity responses: '201': description: The seasonal override was created content: application/vnd.trolie.seasonal-override.v1+json: schema: $ref: '#/components/schemas/seasonal-override' example: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/seasonal-overrides/513a7cb3-5d3c-4b7e-849c-e4015846db53 id: 513a7cb3-5d3c-4b7e-849c-e4015846db53 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: Increased vegetation proximity headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' Location: $ref: '#/components/headers/Location' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': $ref: '#/components/responses/422-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:seasonal-overrides /seasonal-overrides/{id}: get: operationId: getSeasonalOverride description: Obtain a specific temporary seasonal rating by Id. summary: Obtain a specific temporary seasonal rating by Id. tags: - Seasonal Overrides parameters: - $ref: '#/components/parameters/id' responses: '200': description: OK content: application/vnd.trolie.seasonal-override.v1+json: schema: $ref: '#/components/schemas/seasonal-override' example: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/seasonal-overrides/513a7cb3-5d3c-4b7e-849c-e4015846db53 id: 513a7cb3-5d3c-4b7e-849c-e4015846db53 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: Increased vegetation proximity headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '410': $ref: '#/components/responses/410-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:seasonal-overrides delete: operationId: deleteSeasonalOverride description: Delete a specific seasonal override by its Id. summary: Delete a specific seasonal override by its Id. tags: - Seasonal Overrides parameters: - $ref: '#/components/parameters/id' responses: '204': $ref: '#/components/responses/204' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '409': description: Seasonal overrides already employed in Operations cannot be deleted. content: application/problem+json: schema: $ref: '#/components/schemas/problem' example: type: //trolie.example.com/spec/client-errors/409/seasonal-override-in-use title: 'Conflict: Seasonal Override in Use' status: 409 detail: Seasonal Override with id 'fb06e551-37a8-4a98-8c97-fded702530d6' may not be deleted, as it has been used in operations and is now part of the record. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:seasonal-overrides put: operationId: updateSeasonalOverride description: Updates an existing Seasonal override summary: Updates an existing Seasonal override tags: - Seasonal Overrides parameters: - $ref: '#/components/parameters/id' requestBody: required: true content: application/vnd.trolie.seasonal-override.v1+json: schema: $ref: '#/components/schemas/seasonal-override' example: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/seasonal-overrides/513a7cb3-5d3c-4b7e-849c-e4015846db53 id: 513a7cb3-5d3c-4b7e-849c-e4015846db53 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-08-01T00:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: Increased vegetation proximity responses: '204': $ref: '#/components/responses/204' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': $ref: '#/components/responses/422-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:seasonal-overrides /temporary-aar-exceptions: get: operationId: getTemporaryAARExceptions description: | Search for Temporary AAR Exceptions. Will return any Temporary AAR Exceptions that overlap with the start/end period. Clients SHOULD perform Conditional `GET` using the `If-None-Match` header and the `ETag` of a previous `GET` response. summary: Temporary AAR Exceptions tags: - Temporary AAR Exceptions parameters: - $ref: '#/components/parameters/period-start-query' - $ref: '#/components/parameters/period-end' - $ref: '#/components/parameters/query-filter' - $ref: '#/components/parameters/segment-filter' responses: '200': description: OK content: application/vnd.trolie.temporary-aar-exception-set.v1+json: schema: $ref: '#/components/schemas/temporary-aar-exception-set' example: - source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/temporary-aar-exceptions/46f7212b-1633-4c30-ba71-c6e987b2ded7 id: 46f7212b-1633-4c30-ba71-c6e987b2ded7 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: High wildfire risk forecasted until mid-day 7/13/25 headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:temporary-aar-exceptions post: operationId: createTemporaryAARException description: Create a new temporary AAR Exception summary: Create a new temporary AAR Exception tags: - Temporary AAR Exceptions requestBody: required: true content: application/vnd.trolie.temporary-aar-exception.v1+json: schema: $ref: '#/components/schemas/temporary-aar-exception-request' example: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/temporary-aar-exceptions/46f7212b-1633-4c30-ba71-c6e987b2ded7 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: High wildfire risk forecasted until mid-day 7/13/25 responses: '201': description: The temporary AAR Exception was created. content: application/vnd.trolie.temporary-aar-exception.v1+json: schema: $ref: '#/components/schemas/temporary-aar-exception' example: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/temporary-aar-exceptions/46f7212b-1633-4c30-ba71-c6e987b2ded7 id: 46f7212b-1633-4c30-ba71-c6e987b2ded7 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: High wildfire risk forecasted until mid-day 7/13/25 headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' Location: $ref: '#/components/headers/Location' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': $ref: '#/components/responses/422-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:temporary-aar-exceptions /temporary-aar-exceptions/{id}: get: operationId: getTemporaryAARException description: Obtain a specific temporary AAR exception by Id. summary: Obtain a specific temporary AAR exception by Id. tags: - Temporary AAR Exceptions parameters: - $ref: '#/components/parameters/id' responses: '200': description: OK content: application/vnd.trolie.temporary-aar-exception.v1+json: schema: $ref: '#/components/schemas/temporary-aar-exception' example: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/temporary-aar-exceptions/46f7212b-1633-4c30-ba71-c6e987b2ded7 id: 46f7212b-1633-4c30-ba71-c6e987b2ded7 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: High wildfire risk forecasted until mid-day 7/13/25 headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '410': $ref: '#/components/responses/410-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:temporary-aar-exceptions delete: operationId: deleteTemporaryAARException description: Delete a specific temporary AAR Exception by Id. summary: Delete a specific temporary AAR Exception by Id. tags: - Temporary AAR Exceptions parameters: - $ref: '#/components/parameters/id' responses: '204': $ref: '#/components/responses/204' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '409': description: Temporary AAR Exceptions already employed in Operations cannot be deleted. content: application/problem+json: schema: $ref: '#/components/schemas/problem' example: type: //trolie.example.com/spec/client-errors/409/temporary-aar-exception-in-use title: 'Conflict: Temporary AAR Exception in Use' status: 409 detail: Temporary AAR Exception with id 'fb06e551-37a8-4a98-8c97-fded702530d6' may not be deleted, as it has been used in rating snapshots and is now part of the record. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:temporary-aar-exceptions put: operationId: updateTemporaryAARException description: Updates an existing Temporary AAR Exception. summary: Updates an existing Temporary AAR Exception. tags: - Temporary AAR Exceptions parameters: - $ref: '#/components/parameters/id' requestBody: required: true content: application/vnd.trolie.temporary-aar-exception.v1+json: schema: $ref: '#/components/schemas/temporary-aar-exception' example: source: provider: X-AMPL last-updated: '2023-07-12T15:05:43.044267100-07:00' origin-id: //trolie.example.com/temporary-aar-exceptions/46f7212b-1633-4c30-ba71-c6e987b2ded7 id: 46f7212b-1633-4c30-ba71-c6e987b2ded7 resource: resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: emergency limit: mva: 165 - duration-name: load-shed limit: mva: 170 reason: High wildfire risk forecasted until mid-day 7/13/25 responses: '204': $ref: '#/components/responses/204' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': $ref: '#/components/responses/422-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:temporary-aar-exceptions /monitoring-sets: post: operationId: createMonitoringSet description: | Create a new monitoring set. The server will assign a unique identifier and source info to the monitoring set upon creation. This information will be available in the monitoring set `source` header and in the HTTP `Location` header. A 409 Conflict may be returned depending on the implementation. For example, if the monitoring set id that would be generated conflicts with an existing monitoring set, as could be the case if the id was generated by the client. As another example, a provided `alternate-identifiers` entry may conflict with existing identifiers. summary: Create a new monitoring set tags: - Monitoring Sets requestBody: required: true content: application/vnd.trolie.monitoring-set-request.v1+json: schema: $ref: '#/components/schemas/request' responses: '201': description: The monitoring set was created content: application/vnd.trolie.monitoring-set.v1+json: schema: $ref: '#/components/schemas/response' example: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: RC-NERC-ID origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 id: UTILITY123 description: Lines in utility 123's footprint and immediate neighbors power-system-resources: - resource-id: urn:uuid:01925421-0766-771a-a92d-1631a49f647c alternate-identifiers: - name: MYSUBSTN.LN.12345 type: EMSID authority: RC-NERC-ID - name: X-00001785-A type: AssetRegForm authority: RC-NERC-ID - resource-id: urn:uuid:01925421-b967-78de-a746-7497c5105939 alternate-identifiers: - name: MYSUBSTN.LN.67890 type: EMSID authority: RC-NERC-ID - name: X-00001787-C type: AssetRegForm authority: RC-NERC-ID application/vnd.trolie.monitoring-set.v2+json: schema: $ref: '#/components/schemas/response_v2' example: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: RC-NERC-ID origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 id: urn:uuid:5c1f8d0b-a170-4e5e-9f74-a35e6be170b4 name: UTILITY123 description: Lines in utility 123's footprint and immediate neighbors power-system-resources: - resource-id: urn:uuid:01925421-0766-771a-a92d-1631a49f647c alternate-identifiers: - name: MYSUBSTN.LN.12345 type: EMSID authority: RC-NERC-ID - name: X-00001785-A type: AssetRegForm authority: RC-NERC-ID - resource-id: urn:uuid:01925421-b967-78de-a746-7497c5105939 alternate-identifiers: - name: MYSUBSTN.LN.67890 type: EMSID authority: RC-NERC-ID - name: X-00001787-C type: AssetRegForm authority: RC-NERC-ID headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' Location: $ref: '#/components/headers/Location' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '406': $ref: '#/components/responses/406-problem' '409': description: Conflict content: application/problem+json: schema: $ref: '#/components/schemas/problem' headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': $ref: '#/components/responses/422-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:monitoring-sets /monitoring-sets/{id}: get: operationId: getMonitoringSet description: Obtain a specific monitoring set by identifier. summary: Obtain a specific monitoring set by identifier. tags: - Monitoring Sets parameters: - $ref: '#/components/parameters/path-filter' responses: '200': description: OK content: application/vnd.trolie.monitoring-set.v1+json: schema: $ref: '#/components/schemas/response' example: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: RC-NERC-ID origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 id: UTILITY123 description: Lines in utility 123's footprint and immediate neighbors power-system-resources: - resource-id: urn:uuid:01925421-0766-771a-a92d-1631a49f647c alternate-identifiers: - name: MYSUBSTN.LN.12345 type: EMSID authority: RC-NERC-ID - name: X-00001785-A type: AssetRegForm authority: RC-NERC-ID - resource-id: urn:uuid:01925421-b967-78de-a746-7497c5105939 alternate-identifiers: - name: MYSUBSTN.LN.67890 type: EMSID authority: RC-NERC-ID - name: X-00001787-C type: AssetRegForm authority: RC-NERC-ID application/vnd.trolie.monitoring-set.v2+json: schema: $ref: '#/components/schemas/response_v2' example: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: RC-NERC-ID origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 id: urn:uuid:5c1f8d0b-a170-4e5e-9f74-a35e6be170b4 name: UTILITY123 description: Lines in utility 123's footprint and immediate neighbors power-system-resources: - resource-id: urn:uuid:01925421-0766-771a-a92d-1631a49f647c alternate-identifiers: - name: MYSUBSTN.LN.12345 type: EMSID authority: RC-NERC-ID - name: X-00001785-A type: AssetRegForm authority: RC-NERC-ID - resource-id: urn:uuid:01925421-b967-78de-a746-7497c5105939 alternate-identifiers: - name: MYSUBSTN.LN.67890 type: EMSID authority: RC-NERC-ID - name: X-00001787-C type: AssetRegForm authority: RC-NERC-ID headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:monitoring-sets put: operationId: updateMonitoringSet description: | Update an existing monitoring set. Returns 403 Forbidden if the monitoring set is read-only. Returns 404 Not Found if the monitoring set does not exist or the principal does not have read access to it. A 409 Conflict may be returned depending on the implementation. For example, a provided `alternate-identifiers` entry may conflict with existing identifiers. A 422 Unprocessable Entity may be returned if the request body is semantically invalid. For example, if any of the power system resources defined in the monitoring set cannot be found; you cannot monitor a facility that does not exist. summary: Update an existing monitoring set tags: - Monitoring Sets parameters: - $ref: '#/components/parameters/path-filter' requestBody: required: true content: application/vnd.trolie.monitoring-set.v1+json: schema: $ref: '#/components/schemas/response' example: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: RC-NERC-ID origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 id: UTILITY123 description: Lines in utility 123's footprint and immediate neighbors power-system-resources: - resource-id: urn:uuid:01925421-0766-771a-a92d-1631a49f647c alternate-identifiers: - name: MYSUBSTN.LN.12345 type: EMSID authority: RC-NERC-ID - name: X-00001785-A type: AssetRegForm authority: RC-NERC-ID - resource-id: urn:uuid:01925421-b967-78de-a746-7497c5105939 alternate-identifiers: - name: MYSUBSTN.LN.67890 type: EMSID authority: RC-NERC-ID - name: X-00001787-C type: AssetRegForm authority: RC-NERC-ID responses: '204': $ref: '#/components/responses/204' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '409': $ref: '#/components/responses/409' '413': $ref: '#/components/responses/413-empty' '415': $ref: '#/components/responses/415-problem' '422': $ref: '#/components/responses/422-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:monitoring-sets delete: operationId: deleteMonitoringSet description: | Delete a specific monitoring set by its identifier. Returns 403 Forbidden if the monitoring set is read-only. Returns 404 Not Found if the monitoring set does not exist or the principal does not have read access to it. Returns 409 Conflict if the monitoring set cannot be deleted, for example, if it is currently the authenticated principal's default monitoring set. summary: Delete a specific monitoring set by its identifier tags: - Monitoring Sets parameters: - $ref: '#/components/parameters/path-filter' responses: '204': $ref: '#/components/responses/204' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '409': $ref: '#/components/responses/409' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - write:monitoring-sets /default-monitoring-set: get: operationId: getDefaultMonitoringSet summary: Obtain your default monitoring set. description: | Obtain the default monitoring set for the authorized principal. TROLIE implementations SHOULD provide a default monitoring set for each principal. The default monitoring set is the monitoring set that is used for limits snapshots when the `monitoring-set-id` query parameter is not supplied. tags: - Monitoring Sets responses: '200': description: OK content: application/vnd.trolie.monitoring-set.v1+json: schema: $ref: '#/components/schemas/response' example: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: RC-NERC-ID origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 id: UTILITY123 description: Lines in utility 123's footprint and immediate neighbors power-system-resources: - resource-id: urn:uuid:01925421-0766-771a-a92d-1631a49f647c alternate-identifiers: - name: MYSUBSTN.LN.12345 type: EMSID authority: RC-NERC-ID - name: X-00001785-A type: AssetRegForm authority: RC-NERC-ID - resource-id: urn:uuid:01925421-b967-78de-a746-7497c5105939 alternate-identifiers: - name: MYSUBSTN.LN.67890 type: EMSID authority: RC-NERC-ID - name: X-00001787-C type: AssetRegForm authority: RC-NERC-ID application/vnd.trolie.monitoring-set.v2+json: schema: $ref: '#/components/schemas/response_v2' example: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: RC-NERC-ID origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 id: urn:uuid:5c1f8d0b-a170-4e5e-9f74-a35e6be170b4 name: UTILITY123 description: Lines in utility 123's footprint and immediate neighbors power-system-resources: - resource-id: urn:uuid:01925421-0766-771a-a92d-1631a49f647c alternate-identifiers: - name: MYSUBSTN.LN.12345 type: EMSID authority: RC-NERC-ID - name: X-00001785-A type: AssetRegForm authority: RC-NERC-ID - resource-id: urn:uuid:01925421-b967-78de-a746-7497c5105939 alternate-identifiers: - name: MYSUBSTN.LN.67890 type: EMSID authority: RC-NERC-ID - name: X-00001787-C type: AssetRegForm authority: RC-NERC-ID headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': $ref: '#/components/responses/304' '400': $ref: '#/components/responses/400-problem' '401': $ref: '#/components/responses/401-empty' '403': $ref: '#/components/responses/403-empty' '404': $ref: '#/components/responses/404-empty' '406': $ref: '#/components/responses/406-problem' '429': $ref: '#/components/responses/429-empty' '500': $ref: '#/components/responses/500-empty' default: $ref: '#/components/responses/500-empty' security: - oauth2-primary-flow: - read:monitoring-sets components: responses: '201': description: Created. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' Location: $ref: '#/components/headers/Location' '204': description: Operation successful. No Content. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' '304': description: Not Modified. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' '406': headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' ETag: $ref: '#/components/headers/ETag' description: Not Acceptable (Content negotiation failed) content: application/problem+json: schema: $ref: '#/components/schemas/problem' examples: Compression Required: summary: Only compressed responses are supported value: type: //trolie.example.com/spec/client-errors/406/compression-required title: 'Not Acceptable: Accept-Encoding Required' status: 406 detail: 'This resource must be compressed with one of the following algorithms: gzip, deflate, br.' '409': description: Conflict content: application/problem+json: schema: $ref: '#/components/schemas/problem' headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' 400-problem: description: Malformed request headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/problem' 401-empty: description: Unauthorized headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/*: schema: $ref: '#/components/schemas/empty' 403-empty: description: Access denied headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/*: schema: $ref: '#/components/schemas/empty' 404-empty: description: Not Found headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/*: schema: $ref: '#/components/schemas/empty' 406-problem: description: Not Acceptable (Content negotiation failed) headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/problem' 410-problem: description: | Gone. The requested resource is no longer available. TROLIE implementations MAY return this status code when a resource is known to have been deleted or archived, if the authenticated client would otherwise have had authorized access to the resource. headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/problem' 413-empty: description: Payload too large headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/*: schema: $ref: '#/components/schemas/empty' 415-problem: description: Unsupported media type headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' Accept: schema: type: string pattern: ^((application\/vnd\.trolie\.(?:[a-z-]+)\.v\d+\+json(;q=(0\.\d+|1\.0))?))(\,\s*(application\/vnd\.trolie\.(?:[a-z-]+)\.v\d+\+json(;q=(0\.\d+|1\.0))?))*$ maxLength: 500 examples: Forecast Proposal: summary: Used to update the area-wide forecast value: application/vnd.trolie.rating-forecast-proposal.v1+json Real-Time Proposal: summary: Used to update the area-wide nowcast value: application/vnd.trolie.rating-realtime-proposal.v1+json Accept-Encoding: description: | The server must support and prefer Brotli yet must accept gzip for compatibility. schema: type: string enum: - br,gzip content: application/problem+json: schema: $ref: '#/components/schemas/problem' 422-problem: description: Unprocessable content headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/problem' 429-empty: description: Too many requests (rate limiting) headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/*: schema: $ref: '#/components/schemas/empty' 500-empty: description: An unexpected error occurred headers: X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Reset: $ref: '#/components/headers/X-Rate-Limit-Reset' content: application/*: schema: $ref: '#/components/schemas/empty' schemas: empty: description: Intended to proactively avoid information disclosure type: string nullable: true maxLength: 0 pattern: ^$ example: '' problem: description: See [RFC9457](https://www.rfc-editor.org/rfc/rfc9457#appendix-A). type: object properties: type: type: string format: uri-reference maxLength: 2048 description: | A URI reference that identifies the problem type. See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-type) example: https://iana.org/assignments/http-problem-types#date title: type: string format: free-text maxLength: 500 description: | A short, human-readable summary of the problem type. See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-title) status: type: number minimum: 100 maximum: 599 description: | The HTTP status code generated by the origin server for this occurrence of the problem. detail: type: string format: free-text maxLength: 500 description: A human-readable explanation specific to this occurrence of the problem. See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-detail) instance: type: string format: uri-reference maxLength: 2048 description: | A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-status) example: https://iana.org/assignments/http-problem-types#date required: - type period-start: description: | RFC 3339 date-time string with *no fractional seconds component* that designates a start or end to an operating period (such as an hour) that starts at a specified time. This will frequently be at the start of an hour, but may be finer-grained, such as every 30 minutes, should the Clearinghouse Provider choose. If the Transmission Provider is operating in EST, these are valid and equivalent values: * 2023-01-01T06:00Z * 2023-01-01T01:00-5:00 * 2023-01-01T00:00-6:00 * 2023-01-01T11:30+5:30 The server should uniformly represent date-times in the operational time zone of the Clearinghouse Provider. type: string format: date-time maxLength: 25 example: '2025-07-12T03:00:00-05:00' local: type: string maxLength: 500 pattern: ^(.){0,500}$ description: | Contains a identifier that is unique for an object in the context of an exchange between two grid operators. example: '86753_1' resource-id: type: string maxLength: 500 pattern: ^(.){0,500}$ description: | Contains a unique identifier for a power system resource, such as a transmission facility, segment, interface, etc. This identifier is typically used between reliability coordinators in operations. example: urn:uuid:123e4567-e89b-12d3-a456-426614174000 entity: type: string maxLength: 500 pattern: ^(.){0,500}$ description: | Contains a unique identifier for an entity, such as a grid operator or organization. This identifier is typically used in the context of data exchange between entities. example: org:naesb:weq:eir:MISO timestamp: description: RFC 3339 date-time string with a maximum of 10 digits in the fractional seconds component, i.e., nanosecond precision. type: string format: date-time maxLength: 35 data-provenance: type: object description: | Provides information about where the associated representation came from. *No functional aspects of the exchange are contingent upon this data.* However, this information is meant to support debugging and application support use cases, so implementors are encouraged to provide meaningful values. * `provider` identifies that entity, e.g., a Ratings Provider or Clearinghouse Provider, that created the object. The `provider`'s NERC id is recommended. * `last-updated` indicates the wall-clock time at the `provider` when the object was last modified. N.b. this is not when the message describing the object was sent or received, i.e., implementors should not simply insert the current timestamp here when preparing the object serialization. * `origin-id` is the identifier used by the `provider` to uniquely nominate the object. It is recommended but not required that this be a URI. properties: provider: $ref: '#/components/schemas/entity' last-updated: $ref: '#/components/schemas/timestamp' origin-id: $ref: '#/components/schemas/local' required: - provider - last-updated emergency-durations: type: array description: Defines the durations in minutes used for emergency limits. minItems: 1 maxItems: 10 items: type: object properties: name: description: | A type of limit as defined in the Transmission Provider's operating manual, usually indicating specific scenarios under which the limit may be used as well as a maximum period for which the limit may be safely applied. type: string maxLength: 20 pattern: ^[A-Za-z\-]{3,10}$ example: emergency duration-minutes: type: integer format: int32 minimum: 0 maximum: 1440 required: - name - duration-minutes limiting-analysis: type: string description: | Indicates how a operating limit was determined. This is used to provide context for the ratings proposals and limits snapshots. When defined in the header, this is assumed to apply to any limit that does not specify its own limiting analysis. When defined for a period, it applies to the `continuous-operating-limit` as well as the associated `emergency-operating-limits`, unless the `emergency-operating-limits` specify their own limiting analysis. THERMAL_RATING - The limit was determined by the thermal rating of underlying equipment. TRANSIENT_SECURITY_ASSESSMENT - Studies of the system's transient stability determined the limit. VOLTAGE_SECURITY_ASSESSMENT - Studies of the system's voltage stability determined the limit. SMALL_SIGNAL_STABILITY_ASSESSMENT - Small-signal stability studies determined the limit. SYSTEM_SPECIFIC - This could account for limits imposed by specific system characteristics, such as the presence of sensitive loads, the need to maintain specific power flows, or other reliability/volatility reasons. These include limits defined by Special Protection Schemes and Remedial Action Schemes. ENVIRONMENTAL_CONDITIONS - The limit was determined by exceptional environmental conditions such as wildfire risk, ice loading, excessive wind/galloping, or other factors. CONTRACT_CAPACITY - The available facility transfer capacity is limited by contractual obligations. REGULATORY_REQUIREMENTS - The limit is imposed by regulatory requirements. OTHER - The limit was determined by some other means not anticipated in this standard. enum: - THERMAL_RATING - TRANSIENT_SECURITY_ASSESSMENT - VOLTAGE_SECURITY_ASSESSMENT - SMALL_SIGNAL_STABILITY_ASSESSMENT - SYSTEM_SPECIFIC - ENVIRONMENTAL_CONDITIONS - REGULATORY_REQUIREMENTS - CONTRACT_CAPACITY - OTHER name-type: description: Type of the name being referenced. Corresponds to the IEC CIM `NameType` concept. type: string maxLength: 20 pattern: ^[A-Za-z0-9\-]{3,20}$ example: EMSID names: type: object properties: resource-id: $ref: '#/components/schemas/resource-id' alternate-identifiers: type: array maxItems: 10 minItems: 1 items: type: object properties: name: $ref: '#/components/schemas/local' type: $ref: '#/components/schemas/name-type' authority: $ref: '#/components/schemas/entity' mrid: $ref: '#/components/schemas/local' required: - name required: - resource-id named-power-system-resources: type: array minItems: 1 maxItems: 50000 description: Collection of power system resource names items: $ref: '#/components/schemas/names' forecast-snapshot-header: description: Details about the snapshot provided by the Clearinghouse provider. properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' begins: description: | RFC 3339 date-time string with *no fractional seconds component* that Nominates the operational window of this snapshot. type: string format: date-time maxLength: 25 example: '2025-07-12T03:00:00-05:00' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' required: - begins - source - power-system-resources - default-emergency-durations active-power: type: object title: Active Power additionalProperties: false properties: mw: type: number description: Active Power in megawatts format: float minimum: 1 maximum: 10000 kV: description: The voltage in kilovolts. type: number format: int32 minimum: 0 maximum: 1100 required: - mw active-power-with-power-factor: type: object title: Active Power and Power Factor additionalProperties: false properties: mw: type: number description: Active Power in megawatts format: float minimum: 1 maximum: 10000 kV: description: The voltage in kilovolts. type: number format: int32 minimum: 0 maximum: 1100 pf: type: number description: Assumed power factor. format: float minimum: 0 maximum: 1 required: - mw - pf apparent-power: type: object title: Apparent Power additionalProperties: false properties: mva: type: number description: Representation of a limit in megavolt-amperes (MVA). format: float minimum: 1 maximum: 10000 kV: description: The voltage in kilovolts. type: number format: int32 minimum: 0 maximum: 1100 required: - mva current: type: object title: Current description: Representation of a thermal limit in amperes. additionalProperties: false properties: amps: type: number format: float minimum: 1 maximum: 100000 required: - amps reactive-power: type: object title: Reactive Power description: Representation of a limit in megavolt-amperes reactive (MVAR). additionalProperties: false properties: mvar: type: number format: float minimum: -10000 maximum: 10000 required: - mvar overvoltage-threshold-pu: type: object title: Overvoltage Threshold per unit description: | An upper limit to voltage for a transmission facility in per unit with the base voltage assumed to be the nominal voltage. additionalProperties: false properties: voltage-pu-max: type: number format: float minimum: 0 maximum: 2 required: - voltage-pu-max overvoltage-threshold: type: object title: Overvoltage Threshold description: An upper limit to voltage for a transmission facility in kilovolts. additionalProperties: false properties: kV-max: description: The voltage in kilovolts. type: number format: int32 minimum: 0 maximum: 1100 required: - kV-max undervoltage-threshold-pu: type: object title: Undervoltage Threshold per unit description: | An lower limit to voltage for a transmission facility in per unit with the nominal voltage assumed to be the base voltage. additionalProperties: false properties: voltage-pu-min: type: number format: float minimum: 0 maximum: 2 required: - voltage-pu-min undervoltage-threshold: type: object title: Undervoltage Threshold description: A lower limit to voltage for a transmission facility in kilovolts. additionalProperties: false properties: kV-min: description: The voltage in kilovolts. type: number format: int32 minimum: 0 maximum: 1100 required: - kV-min limit: type: object title: Limit description: | Defines the limit. In practice most exchanges will only support one kind of limit for proposals and snapshots. However, the specification supports defining limits on a per resource basis as well as limit types that are not anticipated to be used to implement Order 881. TROLIE server implementations must support at least one of these limit types and should return a well known `application/problem+json` response if they receive a proposal in an unsupported but valid limit type as defined here. When used as the media type parameter `limit-type`, these are nominated by the following names. * `active-power` * `active-power-with-power-factor` * `apparent-power` * `current` * `reactive-power` * `overvoltage-threshold-pu` * `overvoltage-threshold` * `undervoltage-threshold-pu` * `undervoltage-threshold` oneOf: - $ref: '#/components/schemas/active-power' - $ref: '#/components/schemas/active-power-with-power-factor' - $ref: '#/components/schemas/apparent-power' - $ref: '#/components/schemas/current' - $ref: '#/components/schemas/reactive-power' - $ref: '#/components/schemas/overvoltage-threshold-pu' - $ref: '#/components/schemas/overvoltage-threshold' - $ref: '#/components/schemas/undervoltage-threshold-pu' - $ref: '#/components/schemas/undervoltage-threshold' limit-value-set: type: array description: | A set of general limit or rating values, each mapped to the various limit bands defined by the Transmission Provider's operating manual. This typically consists of a "normal" limit, as well as limits for various levels of emergency conditions (typically 2-4) defined in the operations manual. minItems: 1 maxItems: 10 items: type: object description: Operating Limit properties: duration-name: description: | A type of limit as defined in the Transmission Provider's operating manual, usually indicating specific scenarios under which the limit may be used as well as a maximum period for which the limit may be safely applied. type: string maxLength: 20 pattern: ^[A-Za-z\-]{3,10}$ example: emergency limit: $ref: '#/components/schemas/limit' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' required: - duration-name - limit forecast-snapshot: type: object properties: period-start: $ref: '#/components/schemas/period-start' period-end: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' required: - period-start - period-end - continuous-operating-limit - emergency-operating-limits additionalProperties: false forecast-limit-item: type: object additionalProperties: false properties: resource-id: $ref: '#/components/schemas/resource-id' periods: type: array maxItems: 300 items: $ref: '#/components/schemas/forecast-snapshot' required: - resource-id - periods forecast-limits-snapshot: type: object description: A snapshot of the forecast for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/forecast-snapshot-header' limits: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: $ref: '#/components/schemas/forecast-limit-item' required: - snapshot-header - limits forecast-snapshot-header-elide-psr: description: | Details about the snapshot provided by the Clearinghouse provider. The `power-system-resources` property is omitted from this header. properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' begins: description: | RFC 3339 date-time string with *no fractional seconds component* that Nominates the operational window of this snapshot. type: string format: date-time maxLength: 25 example: '2025-07-12T03:00:00-05:00' required: - begins - source - default-emergency-durations forecast-limits-snapshot-elide-psr: type: object description: A snapshot of the forecast for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/forecast-snapshot-header-elide-psr' limits: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: $ref: '#/components/schemas/forecast-limit-item' required: - snapshot-header - limits forecast-snapshot-slim-header: description: Details about the snapshot provided by the Clearinghouse provider. properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' begins: description: | RFC 3339 date-time string with *no fractional seconds component* that Nominates the operational window of this snapshot. type: string format: date-time maxLength: 25 example: '2025-07-12T03:00:00-05:00' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' ends: description: | RFC 3339 date-time string with *no fractional seconds component* that indicates that last period for each individual resource proposal, identifying the appropriate operational window for this proposal. type: string format: date-time maxLength: 25 example: '2025-07-12T03:00:00-05:00' required: - begins - ends - source - power-system-resources - default-emergency-durations slim: type: array title: Slim Period minItems: 1 maxItems: 11 items: type: number resource-forecast-proposal-slim: type: array maxItems: 300 items: $ref: '#/components/schemas/slim' forecast-limits-snapshot-slim: type: object description: A slim snapshot of the forecast for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/forecast-snapshot-slim-header' limits: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: $ref: '#/components/schemas/resource-forecast-proposal-slim' required: - snapshot-header - limits resource-forecast-inputs: type: array maxItems: 300 items: type: number format: float unit: type: string description: | If the `value` is dimensionless, this property should not be provided. Since we are not specifying which inputs shall be provided, we cannot specify a definitive list of units, but implementors are encouraged to use UnitSymbol from CIM when appropriate: The CIM may not include appropriate units for all inputs, e.g., wind speed, degrees Fahrenheit, etc. format: unit maxLength: 50 forecast-limits-snapshot-slim-inputs-used: type: object description: | A slim snapshot of the forecast for a monitoring set, including the inputs that were used to determine the continuous limits. properties: snapshot-header: $ref: '#/components/schemas/forecast-snapshot-slim-header' limits: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: $ref: '#/components/schemas/resource-forecast-proposal-slim' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: type: object properties: name: type: string format: free-text maxLength: 50 values: type: array minItems: 1 maxItems: 50000 description: | Since this is expected to be used for wind speed or temperature, we expect an array of numbers for each resource. An empty array is used to indicate that the inputs are not available for a particular resource. This could occur if the inputs were not provided by the Ratings Provider or if a recourse rating was utilized. items: $ref: '#/components/schemas/resource-forecast-inputs' unit: $ref: '#/components/schemas/unit' required: - name - values - unit required: - snapshot-header - limits forecast-snapshot-detailed: type: object properties: period-start: $ref: '#/components/schemas/period-start' period-end: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' additional-data: type: object description: | Implementors may use this object to provide freeform extensions with additional traceability / provenance data to be included with the limit. Schema of this object is out of scope of the TROLIE specification. required: - period-start - period-end - continuous-operating-limit - emergency-operating-limits additionalProperties: false forecast-limit-item-detailed: type: object additionalProperties: false properties: resource-id: $ref: '#/components/schemas/resource-id' periods: type: array maxItems: 300 items: $ref: '#/components/schemas/forecast-snapshot-detailed' required: - resource-id - periods quality-class-current-source: type: string description: | This property is modeled after the Quality Class called "Current Source" in ICCP. It is used to indicate the source of the current value of the proposed rating. The natural mapping of this property to the kinds of ratings or rating sources described in Order 881 is as follows. | ICCP | TROLIE | --------------|-------------------- | telemetered | DLR | | calculated | AAR | | estimated | Recourse Rating / time-bound static rating | | manual | Operator Override | enum: - Telemetered - Calculated - Estimated - Manual default: Calculated input: type: object properties: name: type: string format: free-text maxLength: 50 value: description: | The value of the input used in the ratings determination. The type of this value is not specified, but implementors are encouraged to use CIM types where appropriate. unit: type: string description: | If the `value` is dimensionless, this property should not be provided. Since we are not specifying which inputs shall be provided, we cannot specify a definitive list of units, but implementors are encouraged to use UnitSymbol from CIM when appropriate: The CIM may not include appropriate units for all inputs, e.g., wind speed, degrees Fahrenheit, etc. format: unit maxLength: 50 required: - name - value forecast-provenance: type: object properties: period-start: $ref: '#/components/schemas/period-start' period-end: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' current-source: $ref: '#/components/schemas/quality-class-current-source' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/input' source: $ref: '#/components/schemas/data-provenance' resource-id: $ref: '#/components/schemas/resource-id' required: - period-start - period-end - continuous-operating-limit - emergency-operating-limits - source title: Forecasted Period description: | Details a proposal that was considered by the Clearinghouse run. If `resource-id` is not provided, the ratings data is assumed to be for the overall facility. additionalProperties: false proposals-considered: type: array maxItems: 1200 items: $ref: '#/components/schemas/forecast-provenance' temporary-aar-exception-provenance: type: object description: | Data structure for a temporary AAR Exception against a resource. Includes a unique ID, start and (optional) end time, and a reason. May or may not include a set of values, depending on the business context in which the temporary AAR exception is used. properties: source: $ref: '#/components/schemas/data-provenance' resource: $ref: '#/components/schemas/names' start-time: $ref: '#/components/schemas/period-start' end-time: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' reason: description: | Free-form text indicating the reason for the exception. type: string format: free-form maxLength: 4000 id: $ref: '#/components/schemas/local' additionalProperties: false required: - id - start-time - continuous-operating-limit - emergency-operating-limits temporary-aar-exceptions: type: array maxItems: 1200 items: $ref: '#/components/schemas/temporary-aar-exception-provenance' operator-override-limit-provenance: type: object description: | Data structure for a temporary AAR Exception against a resource. Includes a unique ID, start and (optional) end time, and a reason. May or may not include a set of values, depending on the business context in which the temporary AAR exception is used. properties: source: $ref: '#/components/schemas/data-provenance' resource: $ref: '#/components/schemas/names' start-time: $ref: '#/components/schemas/period-start' end-time: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' reason: description: | The reason given for the limit override. type: string format: free-form maxLength: 4000 id: $ref: '#/components/schemas/local' additionalProperties: false required: - start-time - continuous-operating-limit - emergency-operating-limits - reason overrides: type: array maxItems: 1200 items: $ref: '#/components/schemas/operator-override-limit-provenance' forecast-limits-detailed-snapshot: type: object description: | A detailed snapshot of the forecast for a monitoring set. These details are meant to support analysis, archival, and troubleshooting. properties: snapshot-header: $ref: '#/components/schemas/forecast-snapshot-header' limits: type: array minItems: 1 maxItems: 50000 description: Forecast including provenance information. items: $ref: '#/components/schemas/forecast-limit-item-detailed' provenance: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: type: object properties: resource-id: $ref: '#/components/schemas/resource-id' proposals-considered: $ref: '#/components/schemas/proposals-considered' temporary-aar-exceptions: $ref: '#/components/schemas/temporary-aar-exceptions' overrides: $ref: '#/components/schemas/overrides' required: - resource-id - proposals-considered required: - snapshot-header - limits - provenance forecast-limits-detailed-snapshot-elide-psr: type: object description: | A detailed snapshot of the forecast for a monitoring set. These details are meant to support analysis, archival, and troubleshooting. properties: snapshot-header: $ref: '#/components/schemas/forecast-snapshot-header-elide-psr' limits: type: array minItems: 1 maxItems: 50000 description: Forecast including provenance information. items: $ref: '#/components/schemas/forecast-limit-item-detailed' provenance: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: type: object properties: resource-id: $ref: '#/components/schemas/resource-id' proposals-considered: $ref: '#/components/schemas/proposals-considered' temporary-aar-exceptions: $ref: '#/components/schemas/temporary-aar-exceptions' overrides: $ref: '#/components/schemas/overrides' required: - resource-id - proposals-considered required: - snapshot-header - limits - provenance schema: type: string format: duration maxLength: 10 default: PT1H example: P1D forecast-proposal-header: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' begins: description: | RFC 3339 date-time string with *no fractional seconds component* that must share the value of `period-start` for each individual resource proposal, identifying the appropriate operational window for this proposal. type: string format: date-time maxLength: 25 example: '2025-07-12T03:00:00-05:00' additionalProperties: false required: - begins - source - default-emergency-durations - power-system-resources description: | Populated by the Ratings Provider in a request to submit forecast ratings. The Clearinghouse implementation should record this information, and the detail limits snapshot should should reflect the appropriate metadata from the Clearinghouse Provider's perspective. forecast-proposal: type: object properties: period-start: $ref: '#/components/schemas/period-start' period-end: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' current-source: $ref: '#/components/schemas/quality-class-current-source' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/input' required: - period-start - period-end - continuous-operating-limit - emergency-operating-limits title: Forecasted Period description: | A Forecasted Period contains proposed limits for a power system object, e.g., a segment, that were forecasted for a particular Period in a Forecast Window. The status of the proposal as determined by the Clearinghouse is also included. additionalProperties: false resource-forecast-proposal: type: object additionalProperties: false properties: resource-id: $ref: '#/components/schemas/resource-id' periods: type: array maxItems: 300 items: $ref: '#/components/schemas/forecast-proposal' required: - resource-id - periods array-max-monitored-elements_forecast-proposal: type: object properties: proposal-header: $ref: '#/components/schemas/forecast-proposal-header' ratings: type: array minItems: 1 maxItems: 50000 description: Forecasted Ratings items: $ref: '#/components/schemas/resource-forecast-proposal' required: - proposal-header - ratings forecast-proposal-slim-header: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' begins: description: | RFC 3339 date-time string with *no fractional seconds component* that must share the value of `period-start` for each individual resource proposal, identifying the appropriate operational window for this proposal. type: string format: date-time maxLength: 25 example: '2025-07-12T03:00:00-05:00' ends: description: | RFC 3339 date-time string with *no fractional seconds component* that indicates that last period for each individual resource proposal, identifying the appropriate operational window for this proposal. type: string format: date-time maxLength: 25 example: '2025-07-12T03:00:00-05:00' current-source: $ref: '#/components/schemas/quality-class-current-source' additionalProperties: false required: - begins - ends - source - default-emergency-durations - power-system-resources description: | Populated by the Ratings Provider in a request to submit forecast ratings. The Clearinghouse implementation should record this information, and the detail limits snapshot should should reflect the appropriate metadata from the Clearinghouse Provider's perspective. forecast-proposal-slim: type: object properties: proposal-header: $ref: '#/components/schemas/forecast-proposal-slim-header' ratings: type: array minItems: 1 maxItems: 50000 description: Forecasted Ratings items: $ref: '#/components/schemas/resource-forecast-proposal-slim' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: type: object properties: name: type: string format: free-text maxLength: 50 values: type: array minItems: 1 maxItems: 50000 description: | Since this is expected to be used for wind speed or temperature, we expect an array of numbers for each resource. An empty array is used to indicate that the inputs are not available for a particular resource. This could occur if the inputs were not provided by the Ratings Provider or if a recourse rating was utilized. items: $ref: '#/components/schemas/resource-forecast-inputs' unit: $ref: '#/components/schemas/unit' required: - name - values - unit required: - proposal-header - ratings forecast-proposal-status: type: object description: | Status of the rating provider's forecast proposal relative to the current forecast window. Includes any validation errors encountered while processing proposals. properties: incomplete-obligation-count: description: | The number of facilities for this provider whose Ratings Obligation has not been met in this forecast window. This number may be larger than the size of `incomplete-obligations`, since the latter has a pre-defined upper bound for performance and application security reasons. The Ratings Provider should check that this value is zero when they believe they have completed their submission process. type: integer format: uint16 minimum: 0 maximum: 50000 incomplete-obligations: type: array description: | Indicates which Ratings Obligations have not been fulfilled. The size of this set is bounded and may be less than the actual count of unfulfilled Obligations indicated in `incomplete-obligation-count`. The intended use case for this set is debugging and troubleshooting. minItems: 0 maxItems: 50000 items: $ref: '#/components/schemas/names' invalid-proposal-count: description: | The number of `resource-forecast-proposal` objects that have been determined to be *invalid* during this Forecast Window for the current Ratings Provider. This count is provided for troubleshooting, establishing trends, and triggering alerts. type: integer format: uint16 minimum: 0 maximum: 50000 proposal-validation-errors: type: array description: The most recent validation errors minItems: 0 maxItems: 50 items: type: object additionalProperties: false description: | Validation errors. Note to implementors, the property `resource-id` intentionally is not `names` as was used in `incomplete-obligations` to mitigate the possibility of information disclosure when a Ratings Provider submits a proposal for a valid resource that they are not permitted to write to. It should be the same `resource-id` that the client submitted. properties: message: type: string pattern: ^(.){1,500}$ maxLength: 500 example: The `resource-forecast-proposal` for `8badf00d` is incomplete. resource-id: $ref: '#/components/schemas/resource-id' source: $ref: '#/components/schemas/data-provenance' begins: $ref: '#/components/schemas/period-start' required: - source - begins - incomplete-obligation-count - incomplete-obligations - invalid-proposal-count - proposal-validation-errors real-time-proposal-status: type: object description: | Status of the rating provider's real-time obligations. Includes any validation errors encountered while processing proposals. properties: incomplete-obligation-count: description: | The number of facilities for this provider whose Ratings Obligation has not been met in this forecast window. This number may be larger than the size of `incomplete-obligations`, since the latter has a pre-defined upper bound for performance and application security reasons. The Ratings Provider should check that this value is zero when they believe they have completed their submission process. type: integer format: uint16 minimum: 0 maximum: 50000 incomplete-obligations: type: array description: | Indicates which Ratings Obligations have not been fulfilled. The size of this set is bounded and may be less than the actual count of unfulfilled Obligations indicated in `incomplete-obligation-count`. The intended use case for this set is debugging and troubleshooting. minItems: 0 maxItems: 50000 items: $ref: '#/components/schemas/names' invalid-proposal-count: description: | The number of `resource-forecast-proposal` objects that have been determined to be *invalid* during this Forecast Window for the current Ratings Provider. This count is provided for troubleshooting, establishing trends, and triggering alerts. type: integer format: uint16 minimum: 0 maximum: 50000 proposal-validation-errors: type: array description: The most recent validation errors minItems: 0 maxItems: 50 items: type: object additionalProperties: false description: | Validation errors. Note to implementors, the property `resource-id` intentionally is not `names` as was used in `incomplete-obligations` to mitigate the possibility of information disclosure when a Ratings Provider submits a proposal for a valid resource that they are not permitted to write to. It should be the same `resource-id` that the client submitted. properties: message: type: string pattern: ^(.){1,500}$ maxLength: 500 example: The `resource-forecast-proposal` for `8badf00d` is incomplete. resource-id: $ref: '#/components/schemas/resource-id' source: $ref: '#/components/schemas/data-provenance' required: - source - incomplete-obligation-count - incomplete-obligations - invalid-proposal-count - proposal-validation-errors real-time-proposal-header: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' additionalProperties: false required: - source - default-emergency-durations - power-system-resources description: | Populated by the Ratings Provider in a request to submit real-time ratings. The Clearinghouse implementation should record this information, and the detail limits snapshot should should reflect the appropriate metadata from the Clearinghouse Provider's perspective. real-time-proposal: type: object properties: continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' resource-id: $ref: '#/components/schemas/resource-id' current-source: $ref: '#/components/schemas/quality-class-current-source' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/input' required: - resource-id - continuous-operating-limit - emergency-operating-limits additionalProperties: false realtime-proposal: type: object properties: proposal-header: $ref: '#/components/schemas/real-time-proposal-header' ratings: type: array minItems: 1 maxItems: 50000 description: Real-Time Ratings Proposals items: $ref: '#/components/schemas/real-time-proposal' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: type: object properties: name: type: string format: free-text maxLength: 50 values: type: array minItems: 1 maxItems: 50000 description: | Since this is expected to be used for wind speed or temperature, we expect an array of numbers for each resource. An empty array is used to indicate that the inputs are not available for a particular resource. This could occur if the inputs were not provided by the Ratings Provider or if a recourse rating was utilized. items: $ref: '#/components/schemas/resource-forecast-inputs' unit: type: string description: | Since we are not specifying which inputs shall be provided, we cannot specify a definitive list of units, but implementors are encouraged to use UnitSymbol from CIM when appropriate: The CIM may not include appropriate units for all inputs, e.g., wind speed, degrees Fahrenheit, etc. format: unit maxLength: 50 required: - name - values - unit required: - proposal-header - ratings real-time-proposal-slim-header: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' current-source: $ref: '#/components/schemas/quality-class-current-source' additionalProperties: false required: - source - default-emergency-durations - power-system-resources description: | Populated by the Ratings Provider in a request to submit real-time ratings. The Clearinghouse implementation should record this information, and the detail limits snapshot should should reflect the appropriate metadata from the Clearinghouse Provider's perspective. realtime-proposal-slim: type: object description: Used to propose real-time ratings for a set of resources. properties: proposal-header: $ref: '#/components/schemas/real-time-proposal-slim-header' ratings: type: array minItems: 1 maxItems: 50000 description: Real-Time Ratings Proposals items: $ref: '#/components/schemas/slim' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: type: object properties: name: type: string format: free-text maxLength: 50 values: type: array minItems: 1 maxItems: 50000 description: | Since this is expected to be used for wind speed or temperature, we expect an array of numbers for each resource. An empty array is used to indicate that the inputs are not available for a particular resource. This could occur if the inputs were not provided by the Ratings Provider or if a recourse rating was utilized. items: $ref: '#/components/schemas/resource-forecast-inputs' unit: $ref: '#/components/schemas/unit' required: - name - values - unit required: - proposal-header - ratings real-time-snapshot-header: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' additionalProperties: false required: - source - default-emergency-durations - power-system-resources description: Details about the snapshot provided by the Clearinghouse provider. realtime-snapshot: type: object properties: continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' resource-id: $ref: '#/components/schemas/resource-id' required: - resource-id - continuous-operating-limit - emergency-operating-limits additionalProperties: false realtime-limits-snapshot: type: object description: A snapshot of the realtime limits for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/real-time-snapshot-header' limits: type: array minItems: 1 maxItems: 50000 description: Real-time limits items: $ref: '#/components/schemas/realtime-snapshot' required: - snapshot-header - limits real-time-snapshot-header-elide-psr: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' additionalProperties: false required: - source - default-emergency-durations description: Details about the snapshot provided by the Clearinghouse provider. realtime-limits-snapshot-elide-psr: type: object description: A snapshot of the realtime limits for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/real-time-snapshot-header-elide-psr' limits: type: array minItems: 1 maxItems: 50000 description: Real-time limits items: $ref: '#/components/schemas/realtime-snapshot' required: - snapshot-header - limits realtime-snapshot-detailed: type: object properties: continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' resource-id: $ref: '#/components/schemas/resource-id' additional-data: type: object description: | Implementors may use this object to provide freeform extensions with additional traceability / provenance data to be included with the limit. Schema of this object is out of scope of the TROLIE specification. required: - resource-id - continuous-operating-limit - emergency-operating-limits additionalProperties: false real-time-provenance: type: object properties: continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' resource-id: $ref: '#/components/schemas/resource-id' current-source: $ref: '#/components/schemas/quality-class-current-source' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/input' source: $ref: '#/components/schemas/data-provenance' required: - resource-id - continuous-operating-limit - emergency-operating-limits - source additionalProperties: false realtime-limits-detailed-snapshot: type: object description: A snapshot of the realtime limits for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/real-time-snapshot-header' limits: type: array minItems: 1 maxItems: 50000 description: Real-time limits including provenance. items: $ref: '#/components/schemas/realtime-snapshot-detailed' provenance: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: type: object properties: resource-id: $ref: '#/components/schemas/resource-id' proposals-considered: type: array maxItems: 10 items: $ref: '#/components/schemas/real-time-provenance' temporary-aar-exceptions: type: array maxItems: 10 items: $ref: '#/components/schemas/temporary-aar-exception-provenance' overrides: type: array maxItems: 10 items: $ref: '#/components/schemas/operator-override-limit-provenance' required: - resource-id - proposals-considered required: - snapshot-header - limits - provenance realtime-limits-detailed-snapshot-elide-psr: type: object description: A snapshot of the realtime limits for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/real-time-snapshot-header-elide-psr' limits: type: array minItems: 1 maxItems: 50000 description: Real-time limits including provenance. items: $ref: '#/components/schemas/realtime-snapshot-detailed' provenance: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: type: object properties: resource-id: $ref: '#/components/schemas/resource-id' proposals-considered: type: array maxItems: 10 items: $ref: '#/components/schemas/real-time-provenance' temporary-aar-exceptions: type: array maxItems: 10 items: $ref: '#/components/schemas/temporary-aar-exception-provenance' overrides: type: array maxItems: 10 items: $ref: '#/components/schemas/operator-override-limit-provenance' required: - resource-id - proposals-considered required: - snapshot-header - limits - provenance realtime-limits-snapshot-slim: type: object description: A slim snapshot of the realtime limits for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/real-time-snapshot-header' limits: type: array minItems: 1 maxItems: 50000 description: Real-time limits items: $ref: '#/components/schemas/slim' required: - snapshot-header - limits realtime-limits-snapshot-slim-inputs-used: type: object description: | A slim snapshot of the realtime limits for a monitoring set, including the inputs used to determine the continuous limits. properties: snapshot-header: $ref: '#/components/schemas/real-time-snapshot-header' limits: type: array minItems: 1 maxItems: 50000 description: Real-time limits items: $ref: '#/components/schemas/slim' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: type: object properties: name: type: string format: free-text maxLength: 50 values: type: array minItems: 1 maxItems: 50000 description: | This is aligned with the `limits` property such that each resource entry is in the same position here. A null is used to indicate that the input is not available for a particular resource. This could occur if the inputs were not provided by the Ratings Provider or if a recourse rating was utilized. items: type: number format: float nullable: true unit: $ref: '#/components/schemas/unit' required: - name - values - unit required: - snapshot-header - limits - inputs-used common-header: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' additionalProperties: false required: - source - default-emergency-durations - power-system-resources season-name: type: string description: A name for the season maxLength: 255 pattern: \w+ day-night: description: | Optional label to specify if the proposed seasonal ratings schedule is meant to be used only during the day or only a night. If this field is not provided, the schedule is assumed to be valid for both day and night. type: string enum: - DAY - NIGHT seasonal-snapshot: type: object properties: period-start: $ref: '#/components/schemas/period-start' period-end: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' season-name: $ref: '#/components/schemas/season-name' day-night: $ref: '#/components/schemas/day-night' required: - period-start - period-end - continuous-operating-limit - emergency-operating-limits additionalProperties: false description: Proposes the continuous and emergency ratings for the specified Season. title: Seasonal Rating Proposal seasonal-rating-snapshot-item: type: object additionalProperties: false properties: resource-id: $ref: '#/components/schemas/resource-id' periods: description: | Defines the seasonal ratings schedule adopted in this proposal. Each season is given a `season-name` with the beginning of the season starting on `begins` and ending on the `begins` of the next season chronologically. It is required that the seasons are listed chronologically. type: array minItems: 1 maxItems: 240 items: $ref: '#/components/schemas/seasonal-snapshot' seasonal-ratings-snapshot: type: object description: A snapshot of the seasonal ratings for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/common-header' ratings: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: $ref: '#/components/schemas/seasonal-rating-snapshot-item' required: - snapshot-header - ratings seasonal-proposal-considered: type: object properties: period-start: $ref: '#/components/schemas/period-start' period-end: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' current-source: $ref: '#/components/schemas/quality-class-current-source' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/input' season-name: $ref: '#/components/schemas/season-name' day-night: $ref: '#/components/schemas/day-night' source: $ref: '#/components/schemas/data-provenance' resource-id: $ref: '#/components/schemas/resource-id' required: - source - resource-id title: Seasonal Rating Proposal description: Proposes the continuous and emergency ratings for the specified Season. additionalProperties: false seasonal-snapshot-detailed: type: object properties: period-start: $ref: '#/components/schemas/period-start' period-end: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' season-name: $ref: '#/components/schemas/season-name' day-night: $ref: '#/components/schemas/day-night' proposals-considered: description: | The seasonal ratings proposals considered when determining the seasonal ratings of a power system resource, e.g., a line or transformer. type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/seasonal-proposal-considered' required: - proposals-considered - period-start - period-end - continuous-operating-limit - emergency-operating-limits additionalProperties: false description: Proposes the continuous and emergency ratings for the specified Season. title: Seasonal Rating Proposal seasonal-rating-snapshot-item-detailed: type: object additionalProperties: false properties: resource-id: $ref: '#/components/schemas/resource-id' periods: description: | Defines the seasonal ratings schedule adopted in this proposal. Each season is given a `season-name` with the beginning of the season starting on `begins` and ending on the `begins` of the next season chronologically. It is required that the seasons are listed chronologically. type: array minItems: 1 maxItems: 240 items: $ref: '#/components/schemas/seasonal-snapshot-detailed' seasonal-ratings-snapshot-detailed: type: object description: A snapshot of the seasonal ratings for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/common-header' ratings: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: $ref: '#/components/schemas/seasonal-rating-snapshot-item-detailed' required: - snapshot-header - ratings base-header: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' additionalProperties: false required: - source - default-emergency-durations ratings: type: array minItems: 1 maxItems: 50000 description: Set of forecast limits items: $ref: '#/components/schemas/seasonal-rating-snapshot-item-detailed' seasonal-ratings-snapshot-detailed-elide-psr: type: object description: A snapshot of the seasonal ratings for a monitoring set. properties: snapshot-header: $ref: '#/components/schemas/base-header' ratings: $ref: '#/components/schemas/ratings' required: - snapshot-header - ratings season: type: object properties: season-name: $ref: '#/components/schemas/season-name' begins: $ref: '#/components/schemas/period-start' required: - season-name - begins missing-seasonal-obligation: type: object additionalProperties: false properties: resource-id: $ref: '#/components/schemas/resource-id' obligation-period-begins: $ref: '#/components/schemas/period-start' obligation-period-ends: $ref: '#/components/schemas/period-start' periods: description: | Defines the seasonal ratings schedule adopted in this proposal. Each season is given a `season-name` with the beginning of the season starting on `begins` and ending on the `begins` of the next season chronologically. It is required that the seasons are listed chronologically. type: array minItems: 1 maxItems: 240 items: $ref: '#/components/schemas/season' seasonal-ratings-proposal-status: type: object description: Seasonal rating proposal status properties: incomplete-obligation-count: description: | The number of facilities for this provider whose Ratings Obligation has not been met in this forecast window. This number may be larger than the size of `incomplete-obligations`, since the latter has a pre-defined upper bound for performance and application security reasons. The Ratings Provider should check that this value is zero when they believe they have completed their submission process. type: integer format: uint16 minimum: 0 maximum: 50000 incomplete-obligations: type: array description: | Indicates which Seasonal Ratings Obligations have not been fulfilled. The size of this set is bounded and may be less than the actual count of unfulfilled Obligations indicated in `incomplete-obligation-count`. minItems: 0 maxItems: 50000 items: $ref: '#/components/schemas/missing-seasonal-obligation' invalid-proposal-count: description: | The number of `resource-forecast-proposal` objects that have been determined to be *invalid* during this Forecast Window for the current Ratings Provider. This count is provided for troubleshooting, establishing trends, and triggering alerts. type: integer format: uint16 minimum: 0 maximum: 50000 proposal-validation-errors: type: array description: The most recent validation errors minItems: 0 maxItems: 50 items: type: object additionalProperties: false description: | Validation errors. Note to implementors, the property `resource-id` intentionally is not `names` as was used in `incomplete-obligations` to mitigate the possibility of information disclosure when a Ratings Provider submits a proposal for a valid resource that they are not permitted to write to. It should be the same `resource-id` that the client submitted. properties: message: type: string pattern: ^(.){1,500}$ maxLength: 500 example: The `resource-forecast-proposal` for `8badf00d` is incomplete. resource-id: $ref: '#/components/schemas/resource-id' source: $ref: '#/components/schemas/data-provenance' required: - source - incomplete-obligation-count - invalid-proposal-count seasonal-proposal-header: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' power-system-resources: $ref: '#/components/schemas/named-power-system-resources' additionalProperties: false required: - source - default-emergency-durations - power-system-resources description: | Describes the contents of this seasonal ratings proposal. seasonal-proposal: type: object properties: period-start: $ref: '#/components/schemas/period-start' period-end: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' limiting-analysis: $ref: '#/components/schemas/limiting-analysis' current-source: $ref: '#/components/schemas/quality-class-current-source' inputs-used: description: | Optional list of quantities used as input to the ratings determination. The particular information exchange determines which values may be expected as well as the conventions used to represent those values. This property is included to prescribe a way to include these inputs. type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/input' season-name: $ref: '#/components/schemas/season-name' day-night: $ref: '#/components/schemas/day-night' required: - period-start - period-end - continuous-operating-limit - emergency-operating-limits title: Seasonal Rating Proposal description: Proposes the continuous and emergency ratings for the specified Season. additionalProperties: false seasonal-proposals: x-tags: - Seasonal title: Per-Resource Seasonal Ratings Schedule type: object additionalProperties: false properties: resource-id: $ref: '#/components/schemas/resource-id' periods: description: | Defines the seasonal ratings schedule adopted in this proposal. Each season is given a `season-name` with the beginning of the season starting on `begins` and ending on the `begins` of the next season chronologically. It is required that the seasons are listed chronologically. type: array minItems: 1 maxItems: 240 items: $ref: '#/components/schemas/seasonal-proposal' seasonal-ratings-proposal: type: object properties: proposal-header: $ref: '#/components/schemas/seasonal-proposal-header' ratings: type: array minItems: 1 maxItems: 50000 description: Seasonal Ratings proposals items: $ref: '#/components/schemas/seasonal-proposals' required: - proposal-header - ratings ordered-named-power-system-resources: type: array minItems: 1 maxItems: 50000 description: | Ordered array of power system resource names. The order of these items determines the order of the ratings proposals in the `ratings` array. items: $ref: '#/components/schemas/names' seasonal-schedule: description: | Defines the seasonal ratings schedule adopted in this proposal. Each season is given a `season-name` with the beginning of the season starting on `begins` and ending on the `begins` of the next season chronologically. It is required that the seasons are listed chronologically. type: array minItems: 1 maxItems: 240 items: $ref: '#/components/schemas/season' seasonal-proposal-header-slim: type: object properties: source: $ref: '#/components/schemas/data-provenance' default-emergency-durations: $ref: '#/components/schemas/emergency-durations' default-limiting-analysis: $ref: '#/components/schemas/limiting-analysis' power-system-resources: $ref: '#/components/schemas/ordered-named-power-system-resources' default-seasonal-schedule: description: | Defines the seasonal schedule that is used in the proposal. Each season is defined in the `schedule` array and the `ends` property defines the end of the last season. Each individual facility proposal must have corresponding entry for each entry In the `schedule` array. properties: schedule: $ref: '#/components/schemas/seasonal-schedule' ends: $ref: '#/components/schemas/period-start' day-night: $ref: '#/components/schemas/day-night' required: - schedule - ends additionalProperties: false required: - source - default-emergency-durations - power-system-resources - default-seasonal-schedule description: | Describes the contents of the seasonal proposal. In particular, the structure of the `ratings` is determined by the details provided in this header. seasonal-proposal-slim: type: array title: Seasonal Period Proposal slim maxItems: 20 minItems: 1 items: type: number title: Continuous and Emergency Ratings values description: | Each number in this array corresponds to a value of the continuous and emergency ratings for a particular period. The first values correspond to the continuous (normal) rating and the subsequent values correspond to the emergency ratings in order of decreasing duration. The durations are defined in the `proposal-header.default-emergency-durations` field. The exact number of values in this array is further determined by the `limit-type` parameter of the media type. ```http Content-Type: application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power ``` If the [limit-type](#tag/limit-type) is single valued, like `apparent-power`, then the array will have a single value for each rating. For example, if there was only one emergency duration defined, then the array would have two values, e.g. `[50, 55]`, corresponding to a 50MVA continuous rating and 55MVA emergency rating, respectively. A single-valued limit type is anticipated to be the most common case in practice. However, if the [limit-type](#tag/limit-type) is `active-power` and the Clearinghouse Provider has required both MW and power factor, e.g., `{"mw":1, "pf":1}`, then the array will have two values for each rating. If we continue with the example of having only one emergency duration defined, then the array would have four values. Thus, instead of `[normal_MVA, emergency_MVA]`, we would have `[normal_MW, normal_pf, emergency_MW, emergency_pf]`, e.g., `[300, 1.0, 350, 1.0]`. seasonal-proposals-slim: description: | A proposal for the seasonal ratings for a power system object, e.g., a segment. The proposal's structure is determined by the contents of the `proposal-header`. In particular, this element should have an entry corresponding to each season in the `default-seasonal-schedule`. type: array minItems: 1 maxItems: 240 items: $ref: '#/components/schemas/seasonal-proposal-slim' x-tags: - Seasonal title: Per-Resource Seasonal Ratings Schedule (slim) example: - - 50 - 55 - 60 - 65 - - 70 - 75 - 80 - 85 - - 90 - 95 - 100 - 105 - - 90 - 95 - 100 - 105 seasonal-ratings-proposal-slim: type: object properties: proposal-header: $ref: '#/components/schemas/seasonal-proposal-header-slim' ratings: type: array minItems: 1 maxItems: 50000 description: Seasonal Ratings proposals (slim) items: $ref: '#/components/schemas/seasonal-proposals-slim' required: - proposal-header - ratings seasonal-override: type: object description: | Data structure for a seasonal override against a resource. Includes a unique ID, start and (optional) end time, and a reason. Must also include a set of values. properties: source: $ref: '#/components/schemas/data-provenance' resource: $ref: '#/components/schemas/names' start-time: $ref: '#/components/schemas/period-start' end-time: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' reason: description: | Free-form text indicating the reason for the exception. type: string format: free-form maxLength: 4000 id: $ref: '#/components/schemas/local' day-night: $ref: '#/components/schemas/day-night' additionalProperties: false required: - id - resource - start-time - continuous-operating-limit - emergency-operating-limits seasonal-override-set: type: array minItems: 0 maxItems: 50000 items: $ref: '#/components/schemas/seasonal-override' seasonal-override-request: type: object description: | Data structure for a seasonal override against a resource. Must also include a set of values. properties: source: $ref: '#/components/schemas/data-provenance' resource: $ref: '#/components/schemas/names' start-time: $ref: '#/components/schemas/period-start' end-time: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' reason: description: | Free-form text indicating the reason for the exception. type: string format: free-form maxLength: 4000 day-night: $ref: '#/components/schemas/day-night' additionalProperties: false required: - resource - start-time - continuous-operating-limit - emergency-operating-limits temporary-aar-exception: type: object description: | Data structure for a temporary AAR Exception against a resource. Includes a unique ID, start and (optional) end time, and a reason. May or may not include a set of values, depending on the business context in which the temporary AAR exception is used. properties: source: $ref: '#/components/schemas/data-provenance' resource: $ref: '#/components/schemas/names' start-time: $ref: '#/components/schemas/period-start' end-time: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' reason: description: | Free-form text indicating the reason for the exception. type: string format: free-form maxLength: 4000 id: $ref: '#/components/schemas/local' additionalProperties: false required: - id - resource - start-time - continuous-operating-limit - emergency-operating-limits temporary-aar-exception-set: type: array minItems: 0 maxItems: 50000 items: $ref: '#/components/schemas/temporary-aar-exception' temporary-aar-exception-request: type: object description: | Represents a temporary AAR Exception against a resource. Includes a start and (optional) end time, and a reason. May or may not include a set of values, depending on the business context in which the temporary AAR exception is used. properties: source: $ref: '#/components/schemas/data-provenance' resource: $ref: '#/components/schemas/names' start-time: $ref: '#/components/schemas/period-start' end-time: $ref: '#/components/schemas/period-start' continuous-operating-limit: $ref: '#/components/schemas/limit' emergency-operating-limits: $ref: '#/components/schemas/limit-value-set' reason: description: | Free-form text indicating the reason for the exception. type: string format: free-form maxLength: 4000 additionalProperties: false required: - resource - start-time - continuous-operating-limit - emergency-operating-limits request: type: object description: | Request body for creating a monitoring set. The server will assign an id and source upon successful creation. Note that any `alternate-identifiers` supplied in the request should be should be used by the server to define an alternate identifier for the associated with a power system resource. In this way monitoring sets can be used to introduce use case specific names for existing power system resources. The details of how alternate identifiers are managed and resolved are are out of scope for this specification. In particular how the `authority` of an alternate identifier is validated is implementation-specific and out of scope for this specification.. properties: name: type: string description: A human-readable name for this monitoring set maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9 _-]{1,255}$ description: type: string format: free-form description: A description of this monitoring set maxLength: 1000 power-system-resources: $ref: '#/components/schemas/named-power-system-resources' required: - power-system-resources - name response: type: object description: | See https://trolie.energy/concepts.html#monitoring-sets for info on the monitoring set concept in TROLIE. This representation is intended to be enough for consumers to read it and tell where the monitoring set came from, using metadata such as a source and an optional description. It also includes the list of resources included in the monitoring set, as well as all their known aliases. properties: name: type: string description: A human-readable name for this monitoring set maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9 _-]{1,255}$ description: type: string format: free-form description: A description of this monitoring set maxLength: 1000 power-system-resources: $ref: '#/components/schemas/named-power-system-resources' source: $ref: '#/components/schemas/data-provenance' id: $ref: '#/components/schemas/local' required: - source - id - power-system-resources response_v2: type: object description: | See https://trolie.energy/concepts.html#monitoring-sets for info on the monitoring set concept in TROLIE. This representation is intended to be enough for consumers to read it and tell where the monitoring set came from, using metadata such as a source and an optional description. It also includes the list of resources included in the monitoring set, as well as all their known aliases. properties: name: type: string description: A human-readable name for this monitoring set maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9 _-]{1,255}$ description: type: string format: free-form description: A description of this monitoring set maxLength: 1000 power-system-resources: $ref: '#/components/schemas/named-power-system-resources' source: $ref: '#/components/schemas/data-provenance' id: $ref: '#/components/schemas/local' required: - source - id - name - power-system-resources headers: ETag: description: | An opaque, unique identifier--typically a hash value--for a specific version of a resource. The modeled resource state is what is versioned, not the content of any particular representation. The server MUST use a strong validator so that the same ETag is returned regardless of the media type of the representation. schema: type: string format: hash maxLength: 256 additionalProperties: false Location: description: | The "Location" header field is used in some responses to refer to a specific resource in relation to the response. In TROLIE, this is always associated with a 201 response (a POST), and therefore refers to the URI of the resource created. schema: type: string format: uri-reference maxLength: 1000 X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer format: int32 minimum: 0 maximum: 1000 X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: integer format: int32 minimum: 0 maximum: 1000 X-Rate-Limit-Reset: description: The number of seconds left in the current period schema: type: integer format: int32 minimum: 0 maximum: 1000 Retry-After: schema: type: integer format: int32 minimum: 0 maximum: 60 example: 60 description: The seconds to delay after the response is received. securitySchemes: oauth2-primary-flow: type: oauth2 description: Support RFC8725 JWT tokens. flows: clientCredentials: tokenUrl: https://no-server/oauth2 scopes: read:monitoring-sets: Read monitoring sets read:forecast-proposals: Read Forecast rating proposals read:realtime-proposals: Read real-time rating proposals read:seasonal-proposals: Read seasonal rating proposals read:temporary-aar-exceptions: Read temporary AAR exceptions read:seasonal-overrides: Read seasonal overrides write:monitoring-sets: Write monitoring sets write:forecast-proposals: Submit forecasted ratings write:realtime-proposals: Submit realtime ratings write:seasonal-proposals: Submit seasonal ratings write:temporary-aar-exceptions: Write temporary AAR exceptions write:seasonal-overrides: Write seasonal overrides read:operating-snapshot: Read the ratings and limits snapshots in-use by the transmission provider read:regional-operating-snapshot: Read a Regional Operating Snapshot write:regional-operating-snapshot: Write a Regional Operating Snapshot parameters: offset-period-start: name: offset-period-start description: | Rather than return the entire forecast from the beginning, i.e., the next operating period, instead return a subset of the forecast starting with the period starting at `offset-period-start`. in: query required: false schema: $ref: '#/components/schemas/period-start' period-end: name: period-end description: Specifies the end of a period for which a filter specifies. Periods will only be returned that start prior to this time. in: query required: false schema: $ref: '#/components/schemas/period-start' query-filter: name: monitoring-set description: | Only return ratings or limits for facilities of the associated `monitoring-set`. The identifier for a `monitoring-set` is pre-coordinated, but using the NERC id of the associated Ratings Provider for the default monitoring set is recommended. in: query required: false schema: $ref: '#/components/schemas/local' examples: name: summary: A pre-coordinated name that nominates a `monitoring-set` for a specific entity or purpose. value: X-AMPL mrid: summary: A pre-coordinated id that nominates a `monitoring-set`. value: urn:uuid:12345678-1234-5678-1234-123456789012 resource-id-filter: name: resource-id description: | Only return limits for this power system resource in: query required: false schema: $ref: '#/components/schemas/resource-id' examples: circuit-id: summary: A typical AC line identifier value: '86753_1' mrid: summary: A CIM mrid for a power system resource value: urn:uuid:123e4567-e89b-12d3-a456-426614174000 static-only: name: static-only description: | Only return limits determined by static ratings. Without this parameter a forecast limits snapshot would include contain limits determined by considering dynamic ratings, like AARs or DLRs, when those were available for a particular forecast period. With `static-only=true`, the forecast limits snapshot would only include limits that were determined using static ratings, such as seasonal ratings, seasonal overrides, temporary AAR exceptions, operator overrides, etc. in: query required: false schema: type: boolean default: false temporal-resolution: name: temporal-resolution description: |+ Specifies the time aggregation for the forecast using ISO 8601 Duration syntax. If not provided, the API will default to hourly. Examples of values that **may** be supported by a given implementation include: * Hourly (default): PT1H * Daily: P1D * Weekly: P1W * Monthly: P1M * Yearly: P1Y * Quarterly: P3M If the API does not support the requested `temporal_resolution`, it will return a `422 Unprocessable Content` response. When this parameter is provided, both `offset-period-start` and `period-end` are required. Given `temporal-resolution` **R**, `offset-period-start` **S**, and `period-end` **E**, both **S** and **E** must agree on each duration component to the right of (so smaller than) **R**. For example, this is a valid combination: | parameter | value | | :--- | :--- | | temporal-resolution | P1D (i.e. "daily") | | offset-period-start | 2025-01-01T01:00:00Z | | period-end | 2025-01-04T01:00:00Z | However, this is not valid because the hours do not agree: | parameter | value | | :--- | :--- | | temporal-resolution | P1D | | offset-period-start | 2025-01-01T**01**:10:00Z | | period-end | 2025-01-04T**12**:00:00Z | Note that the minutes do not agree either, but that is essentially inconsequential since at the daily resolution the hours must first agree. As discussed in their respective parameters, `offset-period-start` and `period-end` nominate the **beginning** of the first and **end** of the last period (interval), respectively. Given our valid example above, the first period in the forecast would be for the 24-hours starting at `2025-01-01T01:00:00Z` and ending at `2025-01-02T01:00:00Z`, and the final period would be for the 24-hour period starting at `2025-01-03T01:00:00Z` and ending at `2025-01-04T01:00:00Z`. in: query required: false schema: type: string format: duration maxLength: 10 default: PT1H example: P1D period-start-query: name: period-start description: | Defines the start of an applicable operating period. in: query required: false schema: $ref: '#/components/schemas/period-start' segment-filter: name: segment description: | Only return limits for this segment. in: query required: false schema: $ref: '#/components/schemas/local' examples: mrid: summary: A CIM mrid value: urn:uuid:12345678-1234-5678-1234-123456789012 circuit-id: summary: A typical AC line identifier value: '86753_1' id: name: id description: | Opaque identifier for the object. Format of this identifier may very depending on the implementation. in: path required: true schema: $ref: '#/components/schemas/local' examples: uuid: value: urn:uuid:123e4567-e89b-12d3-a456-426614174000 description: Example of a UUIDv4 identifier for an object. eic: value: urn:eic:10X1001A1001A515 description: Example of an ENTSO-E Energy Identification Code for an object. qualified-entity-code: value: org:naesb:weq:eir:MISO description: | A fully-qualified representation of an entity code from the NAESB WEQ-022 Electric Industry Registry, currently implemented by the OATI webRegistry. Note that this representation is not an industry standard identifier format but is presented as an example of a structured identifier for such entity codes. In this example, the identifier is for Midcontinent Independent System Operator (MISO). entity-code: value: MISO description: | A unqualified entity code from the NAESB WEQ-022 Electric Industry Registry, currently implemented by the OATI webRegistry. In this example, the identifier is for Midcontinent Independent System Operator (MISO). ncr-id: value: NCR00826 description: An example of a NERC Compliance Registry code for MISO. path-filter: name: id description: | Only return ratings or limits for facilities of the associated `monitoring-set`. The identifier for a `monitoring-set` is pre-coordinated, but using the NERC id of the associated Ratings Provider for the default monitoring set is recommended. in: path required: true schema: $ref: '#/components/schemas/local' examples: name: summary: A pre-coordinated name that nominates a `monitoring-set` for a specific entity or purpose. value: X-AMPL mrid: summary: A pre-coordinated id that nominates a `monitoring-set`. value: urn:uuid:12345678-1234-5678-1234-123456789012 requestBodies: requestBody: required: true content: application/vnd.trolie.rating-forecast-proposal.v1+json: schema: $ref: '#/components/schemas/array-max-monitored-elements_forecast-proposal' example: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' default-emergency-durations: - name: LTE duration-minutes: 240 - name: STE duration-minutes: 30 - name: DAL duration-minutes: 15 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d ratings: - resource-id: 8badf00d periods: - period-start: '2025-11-01T01:00:00-05:00' period-end: '2025-11-01T02:00:00-05:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 170 - period-start: '2025-11-01T01:00:00-06:00' period-end: '2025-11-02T02:00:00-06:00' continuous-operating-limit: mva: 160 emergency-operating-limits: - duration-name: LTE limit: mva: 165 - duration-name: STE limit: mva: 170 - duration-name: DAL limit: mva: 170 application/vnd.trolie.rating-forecast-proposal-slim.v1+json; limit-type=apparent-power: schema: $ref: '#/components/schemas/forecast-proposal-slim' examples: No Inputs Provided: summary: No Inputs Provided in the Forecast Proposal value: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' ends: '2025-11-01T05:00:00-05:00' default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d ratings: - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 140 - 145 - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 140 - 145 Dry Bulb Temp Provided: summary: Dry Bulb Temp Provided in the Forecast Proposal value: proposal-header: source: last-updated: '2025-10-31T15:05:43.044267100-07:00' provider: UTILITY-A origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640 begins: '2025-11-01T01:00:00-05:00' ends: '2025-11-01T05:00:00-05:00' default-emergency-durations: - name: emergency duration-minutes: 240 power-system-resources: - resource-id: 8badf00d alternate-identifiers: - name: segmentX authority: TO-NERC-ID - name: LINE1 SEG-X authority: RC-NERC-ID mrid: 8badf00d - resource-id: f34d3d alternate-identifiers: - name: segmentY authority: TO-NERC-ID - name: LINE2 SEG-Y authority: RC-NERC-ID mrid: 8badf00d ratings: - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 140 - 145 - - - 160 - 170 - - 155 - 160 - - 145 - 150 - - 140 - 145 inputs-used: - name: dry bulb temperature (Fahrenheit) unit: degF values: - - 50 - 51 - 52 - 53 - - 46.1 - 46.5 - 47.1 - 48 x-tagGroups: - name: Operations tags: - Real-Time - Forecasting - Seasonal - Seasonal Overrides - Temporary AAR Exceptions - Monitoring Sets - name: Common Schemas tags: - limit-type