openapi: 3.2.0
info:
  title: Transmission Ratings and Operating Limits Information Exchange (TROLIE) Forecasting API
  x-logo:
    altText: TROLIE logo
    url: images/TROLIE-horizontal-color.svg
  description: "\nThis specification defines a set of operations for the exchange of power\nsystem ratings and limits between entities that own and operate the electric\npower system in North America. In particular, it is designed to support the\nexchange of Ambient Adjusted Ratings (AARs), pursuant to FERC Order 881.  It\nis published as a community standard to facilitate interoperability\nin these exchanges.\n\nThe specification conceives of the exchange as being between two primary\nentities:\n\n* A [Ratings Provider](https://trolie.energy/concepts#ratings-provider) is\n an entity that is responsible for providing ratings on some set of power\n system resources, e.g., Transmission Facilities, typically a Transmission\n Owner or Transmission Operator.  The ratings are provided to a\n Clearinghouse Provider whose is responsible for determining the operating\n limits of the power system resources.\n\n* The [Clearinghouse Provider](https://trolie.energy/concepts#clearinghouse-provider) is\n  typically a Transmission Provider (FERC) and a Reliability Coordinator (NERC).\n\nAdjacent Clearinghouse Providers exchange ratings in order to establish\noperating limit values for the power system resources that are shared\nbetween them.\n\nA Ratings Provider is assumed by this specification to have pre-coordinated \nwith a Clearinghouse Provider to identify the former's Ratings Obligation,\ni.e., the set of power system resources for which they will provide ratings.\nAdditionally, the Ratings Provider will have similarly pre-coordinated the\ndefinition of their Monitoring Sets, i.e., their power system limits of\ninterest. The nature and method of pre-coordination is out-of-scope for this\nspecification.\n\nNote that this API makes a strict distinction between the terms rating and\nlimit.  Colloquially, these terms are often used interchangeably.  However,\nin the context of this specification, they have distinct meanings. At a\nhigh-level, the specification defines an exchange where ratings go in and\nlimits come out. A Clearinghouse is a function for determining the operating\nlimits from the ratings it has on-hand, including those that are proposed by\nRatings Providers and any applicable time-bound static ratings.\n\nThis interaction diagram highlights the primary requests and responses that\nare defined in this spec. Note that not all of the operations will be\nsupported by every implementation.\n\n<img src=\"images/interactions.excalidraw.png\" alt=\"Primary Interactions with Ratings Provider\" />\n"
  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: 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.

    '
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: "\nReturns the latest Limits Forecast the clearinghouse has produced.\n\nThis content of the response varies significantly based on the media type requested.\n\n* `application/vnd.trolie.forecast-limits-snapshot.v1+json` simply includes the limits.\n* For use cases that require understanding *how* the limits were determined,\n  the media type `application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json`\n  is available; it contains the ratings proposals and other factors used to\n  generate the limits.\n\nBoth of these media types support the `include-psr-header` parameter. This\nis a boolean parameter that defaults to `true`. When set to `false`, the\n`power-system-resource` header is omitted.  This can result in smaller\npayloads when the client already knows the resource ids in use by the\nClearinghouse Provider.\n\n```http\nGET /limits/forecast-snapshot HTTP/1.1\nAccept: application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json; include-psr-header=false\n```\n\n### Slim Format\n\nThe `application/vnd.trolie.forecast-limits-snapshot-slim.v1+json` media type\nmay be used to request a more concise representation of the data.  The\nmedia type parameter `limit-type` is required to specify the type of limit\nbeing requested, for example:\n\n```http\nGET /limits/forecast-snapshot HTTP/1.1\nAccept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power\n```\nAdditionally, the `inputs-used` parameter may be set to `true` to include\nthe inputs used to generate the forecast.\n```http\nGET /limits/forecast-snapshot HTTP/1.1\nAccept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true\n```\n\nNote this format is much more concise but requires significant care in\nprocessing.  See [Using Slim Media\nTypes](../example-narratives/using-slim-media-types) for more details.\n\nClients SHOULD perform Conditional `GET` using the `If-None-Match` header\nand the `ETag` of a previous `GET` response to poll this endpoint. Rate\nlimiting is done on a per Ratings Provider basis, so requests from\nindependent clients used by the same provider count against the same\nquota.\n"
      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/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: "\nIn every Forecast Window, a new area-wide Forecast Proposal is created on\nthe TROLIE server of the Clearinghouse Provider. Each Ratings Provider then\n`PATCH`es the area-wide proposal with the forecasts for their respective\nRatings Obligations. Any unmet Ratings Obligations will result in the\nClearinghouse Provider using an appropriate Recourse Rating for those unmet\nobligations.\n\nFor Ratings Providers with a natural split in their Ratings Obligations,\ne.g., geographic or control areas, the `PATCH` semantics afford the ability\nto submit multiple Forecast Proposals containing just proposals for the\nrelevant resources, if they choose to do so. This affordance can also be\nleveraged to split a large proposal into one or more parts in cases where\nthat is advantageous from a performance or reliable delivery perspective.\n\n\nThere are two supported media types for a Real-Time Ratings proposals.\n\n`application/vnd.trolie.rating-forecast-proposal.v1+json` allows the \nRatings Provider to combine different limit types, such as\n`apparent-power` (MVA) and `current` (MW), in a single proposal.\n\n`application/vnd.trolie.rating-forecast-proposal-slim.v1+json` for\nproposals that only require a single limit type, e.g., `apparent-power`.\nClients *MUST* specify that [limit-type](#tag/limit-type) as a media type\nparameter. For example,\n```http\nPATCH /ratings-proposals/forecast HTTP/1.1\nContent-Type: application/vnd.trolie.rating-forecast-proposal-slim.v1+json; limit-type=apparent-power\n```\nNote that this format is much more concise but requires significant care\nin serialization/deserialization.  For details, see [Using Slim Media Types](../example-narratives/using-slim-media-types).\n"
      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
components:
  responses:
    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'
    '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'
    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'
    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'
    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'
    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'
    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'
    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'
    '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.'
    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'
  schemas:
    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-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
    overrides:
      type: array
      maxItems: 1200
      items:
        $ref: '#/components/schemas/operator-override-limit-provenance'
    empty:
      description: Intended to proactively avoid information disclosure
      type:
      - string
      - 'null'
      maxLength: 0
      pattern: ^$
      example: ''
    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-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
    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'
    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-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
    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
    limit:
      type: object
      title: Limit
      description: "\nDefines the limit. In practice most exchanges will only support one kind of\nlimit for proposals and snapshots. However, the specification supports\ndefining limits on a per resource basis as well as limit types that are not\nanticipated to be used to implement Order 881. TROLIE server implementations\nmust support at least one of these limit types and should return a well known\n`application/problem+json` response if they receive a proposal in an\nunsupported but valid limit type as defined here.\n\nWhen used as the media type parameter `limit-type`, these are nominated by\nthe following names.\n\n  * `active-power`\n  * `active-power-with-power-factor`\n  * `apparent-power`\n  * `current`\n  * `reactive-power`\n  * `overvoltage-threshold-pu`\n  * `overvoltage-threshold`\n  * `undervoltage-threshold-pu`\n  * `undervoltage-threshold`\n"
      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'
    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
    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
    proposals-considered:
      type: array
      maxItems: 1200
      items:
        $ref: '#/components/schemas/forecast-provenance'
    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
    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
    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
    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
    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
    slim:
      type: array
      title: Slim Period
      minItems: 1
      maxItems: 11
      items:
        type: number
    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
    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
    schema:
      type: string
      format: duration
      maxLength: 10
      default: PT1H
      example: P1D
    temporary-aar-exceptions:
      type: array
      maxItems: 1200
      items:
        $ref: '#/components/schemas/temporary-aar-exception-provenance'
    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
    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
    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
    resource-forecast-inputs:
      type: array
      maxItems: 300
      items:
        type: number
        format: float
    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'
    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
    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
    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
    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.

        '
    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
    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
    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
    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
    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
    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-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-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-slim:
      type: array
      maxItems: 300
      items:
        $ref: '#/components/schemas/slim'
    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
    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
    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
    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
    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-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
    data-provenance:
      type: object
      description: "\nProvides information about where the associated representation came from. *No\nfunctional aspects of the exchange are contingent upon this data.* However,\nthis information is meant to support debugging and application support use\ncases, so implementors are encouraged to provide\nmeaningful values.\n\n* `provider` identifies that entity, e.g., a Ratings Provider or Clearinghouse\n  Provider, that created the object. The `provider`'s NERC id is recommended.\n* `last-updated` indicates the wall-clock time at the `provider` when the\n  object was last modified. N.b. this is not when the message\n  describing the object was sent or received, i.e., implementors should not\n  simply insert the current timestamp here when preparing the object serialization.\n* `origin-id` is the identifier used by the `provider` to uniquely nominate\n  the object. It is recommended but not required that this be a URI.\n"
      properties:
        provider:
          $ref: '#/components/schemas/entity'
        last-updated:
          $ref: '#/components/schemas/timestamp'
        origin-id:
          $ref: '#/components/schemas/local'
      required:
      - provider
      - last-updated
    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
    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
    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
    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
    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
    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
    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
    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
  parameters:
    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\nsyntax. If not provided, the API will default to hourly. Examples of values\nthat **may** be supported by a given implementation include:\n  * Hourly (default): PT1H\n  * Daily: P1D\n  * Weekly: P1W\n  * Monthly: P1M\n  * Yearly: P1Y\n  * Quarterly: P3M\n\nIf the API does not support the requested `temporal_resolution`, it will\nreturn a `422 Unprocessable Content` response.\n\nWhen this parameter is provided, both `offset-period-start` and `period-end`\nare required.\n\nGiven `temporal-resolution` **R**, `offset-period-start` **S**, and\n`period-end` **E**, both **S** and **E** must agree on each duration component\nto the right of (so smaller than) **R**. For example, this is a valid\ncombination:\n\n| parameter           | value                |\n| :---                | :---                 |\n| temporal-resolution | P1D (i.e. \"daily\")   |\n| offset-period-start | 2025-01-01T01:00:00Z |\n| period-end          | 2025-01-04T01:00:00Z |\n\nHowever, this is not valid because the hours do not agree:\n| parameter           | value                    |\n| :---                | :---                     |\n| temporal-resolution | P1D                      |\n| offset-period-start | 2025-01-01T**01**:10:00Z |\n| period-end          | 2025-01-04T**12**:00:00Z |\n\nNote that the minutes do not agree either, but that is essentially\ninconsequential since at the daily resolution the hours must first agree.\n\nAs discussed in their respective parameters, `offset-period-start` and\n`period-end` nominate the **beginning** of the first and **end** of the last period\n(interval), respectively. Given our valid example above, the first period in\nthe forecast would be for the 24-hours starting at `2025-01-01T01:00:00Z` and\nending at `2025-01-02T01:00:00Z`, and the final period would be for the\n24-hour period starting at `2025-01-03T01:00:00Z` and ending at\n`2025-01-04T01:00:00Z`.\n\n"
      in: query
      required: false
      schema:
        type: string
        format: duration
        maxLength: 10
        default: PT1H
        example: P1D
    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
    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
  headers:
    Retry-After:
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 60
        example: 60
        description: The seconds to delay after the response is received.
    X-Rate-Limit-Reset:
      description: The number of seconds left in the current period
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 1000
    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
    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
  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
  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
x-tagGroups:
- name: Operations
  tags:
  - Real-Time
  - Forecasting
  - Seasonal
  - Seasonal Overrides
  - Temporary AAR Exceptions
  - Monitoring Sets
- name: Common Schemas
  tags:
  - limit-type