openapi: 3.2.0
info:
  title: Transmission Ratings and Operating Limits Information Exchange (TROLIE) Real Time 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: Real-Time
  description: 'If permitted by the Clearinghouse Provider, its Ratings Providers can use

    these functions to exchange real-time ratings, supplementing or replacing

    traditional telemetry protocols like ICCP.


    These ratings are based on real-time measurements of ambient conditions

    and will be used by Transmission Providers for real-time grid operations

    processes, including state estimation and real-time markets.  The clearing

    of real-time ratings may be more frequent than for forecast ratings, but

    the frequency is the prerogative of the Clearinghouse Provider.


    These ratings may be either AARs or DLRs.

    '
paths:
  /rating-proposals/realtime:
    get:
      operationId: getRealTimeProposalStatus
      summary: Real-Time Proposals Status
      description: '

        Retrieves the status of a real-time ratings proposal. The response is

        limited to the requestor''s current proposal.


        Note this status resource is also returned for each `postRealTimeProposal`

        call.  The anticipated use case for this endpoint is to monitoring proposal

        submissions: Clients can use this operation to independently verify that

        their proposal submission process is functioning correctly. This is

        particularly useful for scenarios where a separate monitoring job is set up

        to check the status of proposals.


        Rate limiting is applied per Ratings Provider, meaning requests from

        multiple clients associated with the same provider count towards the same

        quota.  To optimize network traffic and server load, clients should perform

        conditional GET requests with the `If-None-Match` header and the `ETag` from

        a previous response.

        '
      tags:
      - Real-Time
      responses:
        '200':
          description: OK
          content:
            application/vnd.trolie.rating-realtime-proposal-status.v1+json:
              schema:
                $ref: '#/components/schemas/real-time-proposal-status'
              example:
                source:
                  provider: UTILITY-A
                  last-updated: '2023-07-12T15:05:43.044267100-07:00'
                  origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                incomplete-obligation-count: 1
                incomplete-obligations:
                - resource-id: 8badf00d
                  alternate-identifiers:
                  - name: segmentX
                    authority: TO-NERC-ID
                  - name: LINE1 SEG-X
                    authority: RC-NERC-ID
                    mrid: 8badf00d
                invalid-proposal-count: 1
                proposal-validation-errors:
                - message: Submitted continuous rating value of 2000MVA is greater than the upper reasonability limit of 1300MVA
                  resource-id: 8badf00d
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '406':
          $ref: '#/components/responses/406-problem'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - read:realtime-proposals
    post:
      operationId: postRealTimeProposal
      summary: Submit Real-Time Rating Proposal
      description: "\nSome Clearinghouse Providers will support real-time ratings submissions\nthrough this operation.\n\nThe API mechanics are different than forecasts, as there is no implicitly\ncreated time window to modify.  Ratings providers simply `POST` new values\nas they are measured and/or computed.\n\nRules for usage however are similar to forecasts; real-time proposals do not\nhave to contain every resource for which the Ratings Provider is\nresponsible.  Data may be broken into batches across the Rating Provider's\nfootprint.\n\nStatus of the real-time proposals also includes an indication of incomplete\nobligations, much like forecast.  However, the meaning of this is somewhat\ndifferent, as it simply indicates data that is either completely missing, or\nis considered stale by the Clearinghouse Provider, likely due to simply not\nreceiving a value within a reasonable period, such as an hour.\n\nThere are two supported media types for Real-Time Ratings proposals.\n\n* `application/vnd.trolie.rating-realtime-proposal.v1+json` allows the Ratings\n  Provider to combine different limit types, such as `apparent-power` (MVA)\n  and `current` (MW), in a single proposal.\n\n* `application/vnd.trolie.rating-realtime-proposal-slim.v1+json` for\n  proposals that only require a single limit type, e.g., `apparent-power`.\n  Clients *MUST* specify that [limit-type](#tag/limit-type) as a media type\n  parameter. For example,\n\n    ```http\n    POST /ratings-proposals/realtime HTTP/1.1\n    Content-Type: application/vnd.trolie.rating-realtime-proposal-slim.v1+json; limit-type=apparent-power\n    ```\n\n    Note that this format is much more concise but requires significant care\n    in serialization/deserialization.  For details, see [Using Slim Media\n    Types](../example-narratives/using-slim-media-types).\n"
      tags:
      - Real-Time
      requestBody:
        required: true
        content:
          application/vnd.trolie.rating-realtime-proposal.v1+json:
            schema:
              $ref: '#/components/schemas/realtime-proposal'
            example:
              proposal-header:
                source:
                  last-updated: '2025-10-31T15:05:43.044267100-07:00'
                  provider: UTILITY-A
                  origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                default-emergency-durations:
                - name: LTE
                  duration-minutes: 240
                - name: STE
                  duration-minutes: 30
                - name: DAL
                  duration-minutes: 15
                power-system-resources:
                - resource-id: 8badf00d
                  alternate-identifiers:
                  - name: segmentX
                    authority: TO-NERC-ID
                  - name: LINE1 SEG-X
                    authority: RC-NERC-ID
                    mrid: 8badf00d
              ratings:
              - resource-id: 8badf00d
                continuous-operating-limit:
                  mva: 160
                emergency-operating-limits:
                - duration-name: LTE
                  limit:
                    mva: 165
                - duration-name: STE
                  limit:
                    mva: 170
                - duration-name: DAL
                  limit:
                    mva: 170
          application/vnd.trolie.rating-realtime-proposal-slim.v1+json; limit-type=apparent-power:
            schema:
              $ref: '#/components/schemas/realtime-proposal-slim'
            examples:
              No Inputs Provided:
                summary: No Inputs Provided in the Real-Time Proposal
                value:
                  proposal-header:
                    source:
                      last-updated: '2025-10-31T15:05:43.044267100-07:00'
                      provider: UTILITY-A
                      origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                    default-emergency-durations:
                    - name: emergency
                      duration-minutes: 240
                    power-system-resources:
                    - resource-id: 8badf00d
                      alternate-identifiers:
                      - name: segmentX
                        authority: TO-NERC-ID
                      - name: LINE1 SEG-X
                        authority: RC-NERC-ID
                        mrid: 8badf00d
                    - resource-id: f34d3d
                      alternate-identifiers:
                      - name: segmentY
                        authority: TO-NERC-ID
                      - name: LINE2 SEG-Y
                        authority: RC-NERC-ID
                        mrid: 8badf00d
                  ratings:
                  - - 160
                    - 170
                  - - 155
                    - 160
      responses:
        '202':
          description: '

            Accepted. The update was accepted for later processing by the

            Clearinghouse.  Updates to ratings may need to undergo additional

            validation and propagation to other systems.


            Be sure to check the `incomplete-obligation-count` value is zero; if it

            is non-zero, the Clearinghouse Provider does not have a valid and

            non-stale real-time rating for one or more Ratings Obligations.

            Providers should impute recourse ratings as necessary to ensure their

            proposals are complete, i.e., the entire Ratings Obligation is met.

            '
          content:
            application/vnd.trolie.rating-realtime-proposal-status.v1+json:
              schema:
                $ref: '#/components/schemas/real-time-proposal-status'
              example:
                source:
                  provider: UTILITY-A
                  last-updated: '2023-07-12T15:05:43.044267100-07:00'
                  origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                incomplete-obligation-count: 1
                incomplete-obligations:
                - resource-id: 8badf00d
                  alternate-identifiers:
                  - name: segmentX
                    authority: TO-NERC-ID
                  - name: LINE1 SEG-X
                    authority: RC-NERC-ID
                    mrid: 8badf00d
                invalid-proposal-count: 1
                proposal-validation-errors:
                - message: Submitted continuous rating value of 2000MVA is greater than the upper reasonability limit of 1300MVA
                  resource-id: 8badf00d
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '406':
          $ref: '#/components/responses/406-problem'
        '413':
          $ref: '#/components/responses/413-empty'
        '415':
          $ref: '#/components/responses/415-problem'
        '422':
          description: "\nUnprocessable Content. The Real-Time Ratings Proposal may \nnot utilize units that are not permitted by the\nClearinghouse Provider. Check the response for details.\n"
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
              examples:
                invalid-units:
                  summary: Invalid Units Provided in Real-Time Proposal
                  value:
                    type: //trolie.example.com/spec/client-errors/422/invalid-units
                    title: 'Unprocessable Entity: Invalid Units'
                    status: 422
                    detail: The proposal for 8badf00d at 2025-05-07T12:00:00Z specified `mw` so Active Power is assumed, but this exchange requires the power factor `pf` be specified as well.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - write:realtime-proposals
  /limits/realtime-snapshot:
    get:
      operationId: getRealTimeLimits
      description: '

        Obtain the System Operating Limits in-use by the Transmission Provider.


        Clients SHOULD perform Conditional `GET` using the `If-None-Match` header

        and the `ETag` of a previous `GET` response to poll this endpoint. Rate

        limiting is done on a per Ratings Provider basis, so requests from

        independent clients used by the same provider count against the same quota.

        '
      summary: Limits Real Time Snapshot
      tags:
      - Real-Time
      parameters:
      - $ref: '#/components/parameters/query-filter'
      - $ref: '#/components/parameters/resource-id-filter'
      responses:
        '200':
          description: The System Operating Limits snapshot is returned.
          content:
            application/vnd.trolie.realtime-limits-snapshot.v1+json:
              schema:
                $ref: '#/components/schemas/realtime-limits-snapshot'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 15
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                limits:
                - resource-id: 8badf00d
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                  - duration-name: STE
                    limit:
                      mva: 170
                  - duration-name: DAL
                    limit:
                      mva: 180
            application/vnd.trolie.realtime-limits-snapshot.v1+json; include-psr-header=false:
              schema:
                $ref: '#/components/schemas/realtime-limits-snapshot-elide-psr'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 15
                limits:
                - resource-id: 8badf00d
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                  - duration-name: STE
                    limit:
                      mva: 170
                  - duration-name: DAL
                    limit:
                      mva: 180
            application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json:
              schema:
                $ref: '#/components/schemas/realtime-limits-detailed-snapshot'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL-RC
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 5
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                limits:
                - resource-id: 8badf00d
                  additional-data:
                    vendor-specific-data: {}
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                  - duration-name: STE
                    limit:
                      mva: 170
                  - duration-name: DAL
                    limit:
                      mva: 175
                provenance:
                - resource-id: 8badf00d
                  proposals-considered:
                  - resource-id: 8badf00d-UTILITY-A-SEG-id
                    source:
                      last-updated: '2025-07-12T14:10:12-07:00'
                      provider: UTILITY-A
                      origin-id: 8badf00d-UTILITY-A-correlation-id
                    continuous-operating-limit:
                      mva: 150
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                  - resource-id: 8badf00d-UTILITY-B-SEG-id
                    source:
                      last-updated: '2025-07-12T14:10:12-07:00'
                      provider: UTILITY-B
                      origin-id: 8badf00d-UTILITY-B-correlation-id
                    continuous-operating-limit:
                      mva: 150
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 166
                    - duration-name: STE
                      limit:
                        mva: 171
                    - duration-name: DAL
                      limit:
                        mva: 175
                  temporary-aar-exceptions:
                  - id: 284928-2025-07-12T16:00:00-07:00
                    source:
                      origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67
                      provider: UTILITY-A
                      last-updated: '2025-07-12T16:00:00-07:00'
                    resource:
                      resource-id: 8badf00d
                    start-time: '2025-07-12T16:00:00-07:00'
                    end-time: '2025-08-01T00:00:00-07:00'
                    continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                  overrides:
                  - continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    reason: TOI 20250701-01
                    start-time: '2025-07-01T00:00:00-07:00'
            application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json; include-psr-header=false:
              schema:
                $ref: '#/components/schemas/realtime-limits-detailed-snapshot-elide-psr'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL-RC
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 5
                limits:
                - resource-id: 8badf00d
                  additional-data:
                    vendor-specific-data: {}
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                  - duration-name: STE
                    limit:
                      mva: 170
                  - duration-name: DAL
                    limit:
                      mva: 175
                provenance:
                - resource-id: 8badf00d
                  proposals-considered:
                  - resource-id: 8badf00d-UTILITY-A-SEG-id
                    source:
                      last-updated: '2025-07-12T14:10:12-07:00'
                      provider: UTILITY-A
                      origin-id: 8badf00d-UTILITY-A-correlation-id
                    continuous-operating-limit:
                      mva: 150
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                  - resource-id: 8badf00d-UTILITY-B-SEG-id
                    source:
                      last-updated: '2025-07-12T14:10:12-07:00'
                      provider: UTILITY-B
                      origin-id: 8badf00d-UTILITY-B-correlation-id
                    continuous-operating-limit:
                      mva: 150
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 166
                    - duration-name: STE
                      limit:
                        mva: 171
                    - duration-name: DAL
                      limit:
                        mva: 175
                  temporary-aar-exceptions:
                  - id: 284928-2025-07-12T16:00:00-07:00
                    source:
                      origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67
                      provider: UTILITY-A
                      last-updated: '2025-07-12T16:00:00-07:00'
                    resource:
                      resource-id: 8badf00d
                    start-time: '2025-07-12T16:00:00-07:00'
                    end-time: '2025-08-01T00:00:00-07:00'
                    continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                  overrides:
                  - continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    reason: TOI 20250701-01
                    start-time: '2025-07-01T00:00:00-07:00'
            application/vnd.trolie.realtime-limits-snapshot-slim.v1+json; limit-type=apparent-power:
              schema:
                $ref: '#/components/schemas/realtime-limits-snapshot-slim'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: emergency
                    duration-minutes: 240
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                  - resource-id: f34d3d
                    alternate-identifiers:
                    - name: segmentY
                      authority: TO-NERC-ID
                    - name: LINE2 SEG-Y
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                limits:
                - - 160
                  - 170
                - - 155
                  - 160
            application/vnd.trolie.realtime-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true:
              schema:
                $ref: '#/components/schemas/realtime-limits-snapshot-slim-inputs-used'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: emergency
                    duration-minutes: 240
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                  - resource-id: f34d3d
                    alternate-identifiers:
                    - name: segmentY
                      authority: TO-NERC-ID
                    - name: LINE2 SEG-Y
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                limits:
                - - 160
                  - 170
                - - 155
                  - 160
                inputs-used:
                - name: dry bulb temperature (Fahrenheit)
                  unit: degF
                  values:
                  - 50
                  - 51
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '404':
          $ref: '#/components/responses/404-empty'
        '406':
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
          description: Not Acceptable (Content negotiation failed)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
              examples:
                Compression Required:
                  summary: Only compressed responses are supported
                  value:
                    type: //trolie.example.com/spec/client-errors/406/compression-required
                    title: 'Not Acceptable: Accept-Encoding Required'
                    status: 406
                    detail: 'This resource must be compressed with one of the following algorithms: gzip, deflate, br.'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - read:operating-snapshot
  /limits/regional/realtime-snapshot:
    get:
      operationId: getRegionalRealTimeLimits
      description: "\nSimilar to [getRealTimeLimits](#tag/Real-Time/operation/getRealTimeLimits), \nexcept that it specifically returns only the latest **regionally** limiting ratings\n([RLRs](https://trolie.energy/concepts#regionally-limiting-rating))\nused by the Transmission Provider.  \n\nThis is explicitly designed to be used when reconciling real-time ratings between Transmission Providers\nin order to generate globally limiting ratings ([GLRs](https://trolie.energy/concepts#globally-limiting-rating)) \nfor general use.  See the article on \n[RC-to-RC Reconciliation](https://trolie.energy/articles/RC-to-RC-reconciliation.html) for more details.\n\nOutside of this use case, most users should use\n[getRealTimeLimits](#tag/Real-Time/operation/getRealTimeLimits) to get globally\nlimiting ratings.  \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 quota.      \n"
      summary: Regional Limits Real Time Snapshot
      tags:
      - Real-Time
      parameters:
      - $ref: '#/components/parameters/query-filter'
      - $ref: '#/components/parameters/resource-id-filter'
      responses:
        '200':
          description: The System Operating Limits snapshot is returned.
          content:
            application/vnd.trolie.realtime-limits-snapshot.v1+json:
              schema:
                $ref: '#/components/schemas/realtime-limits-snapshot'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 15
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                limits:
                - resource-id: 8badf00d
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                  - duration-name: STE
                    limit:
                      mva: 170
                  - duration-name: DAL
                    limit:
                      mva: 180
            application/vnd.trolie.realtime-limits-snapshot.v1+json; include-psr-header=false:
              schema:
                $ref: '#/components/schemas/realtime-limits-snapshot-elide-psr'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 15
                limits:
                - resource-id: 8badf00d
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                  - duration-name: STE
                    limit:
                      mva: 170
                  - duration-name: DAL
                    limit:
                      mva: 180
            application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json:
              schema:
                $ref: '#/components/schemas/realtime-limits-detailed-snapshot'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL-RC
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 5
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                limits:
                - resource-id: 8badf00d
                  additional-data:
                    vendor-specific-data: {}
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                  - duration-name: STE
                    limit:
                      mva: 170
                  - duration-name: DAL
                    limit:
                      mva: 175
                provenance:
                - resource-id: 8badf00d
                  proposals-considered:
                  - resource-id: 8badf00d-UTILITY-A-SEG-id
                    source:
                      last-updated: '2025-07-12T14:10:12-07:00'
                      provider: UTILITY-A
                      origin-id: 8badf00d-UTILITY-A-correlation-id
                    continuous-operating-limit:
                      mva: 150
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                  - resource-id: 8badf00d-UTILITY-B-SEG-id
                    source:
                      last-updated: '2025-07-12T14:10:12-07:00'
                      provider: UTILITY-B
                      origin-id: 8badf00d-UTILITY-B-correlation-id
                    continuous-operating-limit:
                      mva: 150
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 166
                    - duration-name: STE
                      limit:
                        mva: 171
                    - duration-name: DAL
                      limit:
                        mva: 175
                  temporary-aar-exceptions:
                  - id: 284928-2025-07-12T16:00:00-07:00
                    source:
                      origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67
                      provider: UTILITY-A
                      last-updated: '2025-07-12T16:00:00-07:00'
                    resource:
                      resource-id: 8badf00d
                    start-time: '2025-07-12T16:00:00-07:00'
                    end-time: '2025-08-01T00:00:00-07:00'
                    continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                  overrides:
                  - continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    reason: TOI 20250701-01
                    start-time: '2025-07-01T00:00:00-07:00'
            application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json; include-psr-header=false:
              schema:
                $ref: '#/components/schemas/realtime-limits-detailed-snapshot-elide-psr'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL-RC
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 5
                limits:
                - resource-id: 8badf00d
                  additional-data:
                    vendor-specific-data: {}
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                  - duration-name: STE
                    limit:
                      mva: 170
                  - duration-name: DAL
                    limit:
                      mva: 175
                provenance:
                - resource-id: 8badf00d
                  proposals-considered:
                  - resource-id: 8badf00d-UTILITY-A-SEG-id
                    source:
                      last-updated: '2025-07-12T14:10:12-07:00'
                      provider: UTILITY-A
                      origin-id: 8badf00d-UTILITY-A-correlation-id
                    continuous-operating-limit:
                      mva: 150
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                  - resource-id: 8badf00d-UTILITY-B-SEG-id
                    source:
                      last-updated: '2025-07-12T14:10:12-07:00'
                      provider: UTILITY-B
                      origin-id: 8badf00d-UTILITY-B-correlation-id
                    continuous-operating-limit:
                      mva: 150
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 166
                    - duration-name: STE
                      limit:
                        mva: 171
                    - duration-name: DAL
                      limit:
                        mva: 175
                  temporary-aar-exceptions:
                  - id: 284928-2025-07-12T16:00:00-07:00
                    source:
                      origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67
                      provider: UTILITY-A
                      last-updated: '2025-07-12T16:00:00-07:00'
                    resource:
                      resource-id: 8badf00d
                    start-time: '2025-07-12T16:00:00-07:00'
                    end-time: '2025-08-01T00:00:00-07:00'
                    continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                  overrides:
                  - continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    reason: TOI 20250701-01
                    start-time: '2025-07-01T00:00:00-07:00'
            application/vnd.trolie.realtime-limits-snapshot-slim.v1+json; limit-type=apparent-power:
              schema:
                $ref: '#/components/schemas/realtime-limits-snapshot-slim'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: emergency
                    duration-minutes: 240
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                  - resource-id: f34d3d
                    alternate-identifiers:
                    - name: segmentY
                      authority: TO-NERC-ID
                    - name: LINE2 SEG-Y
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                limits:
                - - 160
                  - 170
                - - 155
                  - 160
            application/vnd.trolie.realtime-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true:
              schema:
                $ref: '#/components/schemas/realtime-limits-snapshot-slim-inputs-used'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T15:05:43.044267100-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: emergency
                    duration-minutes: 240
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                  - resource-id: f34d3d
                    alternate-identifiers:
                    - name: segmentY
                      authority: TO-NERC-ID
                    - name: LINE2 SEG-Y
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                limits:
                - - 160
                  - 170
                - - 155
                  - 160
                inputs-used:
                - name: dry bulb temperature (Fahrenheit)
                  unit: degF
                  values:
                  - 50
                  - 51
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '404':
          $ref: '#/components/responses/404-empty'
        '406':
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
          description: Not Acceptable (Content negotiation failed)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
              examples:
                Compression Required:
                  summary: Only compressed responses are supported
                  value:
                    type: //trolie.example.com/spec/client-errors/406/compression-required
                    title: 'Not Acceptable: Accept-Encoding Required'
                    status: 406
                    detail: 'This resource must be compressed with one of the following algorithms: gzip, deflate, br.'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - read:operating-snapshot
components:
  schemas:
    realtime-proposal-slim:
      type: object
      description: Used to propose real-time ratings for a set of resources.
      properties:
        proposal-header:
          $ref: '#/components/schemas/real-time-proposal-slim-header'
        ratings:
          type: array
          minItems: 1
          maxItems: 50000
          description: Real-Time Ratings Proposals
          items:
            $ref: '#/components/schemas/slim'
        inputs-used:
          description: '

            Optional list of quantities used as input to the ratings determination.

            The particular information exchange determines which values may be expected

            as well as the conventions used to represent those values. This property

            is included to prescribe a way to include these inputs.

            '
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: object
            properties:
              name:
                type: string
                format: free-text
                maxLength: 50
              values:
                type: array
                minItems: 1
                maxItems: 50000
                description: 'Since this is expected to be used for wind speed or temperature,

                  we expect an array of numbers for each resource. An empty array

                  is used to indicate that the inputs are not available for a

                  particular resource. This could occur if the inputs were not provided

                  by the Ratings Provider or if a recourse rating was utilized.

                  '
                items:
                  $ref: '#/components/schemas/resource-forecast-inputs'
              unit:
                $ref: '#/components/schemas/unit'
            required:
            - name
            - values
            - unit
      required:
      - proposal-header
      - ratings
    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
    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
    real-time-provenance:
      type: object
      properties:
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        resource-id:
          $ref: '#/components/schemas/resource-id'
        current-source:
          $ref: '#/components/schemas/quality-class-current-source'
        inputs-used:
          description: '

            Optional list of quantities used as input to the ratings determination.

            The particular information exchange determines which values may be expected

            as well as the conventions used to represent those values. This property

            is included to prescribe a way to include these inputs.

            '
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/input'
        source:
          $ref: '#/components/schemas/data-provenance'
      required:
      - resource-id
      - continuous-operating-limit
      - emergency-operating-limits
      - source
      additionalProperties: false
    real-time-proposal-slim-header:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        default-emergency-durations:
          $ref: '#/components/schemas/emergency-durations'
        default-limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        power-system-resources:
          $ref: '#/components/schemas/named-power-system-resources'
        current-source:
          $ref: '#/components/schemas/quality-class-current-source'
      additionalProperties: false
      required:
      - source
      - default-emergency-durations
      - power-system-resources
      description: '

        Populated by the Ratings Provider in a request to submit real-time ratings.

        The Clearinghouse implementation should record this information,

        and the detail limits snapshot should should reflect the

        appropriate metadata from the

        Clearinghouse Provider''s perspective.

        '
    named-power-system-resources:
      type: array
      minItems: 1
      maxItems: 50000
      description: Collection of power system resource names
      items:
        $ref: '#/components/schemas/names'
    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
    realtime-limits-snapshot-slim:
      type: object
      description: A slim snapshot of the realtime limits for a monitoring set.
      properties:
        snapshot-header:
          $ref: '#/components/schemas/real-time-snapshot-header'
        limits:
          type: array
          minItems: 1
          maxItems: 50000
          description: Real-time limits
          items:
            $ref: '#/components/schemas/slim'
      required:
      - snapshot-header
      - limits
    realtime-limits-snapshot:
      type: object
      description: A snapshot of the realtime limits for a monitoring set.
      properties:
        snapshot-header:
          $ref: '#/components/schemas/real-time-snapshot-header'
        limits:
          type: array
          minItems: 1
          maxItems: 50000
          description: Real-time limits
          items:
            $ref: '#/components/schemas/realtime-snapshot'
      required:
      - snapshot-header
      - limits
    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
    real-time-snapshot-header-elide-psr:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        default-emergency-durations:
          $ref: '#/components/schemas/emergency-durations'
        default-limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
      additionalProperties: false
      required:
      - source
      - default-emergency-durations
      description: Details about the snapshot provided by the Clearinghouse provider.
    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
    real-time-proposal:
      type: object
      properties:
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        resource-id:
          $ref: '#/components/schemas/resource-id'
        current-source:
          $ref: '#/components/schemas/quality-class-current-source'
        inputs-used:
          description: '

            Optional list of quantities used as input to the ratings determination.

            The particular information exchange determines which values may be expected

            as well as the conventions used to represent those values. This property

            is included to prescribe a way to include these inputs.

            '
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/input'
      required:
      - resource-id
      - continuous-operating-limit
      - emergency-operating-limits
      additionalProperties: false
    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
    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
    limiting-analysis:
      type: string
      description: '

        Indicates how a operating limit was determined. This is used to

        provide context for the ratings proposals and limits snapshots. When defined

        in the header, this is assumed to apply to any limit that does not specify its

        own limiting analysis. When defined for a period, it applies to the

        `continuous-operating-limit` as well as the associated

        `emergency-operating-limits`, unless the `emergency-operating-limits` specify

        their own limiting analysis.


        THERMAL_RATING - The limit was determined by the thermal rating of underlying

        equipment.


        TRANSIENT_SECURITY_ASSESSMENT - Studies of the system''s transient stability

        determined the limit.


        VOLTAGE_SECURITY_ASSESSMENT - Studies of the system''s voltage stability

        determined the limit.


        SMALL_SIGNAL_STABILITY_ASSESSMENT - Small-signal stability studies determined

        the limit.


        SYSTEM_SPECIFIC - This could account for limits imposed by specific system

        characteristics, such as the presence of sensitive loads, the need to maintain

        specific power flows, or other reliability/volatility reasons. These include

        limits defined by Special Protection Schemes and Remedial Action Schemes.


        ENVIRONMENTAL_CONDITIONS - The limit was determined by exceptional

        environmental conditions such as wildfire risk, ice loading, excessive

        wind/galloping, or other factors.


        CONTRACT_CAPACITY - The available facility transfer capacity is limited

        by contractual obligations.


        REGULATORY_REQUIREMENTS - The limit is imposed by regulatory requirements.


        OTHER - The limit was determined by some other means not anticipated in this

        standard.

        '
      enum:
      - THERMAL_RATING
      - TRANSIENT_SECURITY_ASSESSMENT
      - VOLTAGE_SECURITY_ASSESSMENT
      - SMALL_SIGNAL_STABILITY_ASSESSMENT
      - SYSTEM_SPECIFIC
      - ENVIRONMENTAL_CONDITIONS
      - REGULATORY_REQUIREMENTS
      - CONTRACT_CAPACITY
      - OTHER
    name-type:
      description: Type of the name being referenced.  Corresponds to the IEC CIM `NameType` concept.
      type: string
      maxLength: 20
      pattern: ^[A-Za-z0-9\-]{3,20}$
      example: EMSID
    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
    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'
    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
    realtime-limits-detailed-snapshot:
      type: object
      description: A snapshot of the realtime limits for a monitoring set.
      properties:
        snapshot-header:
          $ref: '#/components/schemas/real-time-snapshot-header'
        limits:
          type: array
          minItems: 1
          maxItems: 50000
          description: Real-time limits including provenance.
          items:
            $ref: '#/components/schemas/realtime-snapshot-detailed'
        provenance:
          type: array
          minItems: 1
          maxItems: 50000
          description: Set of forecast limits
          items:
            type: object
            properties:
              resource-id:
                $ref: '#/components/schemas/resource-id'
              proposals-considered:
                type: array
                maxItems: 10
                items:
                  $ref: '#/components/schemas/real-time-provenance'
              temporary-aar-exceptions:
                type: array
                maxItems: 10
                items:
                  $ref: '#/components/schemas/temporary-aar-exception-provenance'
              overrides:
                type: array
                maxItems: 10
                items:
                  $ref: '#/components/schemas/operator-override-limit-provenance'
            required:
            - resource-id
            - proposals-considered
      required:
      - snapshot-header
      - limits
      - provenance
    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
    realtime-limits-detailed-snapshot-elide-psr:
      type: object
      description: A snapshot of the realtime limits for a monitoring set.
      properties:
        snapshot-header:
          $ref: '#/components/schemas/real-time-snapshot-header-elide-psr'
        limits:
          type: array
          minItems: 1
          maxItems: 50000
          description: Real-time limits including provenance.
          items:
            $ref: '#/components/schemas/realtime-snapshot-detailed'
        provenance:
          type: array
          minItems: 1
          maxItems: 50000
          description: Set of forecast limits
          items:
            type: object
            properties:
              resource-id:
                $ref: '#/components/schemas/resource-id'
              proposals-considered:
                type: array
                maxItems: 10
                items:
                  $ref: '#/components/schemas/real-time-provenance'
              temporary-aar-exceptions:
                type: array
                maxItems: 10
                items:
                  $ref: '#/components/schemas/temporary-aar-exception-provenance'
              overrides:
                type: array
                maxItems: 10
                items:
                  $ref: '#/components/schemas/operator-override-limit-provenance'
            required:
            - resource-id
            - proposals-considered
      required:
      - snapshot-header
      - limits
      - provenance
    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
    resource-forecast-inputs:
      type: array
      maxItems: 300
      items:
        type: number
        format: float
    realtime-snapshot:
      type: object
      properties:
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        resource-id:
          $ref: '#/components/schemas/resource-id'
      required:
      - resource-id
      - continuous-operating-limit
      - emergency-operating-limits
      additionalProperties: false
    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
    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
    real-time-proposal-header:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        default-emergency-durations:
          $ref: '#/components/schemas/emergency-durations'
        default-limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        power-system-resources:
          $ref: '#/components/schemas/named-power-system-resources'
      additionalProperties: false
      required:
      - source
      - default-emergency-durations
      - power-system-resources
      description: '

        Populated by the Ratings Provider in a request to submit real-time ratings.

        The Clearinghouse implementation should record this information,

        and the detail limits snapshot should should reflect the

        appropriate metadata from the

        Clearinghouse Provider''s perspective.

        '
    real-time-proposal-status:
      type: object
      description: 'Status of the rating provider''s real-time obligations.

        Includes any validation errors encountered while processing proposals.

        '
      properties:
        incomplete-obligation-count:
          description: '

            The number of facilities for this provider whose Ratings Obligation has

            not been met in this forecast window. This number may be larger than the

            size of `incomplete-obligations`, since the latter has a pre-defined

            upper bound for performance and application security reasons.


            The Ratings Provider should check that this value is zero when they

            believe they have completed their submission process.

            '
          type: integer
          format: uint16
          minimum: 0
          maximum: 50000
        incomplete-obligations:
          type: array
          description: '

            Indicates which Ratings Obligations have not been fulfilled. The size of

            this set is bounded and may be less than the actual count of unfulfilled

            Obligations indicated in `incomplete-obligation-count`. The intended use

            case for this set is debugging and troubleshooting.

            '
          minItems: 0
          maxItems: 50000
          items:
            $ref: '#/components/schemas/names'
        invalid-proposal-count:
          description: '

            The number of `resource-forecast-proposal` objects that have been

            determined to be *invalid* during this Forecast Window for the current

            Ratings Provider. This count is provided for troubleshooting,

            establishing trends, and triggering alerts.

            '
          type: integer
          format: uint16
          minimum: 0
          maximum: 50000
        proposal-validation-errors:
          type: array
          description: The most recent validation errors
          minItems: 0
          maxItems: 50
          items:
            type: object
            additionalProperties: false
            description: 'Validation errors.


              Note to implementors, the property `resource-id` intentionally is not `names`

              as was used in `incomplete-obligations` to mitigate the

              possibility of information disclosure when a Ratings Provider

              submits a proposal for a valid resource that they are not

              permitted to write to. It should be the same `resource-id` that

              the client submitted.

              '
            properties:
              message:
                type: string
                pattern: ^(.){1,500}$
                maxLength: 500
                example: The `resource-forecast-proposal` for `8badf00d` is incomplete.
              resource-id:
                $ref: '#/components/schemas/resource-id'
        source:
          $ref: '#/components/schemas/data-provenance'
      required:
      - source
      - incomplete-obligation-count
      - incomplete-obligations
      - invalid-proposal-count
      - proposal-validation-errors
    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'
    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
    real-time-snapshot-header:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        default-emergency-durations:
          $ref: '#/components/schemas/emergency-durations'
        default-limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        power-system-resources:
          $ref: '#/components/schemas/named-power-system-resources'
      additionalProperties: false
      required:
      - source
      - default-emergency-durations
      - power-system-resources
      description: Details about the snapshot provided by the Clearinghouse provider.
    realtime-snapshot-detailed:
      type: object
      properties:
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        resource-id:
          $ref: '#/components/schemas/resource-id'
        additional-data:
          type: object
          description: 'Implementors may use this object to provide freeform extensions with

            additional traceability / provenance data to be included with the limit.

            Schema of this object is out of scope of the TROLIE specification.

            '
      required:
      - resource-id
      - continuous-operating-limit
      - emergency-operating-limits
      additionalProperties: false
    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
    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
    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
    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
    realtime-proposal:
      type: object
      properties:
        proposal-header:
          $ref: '#/components/schemas/real-time-proposal-header'
        ratings:
          type: array
          minItems: 1
          maxItems: 50000
          description: Real-Time Ratings Proposals
          items:
            $ref: '#/components/schemas/real-time-proposal'
        inputs-used:
          description: '

            Optional list of quantities used as input to the ratings determination.

            The particular information exchange determines which values may be expected

            as well as the conventions used to represent those values. This property

            is included to prescribe a way to include these inputs.

            '
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: object
            properties:
              name:
                type: string
                format: free-text
                maxLength: 50
              values:
                type: array
                minItems: 1
                maxItems: 50000
                description: 'Since this is expected to be used for wind speed or temperature, we expect an array of numbers for each resource. An empty array is used to indicate that the inputs are not available for a particular resource. This could occur if the inputs were not provided by the Ratings Provider or if a recourse rating was utilized.

                  '
                items:
                  $ref: '#/components/schemas/resource-forecast-inputs'
              unit:
                type: string
                description: 'Since we are not specifying which inputs shall be

                  provided, we cannot specify a definitive list of units, but

                  implementors are encouraged to use UnitSymbol from CIM when

                  appropriate: The CIM may not include appropriate units for

                  all inputs, e.g., wind speed, degrees Fahrenheit, etc.

                  '
                format: unit
                maxLength: 50
            required:
            - name
            - values
            - unit
      required:
      - proposal-header
      - ratings
    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
    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
    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
    realtime-limits-snapshot-slim-inputs-used:
      type: object
      description: 'A slim snapshot of the realtime limits for a monitoring set, including the

        inputs used to determine the continuous limits.

        '
      properties:
        snapshot-header:
          $ref: '#/components/schemas/real-time-snapshot-header'
        limits:
          type: array
          minItems: 1
          maxItems: 50000
          description: Real-time limits
          items:
            $ref: '#/components/schemas/slim'
        inputs-used:
          description: '

            Optional list of quantities used as input to the ratings determination.

            The particular information exchange determines which values may be expected

            as well as the conventions used to represent those values. This property

            is included to prescribe a way to include these inputs.

            '
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: object
            properties:
              name:
                type: string
                format: free-text
                maxLength: 50
              values:
                type: array
                minItems: 1
                maxItems: 50000
                description: 'This is aligned with the `limits` property such that each resource

                  entry is in the same position here.


                  A null is used to indicate that the input is not available for a

                  particular resource. This could occur if the inputs were not provided

                  by the Ratings Provider or if a recourse rating was utilized.

                  '
                items:
                  type:
                  - number
                  - 'null'
                  format: float
              unit:
                $ref: '#/components/schemas/unit'
            required:
            - name
            - values
            - unit
      required:
      - snapshot-header
      - limits
      - inputs-used
    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
    slim:
      type: array
      title: Slim Period
      minItems: 1
      maxItems: 11
      items:
        type: number
    realtime-limits-snapshot-elide-psr:
      type: object
      description: A snapshot of the realtime limits for a monitoring set.
      properties:
        snapshot-header:
          $ref: '#/components/schemas/real-time-snapshot-header-elide-psr'
        limits:
          type: array
          minItems: 1
          maxItems: 50000
          description: Real-time limits
          items:
            $ref: '#/components/schemas/realtime-snapshot'
      required:
      - snapshot-header
      - limits
  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'
    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'
    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'
    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'
    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'
    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'
    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'
  headers:
    ETag:
      description: 'An opaque, unique identifier--typically a hash value--for a specific version of a resource. The modeled resource state is what is versioned, not the content of any particular representation. The server MUST use a strong validator so that the same ETag is returned regardless of the media type of the representation.

        '
      schema:
        type: string
        format: hash
        maxLength: 256
        additionalProperties: false
    X-Rate-Limit-Limit:
      description: The number of allowed requests in the current period
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 1000
    Retry-After:
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 60
        example: 60
        description: The seconds to delay after the response is received.
    X-Rate-Limit-Reset:
      description: The number of seconds left 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
  parameters:
    query-filter:
      name: monitoring-set
      description: '

        Only return ratings or limits for facilities of the associated

        `monitoring-set`. The identifier for a `monitoring-set` is pre-coordinated,

        but using the NERC id of the associated Ratings Provider for the default

        monitoring set is recommended.

        '
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/local'
      examples:
        name:
          summary: A pre-coordinated name that nominates a `monitoring-set` for a specific entity or purpose.
          value: X-AMPL
        mrid:
          summary: A pre-coordinated id that nominates a `monitoring-set`.
          value: urn:uuid:12345678-1234-5678-1234-123456789012
    resource-id-filter:
      name: resource-id
      description: 'Only return limits for this power system resource

        '
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/resource-id'
      examples:
        circuit-id:
          summary: A typical AC line identifier
          value: '86753_1'
        mrid:
          summary: A CIM mrid for a power system resource
          value: urn:uuid:123e4567-e89b-12d3-a456-426614174000
  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