openapi: 3.2.0
info:
  title: Trolie Seasonal Overrides API
  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
  x-logo:
    altText: TROLIE logo
    url: images/TROLIE-horizontal-color.svg
  description: 'Operations tagged Seasonal Overrides across 2 of this provider''s published API definitions: trolie-openapi-1.0.yaml, trolie-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://trolie.example.com
security:
- oauth2-primary-flow: []
tags:
- name: Seasonal Overrides
  description: 'A Seasonal Override instructs the system to use a temporary static rating

    instead of any concurrent Seasonal Rating for a resource.'
paths:
  /seasonal-overrides:
    get:
      operationId: getSeasonalOverrides
      description: 'Search for Seasonal Overrides. Will return any Seasonal Overrides that overlap with the start/end period.


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

        and the `ETag` of a previous `GET` response.'
      summary: Get Seasonal Overrides
      tags:
      - Seasonal Overrides
      parameters:
      - $ref: '#/components/parameters/period-start-query'
      - $ref: '#/components/parameters/period-end'
      - $ref: '#/components/parameters/query-filter'
      - $ref: '#/components/parameters/segment-filter'
      responses:
        '200':
          description: The requested seasonal ratings are returned.
          content:
            application/vnd.trolie.seasonal-override-set.v1+json:
              schema:
                $ref: '#/components/schemas/seasonal-override-set'
              example:
              - source:
                  provider: X-AMPL
                  last-updated: '2023-07-12T15:05:43.044267100-07:00'
                  origin-id: //trolie.example.com/seasonal-overrides/513a7cb3-5d3c-4b7e-849c-e4015846db53
                id: 513a7cb3-5d3c-4b7e-849c-e4015846db53
                resource:
                  resource-id: 8badf00d
                  alternate-identifiers:
                  - name: segmentX
                    authority: TO-NERC-ID
                  - name: LINE1 SEG-X
                    authority: RC-NERC-ID
                    mrid: 8badf00d
                start-time: '2025-07-12T16:00:00-07:00'
                end-time: '2025-08-01T00:00:00-07:00'
                continuous-operating-limit:
                  mva: 160
                emergency-operating-limits:
                - duration-name: emergency
                  limit:
                    mva: 165
                - duration-name: load-shed
                  limit:
                    mva: 170
                reason: Increased vegetation proximity
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '404':
          $ref: '#/components/responses/404-empty'
        '406':
          $ref: '#/components/responses/406-problem'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - read:seasonal-overrides
    post:
      operationId: createSeasonalOverride
      summary: Create a new seasonal override
      tags:
      - Seasonal Overrides
      requestBody:
        required: true
        content:
          application/vnd.trolie.seasonal-override.v1+json:
            schema:
              $ref: '#/components/schemas/seasonal-override-request'
            example:
              source:
                provider: X-AMPL
                last-updated: '2023-07-12T15:05:43.044267100-07:00'
                origin-id: 513a7cb3-5d3c-4b7e-849c-e4015846db53
              resource:
                resource-id: 8badf00d
                alternate-identifiers:
                - name: segmentX
                  authority: TO-NERC-ID
                - name: LINE1 SEG-X
                  authority: RC-NERC-ID
                  mrid: 8badf00d
              start-time: '2025-07-12T16:00:00-07:00'
              end-time: '2025-08-01T00:00:00-07:00'
              continuous-operating-limit:
                mva: 160
              emergency-operating-limits:
              - duration-name: emergency
                limit:
                  mva: 165
              - duration-name: load-shed
                limit:
                  mva: 170
              reason: Increased vegetation proximity
      responses:
        '201':
          description: The seasonal override was created
          content:
            application/vnd.trolie.seasonal-override.v1+json:
              schema:
                $ref: '#/components/schemas/seasonal-override'
              example:
                source:
                  provider: X-AMPL
                  last-updated: '2023-07-12T15:05:43.044267100-07:00'
                  origin-id: //trolie.example.com/seasonal-overrides/513a7cb3-5d3c-4b7e-849c-e4015846db53
                id: 513a7cb3-5d3c-4b7e-849c-e4015846db53
                resource:
                  resource-id: 8badf00d
                  alternate-identifiers:
                  - name: segmentX
                    authority: TO-NERC-ID
                  - name: LINE1 SEG-X
                    authority: RC-NERC-ID
                    mrid: 8badf00d
                start-time: '2025-07-12T16:00:00-07:00'
                end-time: '2025-08-01T00:00:00-07:00'
                continuous-operating-limit:
                  mva: 160
                emergency-operating-limits:
                - duration-name: emergency
                  limit:
                    mva: 165
                - duration-name: load-shed
                  limit:
                    mva: 170
                reason: Increased vegetation proximity
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
            Location:
              $ref: '#/components/headers/Location'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '404':
          $ref: '#/components/responses/404-empty'
        '406':
          $ref: '#/components/responses/406-problem'
        '413':
          $ref: '#/components/responses/413-empty'
        '415':
          $ref: '#/components/responses/415-problem'
        '422':
          $ref: '#/components/responses/422-problem'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - write:seasonal-overrides
    servers:
    - url: https://trolie.example.com
  /seasonal-overrides/{id}:
    get:
      operationId: getSeasonalOverride
      description: Obtain a specific temporary seasonal rating by Id.
      summary: Obtain a specific temporary seasonal rating by Id
      tags:
      - Seasonal Overrides
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/vnd.trolie.seasonal-override.v1+json:
              schema:
                $ref: '#/components/schemas/seasonal-override'
              example:
                source:
                  provider: X-AMPL
                  last-updated: '2023-07-12T15:05:43.044267100-07:00'
                  origin-id: //trolie.example.com/seasonal-overrides/513a7cb3-5d3c-4b7e-849c-e4015846db53
                id: 513a7cb3-5d3c-4b7e-849c-e4015846db53
                resource:
                  resource-id: 8badf00d
                  alternate-identifiers:
                  - name: segmentX
                    authority: TO-NERC-ID
                  - name: LINE1 SEG-X
                    authority: RC-NERC-ID
                    mrid: 8badf00d
                start-time: '2025-07-12T16:00:00-07:00'
                end-time: '2025-08-01T00:00:00-07:00'
                continuous-operating-limit:
                  mva: 160
                emergency-operating-limits:
                - duration-name: emergency
                  limit:
                    mva: 165
                - duration-name: load-shed
                  limit:
                    mva: 170
                reason: Increased vegetation proximity
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '404':
          $ref: '#/components/responses/404-empty'
        '406':
          $ref: '#/components/responses/406-problem'
        '410':
          $ref: '#/components/responses/410-problem'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - read:seasonal-overrides
    delete:
      operationId: deleteSeasonalOverride
      description: Delete a specific seasonal override by its Id.
      summary: Delete a specific seasonal override by its Id
      tags:
      - Seasonal Overrides
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '404':
          $ref: '#/components/responses/404-empty'
        '409':
          description: Seasonal overrides already employed in Operations cannot be deleted.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
              example:
                type: //trolie.example.com/spec/client-errors/409/seasonal-override-in-use
                title: 'Conflict: Seasonal Override in Use'
                status: 409
                detail: Seasonal Override with id 'fb06e551-37a8-4a98-8c97-fded702530d6' may not be deleted, as it has been used in operations and is now part of the record.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - write:seasonal-overrides
    put:
      operationId: updateSeasonalOverride
      summary: Updates an existing Seasonal override
      tags:
      - Seasonal Overrides
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/vnd.trolie.seasonal-override.v1+json:
            schema:
              $ref: '#/components/schemas/seasonal-override'
            example:
              source:
                provider: X-AMPL
                last-updated: '2023-07-12T15:05:43.044267100-07:00'
                origin-id: //trolie.example.com/seasonal-overrides/513a7cb3-5d3c-4b7e-849c-e4015846db53
              id: 513a7cb3-5d3c-4b7e-849c-e4015846db53
              resource:
                resource-id: 8badf00d
                alternate-identifiers:
                - name: segmentX
                  authority: TO-NERC-ID
                - name: LINE1 SEG-X
                  authority: RC-NERC-ID
                  mrid: 8badf00d
              start-time: '2025-07-12T16:00:00-07:00'
              end-time: '2025-08-01T00:00:00-07:00'
              continuous-operating-limit:
                mva: 160
              emergency-operating-limits:
              - duration-name: emergency
                limit:
                  mva: 165
              - duration-name: load-shed
                limit:
                  mva: 170
              reason: Increased vegetation proximity
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400-problem'
        '401':
          $ref: '#/components/responses/401-empty'
        '403':
          $ref: '#/components/responses/403-empty'
        '404':
          $ref: '#/components/responses/404-empty'
        '406':
          $ref: '#/components/responses/406-problem'
        '413':
          $ref: '#/components/responses/413-empty'
        '415':
          $ref: '#/components/responses/415-problem'
        '422':
          $ref: '#/components/responses/422-problem'
        '429':
          $ref: '#/components/responses/429-empty'
        '500':
          $ref: '#/components/responses/500-empty'
        default:
          $ref: '#/components/responses/500-empty'
      security:
      - oauth2-primary-flow:
        - write:seasonal-overrides
    servers:
    - url: https://trolie.example.com
components:
  schemas:
    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
    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
    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
    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
    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
    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'
    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
    seasonal-override:
      type: object
      description: 'Data structure for a seasonal override against a resource.  Includes a

        unique ID, start and (optional) end time, and a reason.  Must also include a

        set of values.

        '
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        resource:
          $ref: '#/components/schemas/names'
        start-time:
          $ref: '#/components/schemas/period-start'
        end-time:
          $ref: '#/components/schemas/period-start'
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        reason:
          description: 'Free-form text indicating the reason for the exception.

            '
          type: string
          format: free-form
          maxLength: 4000
        id:
          $ref: '#/components/schemas/local'
        day-night:
          $ref: '#/components/schemas/day-night'
      additionalProperties: false
      required:
      - id
      - resource
      - start-time
      - continuous-operating-limit
      - emergency-operating-limits
    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-override-set:
      type: array
      minItems: 0
      maxItems: 50000
      items:
        $ref: '#/components/schemas/seasonal-override'
    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
    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
    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
    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
    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: 867531
    seasonal-override-request:
      type: object
      description: 'Data structure for a seasonal override against a resource.

        Must also include a set of values.

        '
      properties:
        source:
          $ref: '#/components/schemas/data-provenance'
        resource:
          $ref: '#/components/schemas/names'
        start-time:
          $ref: '#/components/schemas/period-start'
        end-time:
          $ref: '#/components/schemas/period-start'
        continuous-operating-limit:
          $ref: '#/components/schemas/limit'
        emergency-operating-limits:
          $ref: '#/components/schemas/limit-value-set'
        reason:
          description: 'Free-form text indicating the reason for the exception.

            '
          type: string
          format: free-form
          maxLength: 4000
        day-night:
          $ref: '#/components/schemas/day-night'
      additionalProperties: false
      required:
      - resource
      - start-time
      - continuous-operating-limit
      - emergency-operating-limits
    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'
    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
    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
    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
    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
    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
    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
    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
    empty:
      description: Intended to proactively avoid information disclosure
      type:
      - string
      - 'null'
      maxLength: 0
      pattern: ^$
      example: ''
  responses:
    401-empty:
      description: Unauthorized
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/*:
          schema:
            $ref: '#/components/schemas/empty'
    403-empty:
      description: Access denied
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/*:
          schema:
            $ref: '#/components/schemas/empty'
    404-empty:
      description: Not Found
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/*:
          schema:
            $ref: '#/components/schemas/empty'
    429-empty:
      description: Too many requests (rate limiting)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/*:
          schema:
            $ref: '#/components/schemas/empty'
    406-problem:
      description: Not Acceptable (Content negotiation failed)
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem'
    422-problem:
      description: Unprocessable content
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem'
    '204':
      description: Operation successful. No Content.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        ETag:
          $ref: '#/components/headers/ETag'
    '304':
      description: Not Modified.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
    413-empty:
      description: Payload too large
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/*:
          schema:
            $ref: '#/components/schemas/empty'
    410-problem:
      description: 'Gone. The requested resource is no longer available.  TROLIE

        implementations MAY return this status code when a resource is known to

        have been deleted or archived, if the authenticated client would

        otherwise have had authorized access to the resource.

        '
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem'
    400-problem:
      description: Malformed request
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problem'
    500-empty:
      description: An unexpected error occurred
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/*:
          schema:
            $ref: '#/components/schemas/empty'
    415-problem:
      description: Unsupported media type
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-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'
  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
    segment-filter:
      name: segment
      description: "Only return limits for this segment.  \n"
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/local'
      examples:
        mrid:
          summary: A CIM mrid
          value: urn:uuid:12345678-1234-5678-1234-123456789012
        circuit-id:
          summary: A typical AC line identifier
          value: 867531
    period-start-query:
      name: period-start
      description: "Defines the start of an applicable operating period.  \n"
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/period-start'
    period-end:
      name: period-end
      description: Specifies the end of a period for which a filter specifies.  Periods will only be returned that start prior to this time.
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/period-start'
    id:
      name: id
      description: 'Opaque identifier for the object. Format of this identifier may

        very depending on the implementation.

        '
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/local'
      examples:
        uuid:
          value: urn:uuid:123e4567-e89b-12d3-a456-426614174000
          description: Example of a UUIDv4 identifier for an object.
        eic:
          value: urn:eic:10X1001A1001A515
          description: Example of an ENTSO-E Energy Identification Code for an object.
        qualified-entity-code:
          value: org:naesb:weq:eir:MISO
          description: 'A fully-qualified representation of an entity code from the NAESB WEQ-022

            Electric Industry Registry, currently implemented by the OATI webRegistry.

            Note that this representation is not an industry standard identifier

            format but is presented as an example of a structured identifier for such

            entity codes. In this example, the identifier is for Midcontinent

            Independent System Operator (MISO).

            '
        entity-code:
          value: MISO
          description: 'A unqualified entity code from the NAESB WEQ-022 Electric Industry

            Registry, currently implemented by the OATI webRegistry.  In this

            example, the identifier is for Midcontinent Independent System Operator

            (MISO).

            '
        ncr-id:
          value: NCR00826
          description: An example of a NERC Compliance Registry code for MISO.
  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-RateLimit-Reset:
      description: The number of seconds left in the current period
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 1000
    Location:
      description: 'The "Location" header field is used in some responses to refer to a specific  resource in relation to the response. In TROLIE, this is always associated with a 201 response (a POST), and therefore refers to the URI of the resource created.

        '
      schema:
        type: string
        format: uri-reference
        maxLength: 1000
    Retry-After:
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 60
        example: 60
        description: The seconds to delay after the response is received.
    X-RateLimit-Remaining:
      description: The number of remaining requests in the current period
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 1000
    X-RateLimit-Limit:
      description: The number of allowed requests in the current period
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 1000
  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-refined-from:
- trolie-openapi-1.0.yaml
- trolie-openapi.yml
x-tagGroups:
- name: Operations
  tags:
  - Real-Time
  - Forecasting
  - Seasonal
  - Seasonal Overrides
  - Temporary AAR Exceptions
  - Monitoring Sets
- name: Common Schemas
  tags:
  - limit-type