openapi: 3.2.0
info:
  title: Transmission Ratings and Operating Limits Information Exchange (TROLIE) Seasonal 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: Seasonal
  description: 'Seasonal ratings are static ratings associated with extended durations,

    typically months. These are typically used in both planning and

    operations.


    Power system resources that are exempt from providing AARs generally

    operate at a seasonal rating. Even for resources using dynamic ratings, a

    seasonal rating is still necessary. This acts as a recourse when a dynamic

    rating is unavailable.  For example, a dynamic rating

    might be unavailable during communication outages or for forecasts beyond

    the ten-day period required by FERC Order 881.

    '
paths:
  /seasonal-ratings/snapshot:
    get:
      operationId: getSeasonalRatingsSnapshot
      description: Retrieve the nominal and seasonal ratings.
      summary: Get Seasonal Ratings
      tags:
      - Seasonal
      parameters:
      - $ref: '#/components/parameters/query-filter'
      - $ref: '#/components/parameters/resource-id-filter'
      responses:
        '200':
          description: OK
          content:
            application/vnd.trolie.seasonal-rating-snapshot.v1+json:
              schema:
                $ref: '#/components/schemas/seasonal-ratings-snapshot'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T16:00:00-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 15
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                ratings:
                - resource-id: segmentX
                  periods:
                  - period-start: '2024-04-01T01:00:00Z'
                    period-end: '2024-07-01T01:00:00Z'
                    season-name: spring
                    continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
            application/vnd.trolie.seasonal-rating-snapshot-detailed.v1+json:
              schema:
                $ref: '#/components/schemas/seasonal-ratings-snapshot-detailed'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T16:00:00-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 15
                  power-system-resources:
                  - resource-id: 8badf00d
                    alternate-identifiers:
                    - name: segmentX
                      authority: TO-NERC-ID
                    - name: LINE1 SEG-X
                      authority: RC-NERC-ID
                      mrid: 8badf00d
                ratings:
                - resource-id: LINE1
                  periods:
                  - period-start: '2024-04-01T01:00:00Z'
                    period-end: '2024-07-01T01:00:00Z'
                    season-name: spring
                    continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                    proposals-considered:
                    - resource-id: 8badf00d
                      period-start: '2024-04-01T01:00:00Z'
                      period-end: '2024-07-01T01:00:00Z'
                      source:
                        provider: X-AMPL
                        last-updated: '2023-07-12T16:00:00-07:00'
                        origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                      season-name: spring
                      continuous-operating-limit:
                        mva: 160
                      emergency-operating-limits:
                      - duration-name: LTE
                        limit:
                          mva: 165
                      - duration-name: STE
                        limit:
                          mva: 170
                      - duration-name: DAL
                        limit:
                          mva: 180
            application/vnd.trolie.seasonal-rating-snapshot-detailed.v1+json; include-psr-header=false:
              schema:
                $ref: '#/components/schemas/seasonal-ratings-snapshot-detailed-elide-psr'
              example:
                snapshot-header:
                  source:
                    provider: X-AMPL
                    last-updated: '2023-07-12T16:00:00-07:00'
                    origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                  default-emergency-durations:
                  - name: LTE
                    duration-minutes: 240
                  - name: STE
                    duration-minutes: 30
                  - name: DAL
                    duration-minutes: 15
                ratings:
                - resource-id: LINE1
                  periods:
                  - period-start: '2024-04-01T01:00:00Z'
                    period-end: '2024-07-01T01:00:00Z'
                    season-name: spring
                    continuous-operating-limit:
                      mva: 160
                    emergency-operating-limits:
                    - duration-name: LTE
                      limit:
                        mva: 165
                    - duration-name: STE
                      limit:
                        mva: 170
                    - duration-name: DAL
                      limit:
                        mva: 180
                    proposals-considered:
                    - resource-id: 8badf00d
                      period-start: '2024-04-01T01:00:00Z'
                      period-end: '2024-07-01T01:00:00Z'
                      source:
                        provider: X-AMPL
                        last-updated: '2023-07-12T16:00:00-07:00'
                        origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
                      season-name: spring
                      continuous-operating-limit:
                        mva: 160
                      emergency-operating-limits:
                      - duration-name: LTE
                        limit:
                          mva: 165
                      - duration-name: STE
                        limit:
                          mva: 170
                      - duration-name: DAL
                        limit:
                          mva: 180
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '404':
          $ref: '#/components/responses/404-empty'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - read:operating-snapshot
  /rating-proposals/seasonal:
    get:
      operationId: getSeasonalRatingProposalStatus
      summary: Obtain seasonal rating proposal status
      description: '

        Used to obtain the status of the Seasonal Ratings proposal. The response is

        implicitly restricted to the requesting Ratings Provider''s obligation.

        Accordingly, the caller can use this endpoint to check the state of their

        proposal submission.


        Note that the same status object is returned for each

        `patchSeasonalRatingsProposal`, so this endpoint may seem redundant.

        However, an anticipated use case for this `GET` endpoint is to support

        supervisor processes that are setup by the client to independently ensure

        the provider''s process for rating submission if functioning properly. For

        example, the Rating Provider might have one program responsible for

        producing and submitting Seasonal Ratings via

        `patchSeasonalRatingsProposal`, while having a separate monitoring job that

        checks this endpoint regularly.


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

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

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

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

        '
      tags:
      - Seasonal
      responses:
        '200':
          description: OK
          content:
            application/vnd.trolie.seasonal-ratings-proposal-status.v1+json:
              schema:
                $ref: '#/components/schemas/seasonal-ratings-proposal-status'
              examples:
                complete:
                  summary: Status reflects no errors or outstanding obligations
                  value:
                    source:
                      provider: UTILITY-A
                      last-updated: '2023-07-12T15:05:43.044267100-07:00'
                      origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                    incomplete-obligation-count: 0
                    incomplete-obligations: []
                    invalid-proposal-count: 0
                    proposal-validation-errors: []
                incomplete:
                  summary: Status reflects outstanding obligations
                  value:
                    source:
                      provider: UTILITY-A
                      last-updated: '2023-07-12T15:05:43.044267100-07:00'
                      origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                    incomplete-obligation-count: 1
                    incomplete-obligations:
                    - resource-id: 8badf00d
                      obligation-period-begins: '2024-01-01T00:00:00-05:00'
                      obligation-period-ends: '2024-01-01T00:00:00-05:00'
                      periods:
                      - season-name: WINTER
                        begins: '2024-01-01T00:00:00-05:00'
                    invalid-proposal-count: 0
                    proposal-validation-errors: []
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '406':
          $ref: '#/components/responses/406-problem'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - read:seasonal-proposals
    patch:
      operationId: patchSeasonalRatingsProposal
      summary: Submit a Seasonal Ratings proposal
      description: '

        This operation allows the Ratings Provider to provide a partial or complete

        updates of their Seasonal Ratings that will be used by the Clearinghouse

        Provider to determine the Seasonal Ratings Schedule.

        '
      tags:
      - Seasonal
      responses:
        '202':
          description: 'The update was accepted for later processing. Updates to ratings may

            need to undergo additional validation and propagation to other systems.

            '
          content:
            application/vnd.trolie.seasonal-ratings-proposal-status.v1+json:
              schema:
                $ref: '#/components/schemas/seasonal-ratings-proposal-status'
              examples:
                complete:
                  summary: Status reflects no errors or outstanding obligations
                  value:
                    source:
                      provider: UTILITY-A
                      last-updated: '2023-07-12T15:05:43.044267100-07:00'
                      origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                    incomplete-obligation-count: 0
                    incomplete-obligations: []
                    invalid-proposal-count: 0
                    proposal-validation-errors: []
                incomplete:
                  summary: Status reflects outstanding obligations
                  value:
                    source:
                      provider: UTILITY-A
                      last-updated: '2023-07-12T15:05:43.044267100-07:00'
                      origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                    incomplete-obligation-count: 1
                    incomplete-obligations:
                    - resource-id: 8badf00d
                      obligation-period-begins: '2024-01-01T00:00:00-05:00'
                      obligation-period-ends: '2024-01-01T00:00:00-05:00'
                      periods:
                      - season-name: WINTER
                        begins: '2024-01-01T00:00:00-05:00'
                    invalid-proposal-count: 0
                    proposal-validation-errors: []
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '406':
          $ref: '#/components/responses/406-problem'
        '409':
          description: Conflict with Seasonal Ratings Schedule
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
            X-Rate-Limit-Reset:
              $ref: '#/components/headers/X-Rate-Limit-Reset'
        '413':
          $ref: '#/components/responses/413-empty'
        '415':
          $ref: '#/components/responses/415-problem'
        '422':
          $ref: '#/components/responses/422-problem'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - write:seasonal-proposals
      requestBody:
        description: "\nThere are two supported media types for a Seasonal Ratings proposals.\n\n`application/vnd.trolie.seasonal-ratings-proposal.v1+json` allows the \nRatings Provider to combine different limit types, such as\n`apparent-power` (MVA) and `current` (MW), in a single proposal.\n\n`application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json` for\nproposals that only require a single limit type, e.g., `apparent-power`.\nClients *MUST* specify that [limit-type](#tag/limit-type) as a media type\nparameter. For example,\n```http\nPATCH /rating-proposals/seasonal HTTP/1.1\nContent-Type: application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power\n```\nNote that this format is much more concise but requires significant care\nin serialization/deserialization.  For details, see the schema description\nfor the [seasonal ratings proposal of an individual\nresource](#schema/seasonal-proposals-slim) which is the description for\neach element of the `ratings` array.\n"
        required: true
        content:
          application/vnd.trolie.seasonal-ratings-proposal.v1+json:
            schema:
              $ref: '#/components/schemas/seasonal-ratings-proposal'
            example:
              proposal-header:
                source:
                  last-updated: '2025-10-31T15:05:43.044267100-07:00'
                  provider: UTILITY-A
                  origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                default-emergency-durations:
                - name: emergency
                  duration-minutes: 240
                power-system-resources:
                - resource-id: 8badf00d
                  alternate-identifiers:
                  - name: segmentX
                    authority: TO-NERC-ID
              ratings:
              - resource-id: 8badf00d
                periods:
                - season-name: WINTER
                  period-start: '2024-11-15T00:00:00-05:00'
                  period-end: '2025-03-01T00:00:00-05:00'
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                - season-name: SPRING
                  period-start: '2025-03-01T00:00:00-05:00'
                  period-end: '2025-06-15T00:00:00-05:00'
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                - season-name: SUMMER
                  period-start: '2025-06-15T00:00:00-05:00'
                  period-end: '2025-09-01T00:00:00-05:00'
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
                - season-name: FALL
                  period-start: '2025-09-01T00:00:00-05:00'
                  period-end: '2025-11-15T00:00:00-05:00'
                  continuous-operating-limit:
                    mva: 160
                  emergency-operating-limits:
                  - duration-name: LTE
                    limit:
                      mva: 165
          application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power:
            schema:
              $ref: '#/components/schemas/seasonal-ratings-proposal-slim'
            example:
              proposal-header:
                source:
                  last-updated: '2024-11-20T15:05:43.044267100-07:00'
                  provider: UTILITY-A
                  origin-id: 5aeacb25-9b65-4738-8a00-ac10afa63640
                default-emergency-durations:
                - name: emergency
                  duration-minutes: 240
                power-system-resources:
                - resource-id: 8badf00d
                  alternate-identifiers:
                  - name: segmentX
                    authority: TO-NERC-ID
                - resource-id: f34d3d
                  alternate-identifiers:
                  - name: segmentY
                    authority: TO-NERC-ID
                default-seasonal-schedule:
                  schedule:
                  - season-name: WINTER
                    begins: '2024-11-15T00:00:00-05:00'
                  - season-name: SPRING
                    begins: '2025-03-01T00:00:00-05:00'
                  - season-name: SUMMER
                    begins: '2025-06-15T00:00:00-05:00'
                  - season-name: FALL
                    begins: '2025-09-01T00:00:00-05:00'
                  ends: '2025-11-15T00:00:00-05:00'
              ratings:
              - - - 160
                  - 170
                - - 155
                  - 160
                - - 145
                  - 150
                - - 155
                  - 160
              - - - 161
                  - 171
                - - 156
                  - 161
                - - 146
                  - 151
                - - 156
                  - 161
components:
  schemas:
    missing-seasonal-obligation:
      type: object
      additionalProperties: false
      properties:
        resource-id:
          $ref: '#/components/schemas/resource-id'
        obligation-period-begins:
          $ref: '#/components/schemas/period-start'
        obligation-period-ends:
          $ref: '#/components/schemas/period-start'
        periods:
          description: "\nDefines the seasonal ratings schedule adopted in this proposal. Each season\nis given a `season-name` with the beginning of the season starting on\n`begins` and ending on the `begins` of the next season chronologically. \n\nIt is required that the seasons are listed chronologically.\n"
          type: array
          minItems: 1
          maxItems: 240
          items:
            $ref: '#/components/schemas/season'
    base-header:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        default-emergency-durations:
          $ref: '#/components/schemas/emergency-durations'
        default-limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
      additionalProperties: false
      required:
      - source
      - default-emergency-durations
    seasonal-rating-snapshot-item-detailed:
      type: object
      additionalProperties: false
      properties:
        resource-id:
          $ref: '#/components/schemas/resource-id'
        periods:
          description: "\nDefines the seasonal ratings schedule adopted in this proposal. Each season\nis given a `season-name` with the beginning of the season starting on\n`begins` and ending on the `begins` of the next season chronologically. \n\nIt is required that the seasons are listed chronologically.\n"
          type: array
          minItems: 1
          maxItems: 240
          items:
            $ref: '#/components/schemas/seasonal-snapshot-detailed'
    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
    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
    seasonal-proposal-slim:
      type: array
      title: Seasonal Period Proposal slim
      maxItems: 20
      minItems: 1
      items:
        type: number
        title: Continuous and Emergency Ratings values
        description: '

          Each number in this array corresponds to a value of the continuous and

          emergency ratings for a particular period.  The first values correspond to

          the continuous (normal) rating and the subsequent values correspond to the

          emergency ratings in order of decreasing duration.  The durations are

          defined in the `proposal-header.default-emergency-durations` field.


          The exact number of values in this array is further determined by the

          `limit-type` parameter of the media type.

          ```http

          Content-Type: application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power

          ```

          If the [limit-type](#tag/limit-type) is single valued, like

          `apparent-power`, then the array will have a single value for each rating.

          For example, if there was only one emergency duration defined, then the

          array would have two values, e.g. `[50, 55]`, corresponding to a 50MVA

          continuous rating and 55MVA emergency rating, respectively. A

          single-valued limit type is anticipated to be the most common case in

          practice.


          However, if the [limit-type](#tag/limit-type) is `active-power` and the

          Clearinghouse Provider has required both MW and power factor, e.g.,

          `{"mw":1, "pf":1}`, then the array will have two values for each rating.

          If we continue with the example of having only one emergency duration

          defined, then the array would have four values.  Thus, instead of

          `[normal_MVA, emergency_MVA]`, we would have `[normal_MW, normal_pf,

          emergency_MW, emergency_pf]`, e.g., `[300, 1.0, 350, 1.0]`.

          '
    seasonal-rating-snapshot-item:
      type: object
      additionalProperties: false
      properties:
        resource-id:
          $ref: '#/components/schemas/resource-id'
        periods:
          description: "\nDefines the seasonal ratings schedule adopted in this proposal. Each season\nis given a `season-name` with the beginning of the season starting on\n`begins` and ending on the `begins` of the next season chronologically. \n\nIt is required that the seasons are listed chronologically.\n"
          type: array
          minItems: 1
          maxItems: 240
          items:
            $ref: '#/components/schemas/seasonal-snapshot'
    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
    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
    ratings:
      type: array
      minItems: 1
      maxItems: 50000
      description: Set of forecast limits
      items:
        $ref: '#/components/schemas/seasonal-rating-snapshot-item-detailed'
    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'
    seasonal-ratings-snapshot-detailed-elide-psr:
      type: object
      description: A snapshot of the seasonal ratings for a monitoring set.
      properties:
        snapshot-header:
          $ref: '#/components/schemas/base-header'
        ratings:
          $ref: '#/components/schemas/ratings'
      required:
      - snapshot-header
      - ratings
    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
    ordered-named-power-system-resources:
      type: array
      minItems: 1
      maxItems: 50000
      description: '

        Ordered array of power system resource names. The order of these items

        determines the order of the ratings proposals in the `ratings` array.

        '
      items:
        $ref: '#/components/schemas/names'
    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
    seasonal-snapshot-detailed:
      type: object
      properties:
        period-start:
          $ref: '#/components/schemas/period-start'
        period-end:
          $ref: '#/components/schemas/period-start'
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        season-name:
          $ref: '#/components/schemas/season-name'
        day-night:
          $ref: '#/components/schemas/day-night'
        proposals-considered:
          description: '

            The seasonal ratings proposals considered when determining the

            seasonal ratings of a power system resource, e.g., a line or

            transformer.

            '
          type: array
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/seasonal-proposal-considered'
      required:
      - proposals-considered
      - period-start
      - period-end
      - continuous-operating-limit
      - emergency-operating-limits
      additionalProperties: false
      description: Proposes the continuous and emergency ratings for the specified Season.
      title: Seasonal Rating Proposal
    seasonal-proposal-considered:
      type: object
      properties:
        period-start:
          $ref: '#/components/schemas/period-start'
        period-end:
          $ref: '#/components/schemas/period-start'
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        current-source:
          $ref: '#/components/schemas/quality-class-current-source'
        inputs-used:
          description: '

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

            The particular information exchange determines which values may be expected

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

            is included to prescribe a way to include these inputs.

            '
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/input'
        season-name:
          $ref: '#/components/schemas/season-name'
        day-night:
          $ref: '#/components/schemas/day-night'
        source:
          $ref: '#/components/schemas/data-provenance'
        resource-id:
          $ref: '#/components/schemas/resource-id'
      required:
      - source
      - resource-id
      title: Seasonal Rating Proposal
      description: Proposes the continuous and emergency ratings for the specified Season.
      additionalProperties: false
    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
    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
    day-night:
      description: '

        Optional label to specify if the proposed seasonal ratings schedule is meant

        to be used only during the day or only a night. If this field is not provided,

        the schedule is assumed to be valid for both day and night.

        '
      type: string
      enum:
      - DAY
      - NIGHT
    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
    seasonal-proposal-header:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        default-emergency-durations:
          $ref: '#/components/schemas/emergency-durations'
        default-limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        power-system-resources:
          $ref: '#/components/schemas/named-power-system-resources'
      additionalProperties: false
      required:
      - source
      - default-emergency-durations
      - power-system-resources
      description: '

        Describes the contents of this seasonal ratings proposal.

        '
    seasonal-proposals:
      x-tags:
      - Seasonal
      title: Per-Resource Seasonal Ratings Schedule
      type: object
      additionalProperties: false
      properties:
        resource-id:
          $ref: '#/components/schemas/resource-id'
        periods:
          description: "\nDefines the seasonal ratings schedule adopted in this proposal. Each season\nis given a `season-name` with the beginning of the season starting on\n`begins` and ending on the `begins` of the next season chronologically. \n\nIt is required that the seasons are listed chronologically.\n"
          type: array
          minItems: 1
          maxItems: 240
          items:
            $ref: '#/components/schemas/seasonal-proposal'
    seasonal-ratings-snapshot-detailed:
      type: object
      description: A snapshot of the seasonal ratings for a monitoring set.
      properties:
        snapshot-header:
          $ref: '#/components/schemas/common-header'
        ratings:
          type: array
          minItems: 1
          maxItems: 50000
          description: Set of forecast limits
          items:
            $ref: '#/components/schemas/seasonal-rating-snapshot-item-detailed'
      required:
      - snapshot-header
      - ratings
    seasonal-snapshot:
      type: object
      properties:
        period-start:
          $ref: '#/components/schemas/period-start'
        period-end:
          $ref: '#/components/schemas/period-start'
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        season-name:
          $ref: '#/components/schemas/season-name'
        day-night:
          $ref: '#/components/schemas/day-night'
      required:
      - period-start
      - period-end
      - continuous-operating-limit
      - emergency-operating-limits
      additionalProperties: false
      description: Proposes the continuous and emergency ratings for the specified Season.
      title: Seasonal Rating Proposal
    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'
    seasonal-ratings-proposal-slim:
      type: object
      properties:
        proposal-header:
          $ref: '#/components/schemas/seasonal-proposal-header-slim'
        ratings:
          type: array
          minItems: 1
          maxItems: 50000
          description: Seasonal Ratings proposals (slim)
          items:
            $ref: '#/components/schemas/seasonal-proposals-slim'
      required:
      - proposal-header
      - ratings
    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
    seasonal-ratings-proposal-status:
      type: object
      description: Seasonal rating proposal status
      properties:
        incomplete-obligation-count:
          description: '

            The number of facilities for this provider whose Ratings Obligation has

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

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

            upper bound for performance and application security reasons.


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

            believe they have completed their submission process.

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

            Indicates which Seasonal Ratings Obligations have not been fulfilled.

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

            unfulfilled Obligations indicated in `incomplete-obligation-count`.

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

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

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

            Ratings Provider. This count is provided for troubleshooting,

            establishing trends, and triggering alerts.

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


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

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

              possibility of information disclosure when a Ratings Provider

              submits a proposal for a valid resource that they are not

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

              the client submitted.

              '
            properties:
              message:
                type: string
                pattern: ^(.){1,500}$
                maxLength: 500
                example: The `resource-forecast-proposal` for `8badf00d` is incomplete.
              resource-id:
                $ref: '#/components/schemas/resource-id'
        source:
          $ref: '#/components/schemas/data-provenance'
      required:
      - source
      - incomplete-obligation-count
      - invalid-proposal-count
    seasonal-proposals-slim:
      description: '

        A proposal for the seasonal ratings for a power system object, e.g., a

        segment. The proposal''s structure is determined by the contents of the

        `proposal-header`. In particular, this element should have an entry corresponding

        to each season in the `default-seasonal-schedule`.

        '
      type: array
      minItems: 1
      maxItems: 240
      items:
        $ref: '#/components/schemas/seasonal-proposal-slim'
      x-tags:
      - Seasonal
      title: Per-Resource Seasonal Ratings Schedule (slim)
      example:
      - - 50
        - 55
        - 60
        - 65
      - - 70
        - 75
        - 80
        - 85
      - - 90
        - 95
        - 100
        - 105
      - - 90
        - 95
        - 100
        - 105
    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
    season-name:
      type: string
      description: A name for the season
      maxLength: 255
      pattern: \w+
    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
    seasonal-schedule:
      description: "\nDefines the seasonal ratings schedule adopted in this proposal. Each season\nis given a `season-name` with the beginning of the season starting on\n`begins` and ending on the `begins` of the next season chronologically. \n\nIt is required that the seasons are listed chronologically.\n"
      type: array
      minItems: 1
      maxItems: 240
      items:
        $ref: '#/components/schemas/season'
    common-header:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        default-emergency-durations:
          $ref: '#/components/schemas/emergency-durations'
        default-limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        power-system-resources:
          $ref: '#/components/schemas/named-power-system-resources'
      additionalProperties: false
      required:
      - source
      - default-emergency-durations
      - power-system-resources
    seasonal-proposal-header-slim:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        default-emergency-durations:
          $ref: '#/components/schemas/emergency-durations'
        default-limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        power-system-resources:
          $ref: '#/components/schemas/ordered-named-power-system-resources'
        default-seasonal-schedule:
          description: '

            Defines the seasonal schedule that is used in the proposal.  Each season

            is defined in the `schedule` array and the `ends` property defines the

            end of the last season.  Each individual facility proposal must have

            corresponding entry for each entry In the `schedule` array.

            '
          properties:
            schedule:
              $ref: '#/components/schemas/seasonal-schedule'
            ends:
              $ref: '#/components/schemas/period-start'
            day-night:
              $ref: '#/components/schemas/day-night'
          required:
          - schedule
          - ends
      additionalProperties: false
      required:
      - source
      - default-emergency-durations
      - power-system-resources
      - default-seasonal-schedule
      description: '

        Describes the contents of the seasonal proposal. In particular, the

        structure of the `ratings` is determined by the details provided in this

        header.

        '
    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
    seasonal-ratings-proposal:
      type: object
      properties:
        proposal-header:
          $ref: '#/components/schemas/seasonal-proposal-header'
        ratings:
          type: array
          minItems: 1
          maxItems: 50000
          description: Seasonal Ratings proposals
          items:
            $ref: '#/components/schemas/seasonal-proposals'
      required:
      - proposal-header
      - ratings
    seasonal-proposal:
      type: object
      properties:
        period-start:
          $ref: '#/components/schemas/period-start'
        period-end:
          $ref: '#/components/schemas/period-start'
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        limiting-analysis:
          $ref: '#/components/schemas/limiting-analysis'
        current-source:
          $ref: '#/components/schemas/quality-class-current-source'
        inputs-used:
          description: '

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

            The particular information exchange determines which values may be expected

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

            is included to prescribe a way to include these inputs.

            '
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/input'
        season-name:
          $ref: '#/components/schemas/season-name'
        day-night:
          $ref: '#/components/schemas/day-night'
      required:
      - period-start
      - period-end
      - continuous-operating-limit
      - emergency-operating-limits
      title: Seasonal Rating Proposal
      description: Proposes the continuous and emergency ratings for the specified Season.
      additionalProperties: false
    seasonal-ratings-snapshot:
      type: object
      description: A snapshot of the seasonal ratings for a monitoring set.
      properties:
        snapshot-header:
          $ref: '#/components/schemas/common-header'
        ratings:
          type: array
          minItems: 1
          maxItems: 50000
          description: Set of forecast limits
          items:
            $ref: '#/components/schemas/seasonal-rating-snapshot-item'
      required:
      - snapshot-header
      - ratings
    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
    season:
      type: object
      properties:
        season-name:
          $ref: '#/components/schemas/season-name'
        begins:
          $ref: '#/components/schemas/period-start'
      required:
      - season-name
      - begins
  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'
    '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.'
    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'
    422-problem:
      description: Unprocessable content
      headers:
        X-Rate-Limit-Limit:
          $ref: '#/components/headers/X-Rate-Limit-Limit'
        X-Rate-Limit-Remaining:
          $ref: '#/components/headers/X-Rate-Limit-Remaining'
        X-Rate-Limit-Reset:
          $ref: '#/components/headers/X-Rate-Limit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem'
  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