diff --git a/cspell.json b/cspell.json index c544a0b..c62e6d3 100644 --- a/cspell.json +++ b/cspell.json @@ -10,6 +10,7 @@ ,"excalidraw" ,"FERC" ,"ICCP" + ,"mrid" ,"NERC" ,"openapi" ,"owasp" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 70b09f9..9256d45 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -228,7 +228,7 @@ GEM mutex_m (0.2.0) net-http (0.4.1) uri - nokogiri (1.16.0-x86_64-linux) + nokogiri (1.16.2-x86_64-linux) racc (~> 1.4) octokit (4.25.1) faraday (>= 1, < 3) diff --git a/docs/_data/components/parameters/monitoring-set-filter.yaml b/docs/_data/components/parameters/monitoring-set-filter.yaml index c6ad69b..ea1f7cd 100644 --- a/docs/_data/components/parameters/monitoring-set-filter.yaml +++ b/docs/_data/components/parameters/monitoring-set-filter.yaml @@ -1,7 +1,5 @@ name: monitoring-set -description: > - Only return ratings or limits for facilities of the associated - `monitoring-set` +description: Only return ratings or limits for facilities of the associated `monitoring-set`. in: query required: false schema: diff --git a/docs/_data/components/schemas/actual-power-and-factor-value.yaml b/docs/_data/components/schemas/actual-power-and-factor-value.yaml deleted file mode 100644 index 1b30501..0000000 --- a/docs/_data/components/schemas/actual-power-and-factor-value.yaml +++ /dev/null @@ -1,16 +0,0 @@ -type: object -description: >- - Representation of a limit using a combination of actual power in MW and an - assumed power factor in MVA/MW -additionalProperties: false -properties: - mw: - type: number - format: float - minimum: 1 - maximum: 10000 - pf: - type: number - format: float - minimum: 0 - maximum: 1 diff --git a/docs/_data/components/schemas/apparent-power-value.yaml b/docs/_data/components/schemas/apparent-power-value.yaml deleted file mode 100644 index 6766682..0000000 --- a/docs/_data/components/schemas/apparent-power-value.yaml +++ /dev/null @@ -1,11 +0,0 @@ -type: object -description: >- - Representation of a limit in megavolt-amperes. This is the recommended - default for limits in TROLIE -additionalProperties: false -properties: - mva: - type: number - format: float - minimum: 1 - maximum: 10000 diff --git a/docs/_data/components/schemas/array-max-emergency-durations.yaml b/docs/_data/components/schemas/array-max-emergency-durations.yaml new file mode 100644 index 0000000..0bfd8b9 --- /dev/null +++ b/docs/_data/components/schemas/array-max-emergency-durations.yaml @@ -0,0 +1,39 @@ +emergency-durations: &max + type: array + description: Defines the durations in minutes used for emergency limits. + minItems: 1 + maxItems: 10 + items: + type: object + properties: + name: + $ref: ./limit-type.yaml + duration-minutes: + type: integer + format: int32 + minimum: 0 + maximum: 1440 + + +limit-value-set: + <<: *max + 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. The list of supported limit + types may be fetched from getSupportedLimitTypes. + + The value of the limits are in units as defined by the X-TROLIE-Limit-Units + header. + items: + type: object + description: Operating Limit + properties: + duration-name: + $ref: ./limit-type.yaml + limit: + $ref: ./limit.yaml diff --git a/docs/_data/components/schemas/array-max-forecast-periods.yaml b/docs/_data/components/schemas/array-max-forecast-periods.yaml index 825f401..bf15783 100644 --- a/docs/_data/components/schemas/array-max-forecast-periods.yaml +++ b/docs/_data/components/schemas/array-max-forecast-periods.yaml @@ -8,7 +8,7 @@ forecast-limit-item: type: array maxItems: 240 items: - $ref: 'forecast-limit-period.yaml#/slim' + $ref: 'forecast-limit-period.yaml#/forecast-period-snapshot-slim' forecast-limit-item-detailed: type: object @@ -19,20 +19,24 @@ forecast-limit-item-detailed: periods: <<: *max items: - $ref: 'forecast-limit-period.yaml#/detailed' + $ref: 'forecast-limit-period.yaml#/forecast-period-snapshot-detailed' -forecast-proposal-for-segment: +resource-forecast-proposal: type: object additionalProperties: false properties: - segment-id: + resource-id: $ref: ./generic-identifier.yaml periods: <<: *max items: - $ref: ./forecast-rating-period.yaml + $ref: 'forecast-limit-period.yaml#/forecast-period-proposal' + + required: + - resource-id + - periods -missing-forecast-rating-for-segment: +missing-forecast: type: object additionalProperties: false properties: diff --git a/docs/_data/components/schemas/array-max-monitored-elements.yaml b/docs/_data/components/schemas/array-max-monitored-elements.yaml index 6f1719b..e35cafd 100644 --- a/docs/_data/components/schemas/array-max-monitored-elements.yaml +++ b/docs/_data/components/schemas/array-max-monitored-elements.yaml @@ -1,22 +1,10 @@ -# TODO: monitoring-set is no longer referenced -monitoring-set: - description: | - Set of transmission facilities noteworthy to reference in queries in TROLIE. - The set of segments included in the monitoring set is implied by their - inclusion in the transmission facilities within the monitoring set. - type: object - additionalProperties: false - properties: - id: - $ref: ./generic-identifier.yaml - description: - $ref: '../../openapi-split.yaml#/components/schemas/description' - transmission-facilities: &max - type: array - minItems: 0 - maxItems: 50000 - items: - $ref: ./generic-identifier.yaml +forecast-limit-set: &max + type: array + minItems: 0 + maxItems: 50000 + description: Set of forecast limits + items: + $ref: 'array-max-forecast-periods.yaml#/forecast-limit-item' forecast-limit-set-detailed: <<: *max @@ -24,23 +12,52 @@ forecast-limit-set-detailed: items: $ref: 'array-max-forecast-periods.yaml#/forecast-limit-item-detailed' -forecast-limit-set: +named-power-system-objects: <<: *max - description: Set of forecast limits + description: Collection of power system object names items: - $ref: 'array-max-forecast-periods.yaml#/forecast-limit-item' + $ref: ./names.yaml + +forecast-proposal: + type: object + properties: + forecast-header: + $ref: ./rating-proposal-header.yaml + ratings: + <<: *max + description: Forecasted Ratings + items: + $ref: 'array-max-forecast-periods.yaml#/resource-forecast-proposal' + required: + - forecast-header + - ratings + +missing-forecast-rating-set: + <<: *max + description: A set of Missing Forecasted Ratings for a Forecast Window + items: + $ref: 'array-max-forecast-periods.yaml#/missing-forecast' realtime-limit-set: <<: *max + description: Real-time limits items: $ref: ./realtime-limit-item.yaml realtime-limit-set-detailed: <<: *max + description: Real-time limits including provenance. items: $ref: ./realtime-limit-item-detailed.yaml -rating-proposal: +realtime-ratings-proposals: + <<: *max + description: Real-Time Ratings Proposals + items: + $ref: 'array-max-forecast-periods.yaml#/realtime-rating-proposal' + +seasonal-rating-proposal: + description: Seasonal rating proposal allOf: - $ref: ./mutable-rating-proposal.yaml - type: object @@ -48,4 +65,9 @@ rating-proposal: ratings: <<: *max items: - $ref: 'array-max-seasons.yaml#/seasonal-proposals' \ No newline at end of file + $ref: 'array-max-seasons.yaml#/seasonal-proposals' +seasonal-rating-snapshot: + <<: *max + description: Seasonal rating snapshot + items: + $ref: ./array-max-seasons.yaml#/seasonal-rating-snapshot-item diff --git a/docs/_data/components/schemas/array-max-monitoring-sets.yaml b/docs/_data/components/schemas/array-max-monitoring-sets.yaml deleted file mode 100644 index d4000b5..0000000 --- a/docs/_data/components/schemas/array-max-monitoring-sets.yaml +++ /dev/null @@ -1,22 +0,0 @@ -monitoring-set-list: &max - description: List of monitoring set IDs - type: array - minItems: 0 - maxItems: 2000 - items: - $ref: ./generic-identifier.yaml - -forecast-ratings-proposals: - <<: *max - items: - $ref: 'array-max-forecast-periods.yaml#/forecast-proposal-for-segment' - -realtime-ratings-proposals: - <<: *max - items: - $ref: 'array-max-forecast-periods.yaml#/realtime-rating-proposal' - -missing-forecast-rating-set: - <<: *max - items: - $ref: 'array-max-forecast-periods.yaml#/missing-forecast-rating-for-segment' diff --git a/docs/_data/components/schemas/array-max-seasons.yaml b/docs/_data/components/schemas/array-max-seasons.yaml index 632ccd5..37d4ff5 100644 --- a/docs/_data/components/schemas/array-max-seasons.yaml +++ b/docs/_data/components/schemas/array-max-seasons.yaml @@ -4,8 +4,19 @@ seasonal-proposals: properties: segment-id: $ref: ./generic-identifier.yaml - seasons: + seasons: &max type: array - maxItems: 20 # max seasons + maxItems: 20 + minItems: 0 items: $ref: ./seasonal-proposal-season.yaml +seasonal-rating-snapshot-item: + type: object + additionalProperties: false + properties: + transmission-facility-id: + $ref: ./generic-identifier.yaml + seasons: + <<: *max + items: + $ref: ./seasonal-rating-snapshot-value.yaml \ No newline at end of file diff --git a/docs/_data/components/schemas/conditional-value-set.yaml b/docs/_data/components/schemas/conditional-value-set.yaml index 541f55a..121c76d 100644 --- a/docs/_data/components/schemas/conditional-value-set.yaml +++ b/docs/_data/components/schemas/conditional-value-set.yaml @@ -8,5 +8,7 @@ items: properties: condition: $ref: ./network-component-name.yaml - values: - $ref: ./limit-value-set.yaml + continuous-operating-limit: + $ref: ./limit.yaml + emergency-operating-limits: + $ref: ./array-max-emergency-durations.yaml#/limit-value-set diff --git a/docs/_data/components/schemas/current-value.yaml b/docs/_data/components/schemas/current-value.yaml deleted file mode 100644 index 04903bf..0000000 --- a/docs/_data/components/schemas/current-value.yaml +++ /dev/null @@ -1,11 +0,0 @@ -type: object -description: >- - Representation of a limit in amps. Assumes that TROLIE has a nominal voltage - in its model. -additionalProperties: false -properties: - amps: - type: number - format: float - minimum: 1 - maximum: 100000 diff --git a/docs/_data/components/schemas/forecast-limit-period.yaml b/docs/_data/components/schemas/forecast-limit-period.yaml index 421226e..3e5c00b 100644 --- a/docs/_data/components/schemas/forecast-limit-period.yaml +++ b/docs/_data/components/schemas/forecast-limit-period.yaml @@ -1,16 +1,41 @@ -slim: +forecast-period-proposal: type: object + title: Forecasted Period + description: | + + A Forecasted Period contains proposed limits for a power system + object, e.g., a segment, that were forecasted for a particular Period + in a Forecast Window. The status of the proposal as determined by the + Clearinghouse is also included. + properties: period-start: $ref: ./period-start.yaml - updated-time: - $ref: ./timestamp.yaml - values: - $ref: ./limit-value-set.yaml + period-end: + $ref: ./period-start.yaml + continuous-operating-limit: + $ref: ./limit.yaml + emergency-operating-limits: + $ref: ./array-max-emergency-durations.yaml#/limit-value-set + required: + - period-start + - period-end + - continuous-operating-limit + - emergency-operating-limits + +forecast-period-snapshot-slim: + allOf: + - $ref: '#/forecast-period-proposal' + - type: object + properties: + updated-time: + $ref: ./timestamp.yaml + required: + - updated-time -detailed: +forecast-period-snapshot-detailed: type: object description: Period detailed limits including provenance allOf: - - $ref: '#/slim' + - $ref: '#/forecast-period-snapshot-slim' - $ref: ./limit-provenance.yaml diff --git a/docs/_data/components/schemas/forecast-rating-period.yaml b/docs/_data/components/schemas/forecast-rating-period-deprecated.yaml similarity index 81% rename from docs/_data/components/schemas/forecast-rating-period.yaml rename to docs/_data/components/schemas/forecast-rating-period-deprecated.yaml index 4cd936f..ce99475 100644 --- a/docs/_data/components/schemas/forecast-rating-period.yaml +++ b/docs/_data/components/schemas/forecast-rating-period-deprecated.yaml @@ -30,7 +30,9 @@ properties: $ref: ./period-start.yaml status: $ref: ./proposal-status.yaml - values: - $ref: ./limit-value-set.yaml + continuous-operating-limit: + $ref: ./limit.yaml + emergency-operating-limits: + $ref: ./array-max-emergency-durations.yaml#/limit-value-set branch-only-values: - $ref: ./limit-value-set.yaml + $ref: ./array-max-emergency-durations.yaml#/limit-value-set diff --git a/docs/_data/components/schemas/forecast-rating-proposal.yaml b/docs/_data/components/schemas/forecast-rating-proposal.yaml deleted file mode 100644 index ec4e826..0000000 --- a/docs/_data/components/schemas/forecast-rating-proposal.yaml +++ /dev/null @@ -1,6 +0,0 @@ -allOf: - - $ref: ./mutable-rating-proposal.yaml - - type: object - properties: - ratings: - $ref: 'array-max-monitoring-sets.yaml#/forecast-ratings-proposals' diff --git a/docs/_data/components/schemas/limit-provenance.yaml b/docs/_data/components/schemas/limit-provenance.yaml index 46963e7..359e498 100644 --- a/docs/_data/components/schemas/limit-provenance.yaml +++ b/docs/_data/components/schemas/limit-provenance.yaml @@ -33,3 +33,6 @@ properties: Schema of this object is out of scope of the TROLIE specification. type: object +required: + - proposals-considered + - limiting-segment diff --git a/docs/_data/components/schemas/limit-value-set.yaml b/docs/_data/components/schemas/limit-value-set.yaml deleted file mode 100644 index 942f8ad..0000000 --- a/docs/_data/components/schemas/limit-value-set.yaml +++ /dev/null @@ -1,25 +0,0 @@ -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. The list of supported limit - types may be fetched from getSupportedLimitTypes. - - The value of the limits are in units as defined by the X-TROLIE-Limit-Units - header. -maxItems: 10 -items: - type: object - properties: - type: - $ref: ./limit-type.yaml - value: - type: object - oneOf: - - $ref: ./apparent-power-value.yaml - - $ref: ./current-value.yaml - - $ref: ./actual-power-and-factor-value.yaml diff --git a/docs/_data/components/schemas/limit.yaml b/docs/_data/components/schemas/limit.yaml new file mode 100644 index 0000000..09c4b6a --- /dev/null +++ b/docs/_data/components/schemas/limit.yaml @@ -0,0 +1,44 @@ +type: object +title: Limit +oneOf: + - type: object + title: Actual Power and Power Factor + description: >- + Representation of a limit using a combination of actual power in MW and an + assumed power factor in MVA/MW + additionalProperties: false + properties: + mw: + type: number + format: float + minimum: 1 + maximum: 10000 + pf: + type: number + format: float + minimum: 0 + maximum: 1 + - type: object + title: Apparent Power Value + description: >- + Representation of a limit in megavolt-amperes. This is the recommended + default for limits in TROLIE + additionalProperties: false + properties: + mva: + type: number + format: float + minimum: 1 + maximum: 10000 + - type: object + title: Current + description: >- + Representation of a limit in amps. Assumes that TROLIE has a nominal voltage + in its model. + additionalProperties: false + properties: + amps: + type: number + format: float + minimum: 1 + maximum: 100000 diff --git a/docs/_data/components/schemas/names.yaml b/docs/_data/components/schemas/names.yaml new file mode 100644 index 0000000..6bc8cee --- /dev/null +++ b/docs/_data/components/schemas/names.yaml @@ -0,0 +1,22 @@ +type: object +properties: + resource-id: + $ref: ./generic-identifier.yaml + alternate-identifiers: + type: array + maxItems: 10 + minItems: 1 + items: + type: object + properties: + name: + $ref: ./generic-identifier.yaml + authority: + $ref: ./entity-id.yaml + mrid: + $ref: ./generic-identifier.yaml + required: + - name + - authority +required: + - resource-id diff --git a/docs/_data/components/schemas/rating-proposal-header.yaml b/docs/_data/components/schemas/rating-proposal-header.yaml new file mode 100644 index 0000000..0768065 --- /dev/null +++ b/docs/_data/components/schemas/rating-proposal-header.yaml @@ -0,0 +1,32 @@ +type: object +description: > + General type for ratings proposal that is mutable over time, such as forecasts + and seasonal ratings. + + Like the immutable proposal, it includes general fields created by the + system. + + Filling in these fields before posting may be ignored, or result in a 400 + error from TROLIE. + + Properties include: + + * The time the proposal was last updated. + + * The ratings provider that owns the proposal. For mutable proposals such as + those for forecasts or seasonal + ratings, the ID of the owning ratings provider is the ID of the proposal itself. +properties: + last-updated: + $ref: ./timestamp.yaml + ratings-provider: + $ref: ./entity-id.yaml + default-emergency-durations: + $ref: ./array-max-emergency-durations.yaml#/emergency-durations + power-system-objects: + $ref: ./array-max-monitored-elements.yaml#/named-power-system-objects + +required: + - default-emergency-durations + - power-system-objects +additionalProperties: false diff --git a/docs/_data/components/schemas/realtime-limit-item.yaml b/docs/_data/components/schemas/realtime-limit-item.yaml index 1e47d8f..7606440 100644 --- a/docs/_data/components/schemas/realtime-limit-item.yaml +++ b/docs/_data/components/schemas/realtime-limit-item.yaml @@ -4,5 +4,7 @@ properties: $ref: ./generic-identifier.yaml updated-time: $ref: ./timestamp.yaml - values: - $ref: ./limit-value-set.yaml + continuous-operating-limit: + $ref: ./limit.yaml + emergency-operating-limits: + $ref: ./array-max-emergency-durations.yaml#/limit-value-set diff --git a/docs/_data/components/schemas/realtime-proposal-for-segment.yaml b/docs/_data/components/schemas/realtime-proposal-for-segment.yaml index cb1ab2c..dc92fa2 100644 --- a/docs/_data/components/schemas/realtime-proposal-for-segment.yaml +++ b/docs/_data/components/schemas/realtime-proposal-for-segment.yaml @@ -8,5 +8,7 @@ properties: $ref: ./generic-identifier.yaml status: $ref: ./proposal-status.yaml - values: - $ref: ./limit-value-set.yaml + continuous-operating-limit: + $ref: ./limit.yaml + emergency-operating-limits: + $ref: ./array-max-emergency-durations.yaml#/limit-value-set diff --git a/docs/_data/components/schemas/seasonal-proposal-season.yaml b/docs/_data/components/schemas/seasonal-proposal-season.yaml index e6cbc37..d39e9f8 100644 --- a/docs/_data/components/schemas/seasonal-proposal-season.yaml +++ b/docs/_data/components/schemas/seasonal-proposal-season.yaml @@ -11,7 +11,9 @@ properties: $ref: ./generic-identifier.yaml status: $ref: ./proposal-status.yaml - values: - $ref: ./limit-value-set.yaml + continuous-operating-limit: + $ref: ./limit.yaml + emergency-operating-limits: + $ref: ./array-max-emergency-durations.yaml#/limit-value-set conditional-values: $ref: ./conditional-value-set.yaml diff --git a/docs/_data/components/schemas/seasonal-rating-snapshot-item.yaml b/docs/_data/components/schemas/seasonal-rating-snapshot-item.yaml deleted file mode 100644 index 26c97b2..0000000 --- a/docs/_data/components/schemas/seasonal-rating-snapshot-item.yaml +++ /dev/null @@ -1,11 +0,0 @@ -type: object -additionalProperties: false -properties: - transmission-facility-id: - $ref: ./generic-identifier.yaml - seasons: - type: array - items: - $ref: ./seasonal-rating-snapshot-value.yaml - maxItems: 100 - minItems: 0 diff --git a/docs/_data/components/schemas/seasonal-rating-snapshot-value.yaml b/docs/_data/components/schemas/seasonal-rating-snapshot-value.yaml index fa9be19..08760e4 100644 --- a/docs/_data/components/schemas/seasonal-rating-snapshot-value.yaml +++ b/docs/_data/components/schemas/seasonal-rating-snapshot-value.yaml @@ -5,7 +5,9 @@ properties: $ref: ./generic-identifier.yaml effective-date: $ref: ./period-start.yaml - values: - $ref: ./limit-value-set.yaml + continuous-operating-limit: + $ref: ./limit.yaml + emergency-operating-limits: + $ref: ./array-max-emergency-durations.yaml#/limit-value-set conditional-values: $ref: ./conditional-value-set.yaml diff --git a/docs/_data/components/schemas/seasonal-rating-snapshot.yaml b/docs/_data/components/schemas/seasonal-rating-snapshot.yaml deleted file mode 100644 index 5be3fdf..0000000 --- a/docs/_data/components/schemas/seasonal-rating-snapshot.yaml +++ /dev/null @@ -1,5 +0,0 @@ -type: array -minItems: 0 -maxItems: 50000 -items: - $ref: ./seasonal-rating-snapshot-item.yaml diff --git a/docs/_data/components/schemas/temporary-rating.yaml b/docs/_data/components/schemas/temporary-rating.yaml index 298f9d8..4820122 100644 --- a/docs/_data/components/schemas/temporary-rating.yaml +++ b/docs/_data/components/schemas/temporary-rating.yaml @@ -17,11 +17,13 @@ properties: $ref: ./period-start.yaml updated-time: $ref: ./timestamp.yaml - values: - $ref: ./limit-value-set.yaml + continuous-operating-limit: + $ref: ./limit.yaml + emergency-operating-limits: + $ref: ./array-max-emergency-durations.yaml#/limit-value-set reason: description: | - Free-form text indicating the reason for the temporary rating. + Free-form text indicating the reason for the temporary rating. type: string format: free-form maxLength: 100 diff --git a/docs/_data/openapi-split.yaml b/docs/_data/openapi-split.yaml index 4aac683..df76774 100644 --- a/docs/_data/openapi-split.yaml +++ b/docs/_data/openapi-split.yaml @@ -470,8 +470,6 @@ components: write:seasonal-proposals: Submit seasonal ratings write:temporary-aar-exceptions: Write temporary AAR exceptions write:temporary-seasonal-ratings: Write temporary seasonal ratings - read:monitoring-set: Read monitoring set definitions - write:monitoring-sets: Write monitoring set definitions read:operating-snapshot: >- Read the ratings and limits snapshots in-use by the transmission provider diff --git a/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml b/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml index 7645f23..00e2bf3 100644 --- a/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml +++ b/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml @@ -40,6 +40,7 @@ get: - transmission-facility-id: line2 periods: - period-start: '2023-07-12T16:00:00-07:00' + period-end: '2023-07-12T17:00:00-07:00' updated-time: '2023-07-12T13:05:43.044267100-07:00' proposals-considered: - c386503e-ae8f-46e7-8fcf-bdee30f4f56b @@ -49,15 +50,14 @@ get: override-reason: Any reason entered by the operator for an override. additional-data: vendor-specific-data: {} - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: emergency + limit: mva: 165 - - type: load-shed - value: + - duration-name: load-shed + limit: mva: 170 application/json: schema: diff --git a/docs/_data/paths/rating-proposals_forecasts.yaml b/docs/_data/paths/rating-proposals_forecasts.yaml index 1081445..c6c6010 100644 --- a/docs/_data/paths/rating-proposals_forecasts.yaml +++ b/docs/_data/paths/rating-proposals_forecasts.yaml @@ -33,32 +33,46 @@ get: description: OK content: application/vnd.trolie.rating-forecast-proposal.v1+json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: &forecast-rating-proposal + $ref: ../components/schemas/array-max-monitored-elements.yaml#/forecast-proposal example: - timestamp: '2023-07-12T15:05:43.044267100-07:00' - ratings-provider: UTILITY-X + forecast-header: + last-updated: '2023-07-12T15:05:43.044267100-07:00' + default-emergency-durations: + - name: lte + duration-minutes: 240 + - name: ste + duration-minutes: 30 + - name: dal + duration-minutes: 15 + power-system-objects: + - resource-id: 8badf00d + alternate-identifiers: + - name: segmentX + authority: TO-NERC-ID + - name: LINE1 SEG-X + authority: RC-NERC-ID + mrid: 8badf00d + ratings-provider: UTILITY-X ratings: - - segment-id: segmentX + - resource-id: segmentX periods: - period-start: '2023-07-12T16:00:00-07:00' - status: pending - values: - - type: normal - value: - mva: 160 - - type: ste - value: + period-end: '2023-07-12T17:00:00-07:00' + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' @@ -91,13 +105,11 @@ patch: requestBody: content: application/vnd.trolie.rating-forecast-proposal.v1+json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal example: $ref: ../../example-narratives/examples/forecast-ratings-proposal-patch.json application/json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal responses: '202': description: > @@ -107,32 +119,45 @@ patch: `getRatingForecastProposals` content: application/vnd.trolie.rating-forecast-proposal.v1+json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal example: - timestamp: '2023-07-12T15:05:43.044267100-07:00' - ratings-provider: UTILITY-A + forecast-header: + last-updated: '2023-07-12T15:05:43.044267100-07:00' + default-emergency-durations: + - name: lte + duration-minutes: 240 + - name: ste + duration-minutes: 30 + - name: dal + duration-minutes: 15 + power-system-objects: + - resource-id: 8badf00d + alternate-identifiers: + - name: segmentX + authority: TO-NERC-ID + - name: LINE1 SEG-X + authority: RC-NERC-ID + mrid: 8badf00d + ratings-provider: UTILITY-X ratings: - - segment-id: segmentX + - resource-id: segmentX periods: - period-start: '2023-07-12T16:00:00-07:00' - status: pending - values: - - type: normal - value: - mva: 160 - - type: ste - value: + period-end: '2023-07-12T17:00:00-07:00' + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' '400': *malformed diff --git a/docs/_data/paths/rating-proposals_forecasts_{ratings-provider}.yaml b/docs/_data/paths/rating-proposals_forecasts_{ratings-provider}.yaml index 5535549..8bfff8d 100644 --- a/docs/_data/paths/rating-proposals_forecasts_{ratings-provider}.yaml +++ b/docs/_data/paths/rating-proposals_forecasts_{ratings-provider}.yaml @@ -15,32 +15,46 @@ get: description: OK content: application/vnd.trolie.rating-forecast-proposal.v1+json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: &forecast-rating-proposal + $ref: ../components/schemas/array-max-monitored-elements.yaml#/forecast-proposal example: - timestamp: '2023-07-12T15:05:43.044267100-07:00' - ratings-provider: UTILITY-X + forecast-header: + last-updated: '2023-07-12T15:05:43.044267100-07:00' + ratings-provider: UTILITY-X + default-emergency-durations: + - name: lte + duration-minutes: 240 + - name: ste + duration-minutes: 30 + - name: dal + duration-minutes: 15 + power-system-objects: + - resource-id: 8badf00d + alternate-identifiers: + - name: segmentX + authority: TO-NERC-ID + - name: LINE1 SEG-X + authority: RC-NERC-ID + mrid: 8badf00d ratings: - - segment-id: segmentX + - resource-id: segmentX periods: - period-start: '2023-07-12T16:00:00-07:00' - status: pending - values: - - type: normal - value: - mva: 160 - - type: ste - value: + period-end: '2023-07-12T17:00:00-07:00' + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' '304': ¬-modified @@ -77,29 +91,45 @@ patch: requestBody: content: application/vnd.trolie.rating-forecast-proposal.v1+json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal example: + forecast-header: + last-updated: '2023-07-12T15:05:43.044267100-07:00' + ratings-provider: UTILITY-A + default-emergency-durations: + - name: lte + duration-minutes: 240 + - name: ste + duration-minutes: 30 + - name: dal + duration-minutes: 15 + power-system-objects: + - resource-id: 8badf00d + alternate-identifiers: + - name: segmentX + authority: TO-NERC-ID + - name: LINE1 SEG-X + authority: RC-NERC-ID + mrid: 8badf00d ratings: - - segment-id: segmentX + - resource-id: segmentX periods: - period-start: '2023-07-12T16:00:00-07:00' - values: - - type: normal - value: - mva: 160 - - type: ste - value: + period-end: '2023-07-12T17:00:00-07:00' + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal responses: '202': description: > @@ -109,32 +139,45 @@ patch: `getRatingForecastProposals` content: application/vnd.trolie.rating-forecast-proposal.v1+json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal example: - timestamp: '2023-07-12T15:05:43.044267100-07:00' - ratings-provider: UTILITY-A + forecast-header: + last-updated: '2023-07-12T15:05:43.044267100-07:00' + ratings-provider: UTILITY-A + default-emergency-durations: + - name: lte + duration-minutes: 240 + - name: ste + duration-minutes: 30 + - name: dal + duration-minutes: 15 + power-system-objects: + - resource-id: 8badf00d + alternate-identifiers: + - name: segmentX + authority: TO-NERC-ID + - name: LINE1 SEG-X + authority: RC-NERC-ID + mrid: 8badf00d ratings: - - segment-id: segmentX + - resource-id: segmentX periods: - period-start: '2023-07-12T16:00:00-07:00' - status: pending - values: - - type: normal - value: - mva: 160 - - type: ste - value: + period-end: '2023-07-12T17:00:00-07:00' + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: ../components/schemas/forecast-rating-proposal.yaml + schema: *forecast-rating-proposal headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' '304': *not-modified @@ -150,7 +193,7 @@ patch: '429': *rate-limit-hit '500': *unexpected-error-empty default: *unexpected-error-empty - + security: - oauth2-primary-flow: - write:forecast-proposals diff --git a/docs/_data/paths/rating-proposals_missing_forecasts.yaml b/docs/_data/paths/rating-proposals_missing_forecasts.yaml index 96d5e38..dcfaa6f 100644 --- a/docs/_data/paths/rating-proposals_missing_forecasts.yaml +++ b/docs/_data/paths/rating-proposals_missing_forecasts.yaml @@ -34,14 +34,14 @@ get: content: application/vnd.trolie.missing-forecast-rating-set.v1+json: schema: - $ref: "../components/schemas/array-max-monitoring-sets.yaml#/missing-forecast-rating-set" + $ref: "../components/schemas/array-max-monitored-elements.yaml#/missing-forecast-rating-set" example: - segment-id: segmentX periods: - '2023-07-12T16:00:00-07:00' application/json: schema: - $ref: "../components/schemas/array-max-monitoring-sets.yaml#/missing-forecast-rating-set" + $ref: "../components/schemas/array-max-monitored-elements.yaml#/missing-forecast-rating-set" headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' diff --git a/docs/_data/paths/rating-proposals_missing_forecasts_{ratings-provider}.yaml b/docs/_data/paths/rating-proposals_missing_forecasts_{ratings-provider}.yaml index 4d0aa68..1fe8456 100644 --- a/docs/_data/paths/rating-proposals_missing_forecasts_{ratings-provider}.yaml +++ b/docs/_data/paths/rating-proposals_missing_forecasts_{ratings-provider}.yaml @@ -35,14 +35,14 @@ get: content: application/vnd.trolie.missing-forecast-rating-set.v1+json: schema: - $ref: "../components/schemas/array-max-monitoring-sets.yaml#/missing-forecast-rating-set" + $ref: "../components/schemas/array-max-monitored-elements.yaml#/missing-forecast-rating-set" example: - segment-id: segmentX periods: - '2023-07-12T16:00:00-07:00' application/json: schema: - $ref: "../components/schemas/array-max-monitoring-sets.yaml#/missing-forecast-rating-set" + $ref: "../components/schemas/array-max-monitored-elements.yaml#/missing-forecast-rating-set" headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' diff --git a/docs/_data/paths/rating-proposals_realtime.yaml b/docs/_data/paths/rating-proposals_realtime.yaml index 8e3b6d1..a0cd83c 100644 --- a/docs/_data/paths/rating-proposals_realtime.yaml +++ b/docs/_data/paths/rating-proposals_realtime.yaml @@ -30,11 +30,10 @@ get: description: OK content: application/vnd.trolie.realtime-rating-proposal-set.v1+json: - schema: - $ref: "../components/schemas/array-max-monitoring-sets.yaml#/realtime-ratings-proposals" + schema: &realtime-ratings-proposals + $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-ratings-proposals" application/json: - schema: - $ref: "../components/schemas/array-max-monitoring-sets.yaml#/realtime-ratings-proposals" + schema: *realtime-ratings-proposals headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' diff --git a/docs/_data/paths/rating-proposals_seasonal.yaml b/docs/_data/paths/rating-proposals_seasonal.yaml index fd7894a..63ff315 100644 --- a/docs/_data/paths/rating-proposals_seasonal.yaml +++ b/docs/_data/paths/rating-proposals_seasonal.yaml @@ -29,8 +29,8 @@ get: description: OK content: application/vnd.trolie.seasonal-rating-proposal.v1+json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: &seasonal-rating-proposal + $ref: "../components/schemas/array-max-monitored-elements.yaml#/seasonal-rating-proposal" example: timestamp: '2023-07-12T15:05:43.044267100-07:00' owner: UTILITY A @@ -39,22 +39,20 @@ get: seasons: - season-id: fall status: accepted - values: - - type: normal - value: - mva: 160 - - type: ste - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' @@ -88,29 +86,26 @@ patch: requestBody: content: application/vnd.trolie.seasonal-rating-proposal.v1+json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal example: ratings: - segment-id: segmentX seasons: - season-id: fall - values: - - type: normal - value: - mva: 160 - - type: ste - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal responses: '202': description: > @@ -118,8 +113,7 @@ patch: need to undergo additional validation and propagation to other systems. content: application/vnd.trolie.seasonal-proposal.v1+json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal example: timestamp: '2023-07-12T15:05:43.044267100-07:00' owner: UTILITY A @@ -128,22 +122,20 @@ patch: seasons: - season-id: fall status: accepted - values: - - type: normal - value: - mva: 160 - - type: ste - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' diff --git a/docs/_data/paths/rating-proposals_seasonal_{ratings-provider}.yaml b/docs/_data/paths/rating-proposals_seasonal_{ratings-provider}.yaml index c3077b2..67ddc00 100644 --- a/docs/_data/paths/rating-proposals_seasonal_{ratings-provider}.yaml +++ b/docs/_data/paths/rating-proposals_seasonal_{ratings-provider}.yaml @@ -13,8 +13,8 @@ get: description: OK content: application/vnd.trolie.seasonal-rating-proposal.v1+json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: &seasonal-rating-proposal + $ref: "../components/schemas/array-max-monitored-elements.yaml#/seasonal-rating-proposal" example: timestamp: '2023-07-12T15:05:43.044267100-07:00' owner: UTILITY A @@ -23,22 +23,21 @@ get: seasons: - season-id: fall status: accepted - values: - - type: normal - value: - mva: 160 - - type: ste - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal + #$ref: "../components/schemas/array-max-monitored-elements.yaml#/seasonal-rating-proposal" headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' @@ -76,29 +75,26 @@ patch: requestBody: content: application/vnd.trolie.seasonal-rating-proposal.v1+json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal example: ratings: - segment-id: segmentX seasons: - season-id: fall - values: - - type: normal - value: - mva: 160 - - type: ste - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal responses: '202': description: > @@ -106,8 +102,7 @@ patch: need to undergo additional validation and propagation to other systems. content: application/vnd.trolie.seasonal-proposal.v1+json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal example: timestamp: '2023-07-12T15:05:43.044267100-07:00' owner: UTILITY A @@ -116,22 +111,20 @@ patch: seasons: - season-id: fall status: accepted - values: - - type: normal - value: - mva: 160 - - type: ste - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: lte - value: + - duration-name: lte + limit: mva: 170 - - type: dal - value: + - duration-name: dal + limit: mva: 170 application/json: - schema: - $ref: "../components/schemas/array-max-monitored-elements.yaml#/rating-proposal" + schema: *seasonal-rating-proposal headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' diff --git a/docs/_data/paths/seasonal-ratings_snapshot.yaml b/docs/_data/paths/seasonal-ratings_snapshot.yaml index 263a5cc..9cfd4ca 100644 --- a/docs/_data/paths/seasonal-ratings_snapshot.yaml +++ b/docs/_data/paths/seasonal-ratings_snapshot.yaml @@ -3,7 +3,7 @@ head: &head description: > Use to obtain the headers that would be returned for `getSeasonalRatingsSnapshot`. Useful for cache invalidation. - summary: Get header for Seasonal Ratings + summary: Get headers for Seasonal Ratings tags: - Seasonal Rating Snapshots parameters: @@ -19,35 +19,31 @@ head: &head get: <<: *head operationId: getSeasonalRatingsSnapshot - description: >- - Retrieve the nominal and seasonal ratings for all facilities in the - `monitoring-set`. + description: Retrieve the nominal and seasonal ratings. summary: Get Seasonal Ratings responses: '200': description: OK content: application/vnd.trolie.seasonal-rating-snapshot.v1+json: - schema: - $ref: ../components/schemas/seasonal-rating-snapshot.yaml + schema: &seasonal-rating-snapshot + $ref: ../components/schemas/array-max-monitored-elements.yaml#/seasonal-rating-snapshot example: - transmission-facility-id: line2 seasons: - season-instance: fall-2023 effective-date: '2023-09-01T00:00:00-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: emergency + limit: mva: 165 - - type: load-shed - value: + - duration-name: load-shed + limit: mva: 170 application/json: - schema: - $ref: ../components/schemas/seasonal-rating-snapshot.yaml + schema: *seasonal-rating-snapshot headers: $ref: '../openapi-split.yaml#/components/responses/200/headers' diff --git a/docs/_data/paths/temporary-aar-exceptions.yaml b/docs/_data/paths/temporary-aar-exceptions.yaml index a019c02..04fe17d 100644 --- a/docs/_data/paths/temporary-aar-exceptions.yaml +++ b/docs/_data/paths/temporary-aar-exceptions.yaml @@ -40,15 +40,17 @@ get: start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' updated-time: '2025-07-08T13:05:43.044267100-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: load-shed - value: + - duration-name: lte + limit: + mva: 170 + - duration-name: dal + limit: mva: 170 reason: Free-form text reason. application/json: @@ -93,15 +95,17 @@ post: segment-id: segmentX start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: load-shed - value: + - duration-name: lte + limit: + mva: 170 + - duration-name: dal + limit: mva: 170 reason: Free-form text reason. application/json: @@ -120,15 +124,17 @@ post: start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' updated-time: '2025-07-08T13:05:43.044267100-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: load-shed - value: + - duration-name: lte + limit: + mva: 170 + - duration-name: dal + limit: mva: 170 reason: Free-form text reason. application/json: diff --git a/docs/_data/paths/temporary-aar-exceptions_{id}.yaml b/docs/_data/paths/temporary-aar-exceptions_{id}.yaml index 739adf2..f6a6def 100644 --- a/docs/_data/paths/temporary-aar-exceptions_{id}.yaml +++ b/docs/_data/paths/temporary-aar-exceptions_{id}.yaml @@ -19,15 +19,17 @@ get: start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' updated-time: '2025-07-08T13:05:43.044267100-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: load-shed - value: + - duration-name: lte + limit: + mva: 170 + - duration-name: dal + limit: mva: 170 reason: Free-form text reason. application/json: @@ -102,15 +104,17 @@ put: segment-id: segmentX start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: ste + limit: mva: 165 - - type: load-shed - value: + - duration-name: lte + limit: + mva: 170 + - duration-name: dal + limit: mva: 170 reason: Free-form text reason. application/json: diff --git a/docs/_data/paths/temporary-seasonal-ratings.yaml b/docs/_data/paths/temporary-seasonal-ratings.yaml index a853050..189b537 100644 --- a/docs/_data/paths/temporary-seasonal-ratings.yaml +++ b/docs/_data/paths/temporary-seasonal-ratings.yaml @@ -42,15 +42,14 @@ get: start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' updated-time: '2025-07-08T13:05:43.044267100-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: emergency + limit: mva: 165 - - type: load-shed - value: + - duration-name: load-shed + limit: mva: 170 reason: Free-form text reason. application/json: @@ -96,15 +95,14 @@ post: segment-id: segmentX start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: emergency + limit: mva: 165 - - type: load-shed - value: + - duration-name: load-shed + limit: mva: 170 reason: Free-form text reason. application/json: @@ -123,15 +121,14 @@ post: start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' updated-time: '2025-07-08T13:05:43.044267100-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: emergency + limit: mva: 165 - - type: load-shed - value: + - duration-name: load-shed + limit: mva: 170 reason: Free-form text reason. application/json: diff --git a/docs/_data/paths/temporary-seasonal-ratings_{id}.yaml b/docs/_data/paths/temporary-seasonal-ratings_{id}.yaml index 8b2a69f..6195b85 100644 --- a/docs/_data/paths/temporary-seasonal-ratings_{id}.yaml +++ b/docs/_data/paths/temporary-seasonal-ratings_{id}.yaml @@ -19,15 +19,14 @@ get: start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' updated-time: '2025-07-08T13:05:43.044267100-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: emergency + limit: mva: 165 - - type: load-shed - value: + - duration-name: "load-shed" + limit: mva: 170 reason: Free-form text reason. application/json: @@ -102,15 +101,14 @@ put: segment-id: segmentX start-time: '2025-07-12T16:00:00-07:00' end-time: '2025-07-13T12:00:00-07:00' - values: - - type: normal - value: - mva: 160 - - type: emergency - value: + continuous-operating-limit: + mva: 160 + emergency-operating-limits: + - duration-name: emergency + limit: mva: 165 - - type: load-shed - value: + - duration-name: "load-shed" + limit: mva: 170 reason: Free-form text reason. application/json: diff --git a/docs/concepts.md b/docs/concepts.md index 11613dc..10232d6 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -22,4 +22,22 @@ Proposals are forecasted or real-time ratings values submitted to TROLIE against As implied above, Snapshots are generated in TROLIE server implementations based on proposals and other inputs to generate in-use ratings for each Transmission Facility. TROLIE allows for ratings providers to fetch the latest snapshot, aka the latest "version" of the ratings data. ## Monitoring Sets -Monitoring Sets are arbitrarily defined sets of transmission facilities that may be used to filter ratings and limits returned by queries against these APIs. Defining the contents of these monitoring sets may vary, and is up to TROLIE server implementations. + +Monitoring Sets are named sets of power system objects that may be used to +filter ratings and limits returned by queries against these APIs. How Monitoring +Sets are defined is beyond the scope of the TROLIE specification, and it is +assumed that the sender and receiver have predefined the appropriate Monitoring +Sets. + +A typical implementation might define a Monitoring Set for each Ratings +Provider, containing all of the power system objects of interest to that Rating +Provider, such as their owned and/or operated facilities as well as any +additional objects whose limits they might monitor. It is generally assumed that +the Ratings Provider's Monitoring Set would include all of the transmission +facilities or other power system objects for which they have a Ratings +Obligation as well as their so-called "tier 1" monitored elements. + +Another typical Monitoring Set would be that which nominates the complete +footprint for the Transmission Provider. A natural choice for the +`monitoring-set` identifier is the NERC id of the entity that defines the +`monitoring-set`, if applicable. diff --git a/docs/example-narratives/examples/forecast-limits-detailed.json b/docs/example-narratives/examples/forecast-limits-detailed.json index f80cb29..2f6037a 100644 --- a/docs/example-narratives/examples/forecast-limits-detailed.json +++ b/docs/example-narratives/examples/forecast-limits-detailed.json @@ -4,6 +4,7 @@ "periods": [ { "period-start": "2023-07-12T16:00:00-07:00", + "period-end": "2023-07-12T17:00:00-07:00", "updated-time": "2023-07-12T13:05:43.044267100-07:00", "proposals-considered":["c386503e-ae8f-46e7-8fcf-bdee30f4f56b"], "temporary-aar-exceptions": ["2d8c80e8-f533-4be9-85bf-f7f81eb73d67"], @@ -12,22 +13,17 @@ "additional-data": { "vendor-specific-data": {} }, - "values": [ + "continuous-operating-limit": { "mva": 160 }, + "emergency-operating-limits": [ { - "type": "normal", - "value": { - "mva": 160 - } - }, - { - "type": "emergency", - "value": { + "duration-name": "emergency", + "limit": { "mva": 165 } }, { - "type": "load-shed", - "value": { + "duration-name": "load-shed", + "limit": { "mva": 170 } } @@ -35,4 +31,4 @@ } ] } -] \ No newline at end of file +] diff --git a/docs/example-narratives/examples/forecast-limits-slim.json b/docs/example-narratives/examples/forecast-limits-slim.json index 806c702..48e3953 100644 --- a/docs/example-narratives/examples/forecast-limits-slim.json +++ b/docs/example-narratives/examples/forecast-limits-slim.json @@ -4,23 +4,19 @@ "periods": [ { "period-start": "2023-07-12T16:00:00-07:00", + "period-end": "2023-07-12T17:00:00-07:00", "updated-time": "2023-07-12T13:05:43.044267100-07:00", - "values": [ + "continuous-operating-limit": { "mva": 160 }, + "emergency-operating-limits": [ { - "type": "normal", - "value": { - "mva": 160 - } - }, - { - "type": "emergency", - "value": { + "duration-name": "emergency", + "limit": { "mva": 165 } }, { - "type": "load-shed", - "value": { + "duration-name": "load-shed", + "limit": { "mva": 170 } } @@ -28,4 +24,4 @@ } ] } -] \ No newline at end of file +] diff --git a/docs/example-narratives/examples/forecast-ratings-proposal-patch.json b/docs/example-narratives/examples/forecast-ratings-proposal-patch.json index 6f75e09..7a0fe1b 100644 --- a/docs/example-narratives/examples/forecast-ratings-proposal-patch.json +++ b/docs/example-narratives/examples/forecast-ratings-proposal-patch.json @@ -1,59 +1,66 @@ { + "forecast-header" : { + "default-emergency-durations": [ + { "name": "emergency", "duration-minutes": 60} + ], + "power-system-objects": [ + { "resource-id": "8badf00d", + "alternate-identifiers": [ + {"name": "segmentX", "authority": "TO-NERC-ID"}, + {"name": "LINE1 SEG-X", "authority": "RC-NERC-ID", "mrid": "8badf00d"} + ] + } + ] + }, "ratings": [ - { - "segment-id": "segmentX", + { + "resource-id": "segmentX", "periods": [ { "period-start": "2025-11-02T01:00:00-05:00", - "values": [ + "period-end": "2025-11-02T02:00:00-05:00", + "continuous-operating-limit": { + "mva": 160 + }, + "emergency-operating-limits": [ { - "type": "normal", - "value": { - "mva": 160 - } - }, - { - "type": "emergency", - "value": { + "duration-name": "emergency", + "limit": { "mva": 165 - } + } } ] }, { - "period-start": "2025-11-02T01:00:00-06:00", - "values": [ - { - "type": "normal", - "value": { - "mva": 162 - } - }, - { - "type": "emergency", - "value": { - "mva": 167 - } + "period-start": "2025-11-02T02:00:00-05:00", + "period-end": "2025-11-02T03:00:00-05:00", + "continuous-operating-limit": { + "mva": 160 + }, + "emergency-operating-limits": [ + { + "duration-name": "emergency", + "limit": { + "mva": 165 } - ] - }, + } + ] + }, { - "period-start": "2025-11-02T02:00:00-06:00", - "values": [ - { - "type": "normal", - "value": { - "mva": 162 - } - }, - { - "type": "emergency", - "value": { - "mva": 167 - } + "period-start": "2025-11-02T03:00:00-05:00", + "period-end": "2025-11-02T04:00:00-05:00", + "continuous-operating-limit": { + "mva": 160 + }, + "emergency-operating-limits": [ + { + "duration-name": "emergency", + "limit": { + "mva": 165 } - ] - } + } + ] + } ] } ] diff --git a/docs/example-narratives/examples/realtime-limit-set-detailed.json b/docs/example-narratives/examples/realtime-limit-set-detailed.json index 7bbd1ea..1c67225 100644 --- a/docs/example-narratives/examples/realtime-limit-set-detailed.json +++ b/docs/example-narratives/examples/realtime-limit-set-detailed.json @@ -7,31 +7,26 @@ "temporary-aar-exceptions": [ "2d8c80e8-f533-4be9-85bf-f7f81eb73d67" ], - "limiting-segment-id": "segmentX", + "limiting-segment": "segmentX", "override-reason": "Any reason entered by the operator for an override.", "additional-data": { "vendor-specific-data": {} }, "updated-time": "2023-07-12T13:05:43.044267100-07:00", - "values": [ - { - "type": "normal", - "value": { - "mva": 160 + "continuous-operating-limit": { "mva": 160 }, + "emergency-operating-limits": [ + { + "duration-name": "emergency", + "limit": { + "mva": 165 + } + }, + { + "duration-name": "load-shed", + "limit": { + "mva": 170 + } } - }, - { - "type": "emergency", - "value": { - "mva": 165 - } - }, - { - "type": "load-shed", - "value": { - "mva": 170 - } - } ] } -] \ No newline at end of file +] diff --git a/docs/example-narratives/examples/realtime-limit-set-slim.json b/docs/example-narratives/examples/realtime-limit-set-slim.json index 618e772..d08ae0b 100644 --- a/docs/example-narratives/examples/realtime-limit-set-slim.json +++ b/docs/example-narratives/examples/realtime-limit-set-slim.json @@ -2,25 +2,20 @@ { "transmission-facility-id": "line2", "updated-time": "2023-07-12T13:05:43.044267100-07:00", - "values": [ - { - "type": "normal", - "value": { - "mva": 160 + "continuous-operating-limit": { "mva": 160 }, + "emergency-operating-limits": [ + { + "duration-name": "emergency", + "limit": { + "mva": 165 + } + }, + { + "duration-name": "load-shed", + "limit": { + "mva": 170 + } } - }, - { - "type": "emergency", - "value": { - "mva": 165 - } - }, - { - "type": "load-shed", - "value": { - "mva": 170 - } - } ] } ] \ No newline at end of file