diff --git a/docs/_data/components/schemas/array-max-forecast-periods.yaml b/docs/_data/components/schemas/array-max-forecast-periods.yaml index ac5d24d..152dc2e 100644 --- a/docs/_data/components/schemas/array-max-forecast-periods.yaml +++ b/docs/_data/components/schemas/array-max-forecast-periods.yaml @@ -1,48 +1,41 @@ -forecast-limit-item: +forecast-limit-item: &limit type: object additionalProperties: false properties: - transmission-facility-id: - $ref: ./generic-identifier.yaml - periods: &max + resource-id: &id + $ref: ./resource-id.yaml + periods: &periods type: array maxItems: 240 items: - $ref: 'forecast-limit-period.yaml#/forecast-period-snapshot-slim' + $ref: 'forecast-limit-period.yaml#/snapshot-slim' + required: + - resource-id + - periods forecast-limit-item-detailed: - type: object - additionalProperties: false + <<: *limit properties: - transmission-facility-id: - $ref: ./generic-identifier.yaml + resource-id: *id periods: - <<: *max + <<: *periods items: - $ref: 'forecast-limit-period.yaml#/forecast-period-snapshot-detailed' + $ref: 'forecast-limit-period.yaml#/snapshot-detailed' resource-forecast-proposal: - type: object - additionalProperties: false + <<: *limit properties: - resource-id: - $ref: ./generic-identifier.yaml + resource-id: *id periods: - <<: *max + <<: *periods items: - $ref: 'forecast-limit-period.yaml#/forecast-period-proposal' - - required: - - resource-id - - periods + $ref: 'forecast-limit-period.yaml#/proposal' missing-forecast: - type: object - additionalProperties: false + <<: *limit properties: - resource-id: - $ref: ./generic-identifier.yaml + resource-id: *id periods: - <<: *max + <<: *periods items: $ref: ./period-start.yaml diff --git a/docs/_data/components/schemas/array-max-monitored-elements.yaml b/docs/_data/components/schemas/array-max-monitored-elements.yaml index 1b25fe7..dcc8c5f 100644 --- a/docs/_data/components/schemas/array-max-monitored-elements.yaml +++ b/docs/_data/components/schemas/array-max-monitored-elements.yaml @@ -14,7 +14,11 @@ forecast-limits-snapshot: forecast-limits-detailed-snapshot: type: object - description: A snapshot of the forecast for a monitoring set. + description: | + + A detailed snapshot of the forecast for a monitoring set. These details are + meant to support analysis, archival, and troubleshooting. + properties: snapshot-header: $ref: ./headers.yaml#/snapshot-header @@ -116,7 +120,7 @@ forecast-proposal-status: # submits a proposal for a valid resource that they are not # permitted to write to. It should be the same `resource-id` that # the client submitted. - $ref: ./generic-identifier.yaml + $ref: ./resource-id.yaml required: - forecast-provider @@ -168,7 +172,7 @@ realtime-proposal: - type: object properties: resource-id: - $ref: ./generic-identifier.yaml + $ref: ./resource-id.yaml status: $ref: ./proposal-status.yaml - $ref: ./limit-data.yaml diff --git a/docs/_data/components/schemas/array-max-seasons.yaml b/docs/_data/components/schemas/array-max-seasons.yaml index b2161cb..ff12131 100644 --- a/docs/_data/components/schemas/array-max-seasons.yaml +++ b/docs/_data/components/schemas/array-max-seasons.yaml @@ -3,7 +3,7 @@ seasonal-proposals: additionalProperties: false properties: resource-id: - $ref: ./generic-identifier.yaml + $ref: ./resource-id.yaml seasons: &max type: array maxItems: 20 @@ -15,7 +15,7 @@ seasonal-rating-snapshot-item: additionalProperties: false properties: resource-id: - $ref: ./generic-identifier.yaml + $ref: ./resource-id.yaml seasons: <<: *max items: diff --git a/docs/_data/components/schemas/data-provenance.yaml b/docs/_data/components/schemas/data-provenance.yaml index c7ad35a..1ba4a6a 100644 --- a/docs/_data/components/schemas/data-provenance.yaml +++ b/docs/_data/components/schemas/data-provenance.yaml @@ -27,4 +27,3 @@ properties: required: - provider - last-updated - - origin-id diff --git a/docs/_data/components/schemas/forecast-limit-period.yaml b/docs/_data/components/schemas/forecast-limit-period.yaml index e37acab..0454c4a 100644 --- a/docs/_data/components/schemas/forecast-limit-period.yaml +++ b/docs/_data/components/schemas/forecast-limit-period.yaml @@ -9,33 +9,56 @@ period: - period-start - period-end -forecast-period-proposal: +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. + 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. allOf: - $ref: '#/period' - - $ref: ./limit-data.yaml + - $ref: ./limit-proposal.yaml -forecast-period-snapshot-slim: +proposal-considered: + type: object + description: Details a proposal that was considered by the Clearinghouse run. allOf: - - $ref: '#/forecast-period-proposal' + - $ref: '#/proposal' - type: object properties: - updated-time: - $ref: ./timestamp.yaml + source: + $ref: ./data-provenance.yaml + proposal-disposition: + description: | + + Despite a proposal being accepted by TROLIE, the downstream + Clearinghouse logic may still disqualify a proposal. This might + occur if, for example, the upper and lower reasonability limits + are not aligned between TROLIE and the Clearinghouse. To aid + troubleshooting, the specification requires that TROLIE instances + explicitly indicate if the proposal was `Used` in the + determination of the limit or was `Rejected`. + + type: string + enum: + - Used + - Rejected required: - - updated-time + - source + - proposal-disposition + +snapshot-slim: + allOf: + - $ref: '#/period' + - $ref: ./limit-data.yaml -forecast-period-snapshot-detailed: +snapshot-detailed: type: object description: Period detailed limits including provenance allOf: - - $ref: '#/forecast-period-snapshot-slim' + - $ref: '#/snapshot-slim' - $ref: ./limit-provenance.yaml diff --git a/docs/_data/components/schemas/limit-data.yaml b/docs/_data/components/schemas/limit-data.yaml index f037638..f2d3fc5 100644 --- a/docs/_data/components/schemas/limit-data.yaml +++ b/docs/_data/components/schemas/limit-data.yaml @@ -4,42 +4,6 @@ properties: $ref: ./limit.yaml emergency-operating-limits: $ref: ./array-max-emergency-durations.yaml#/limit-value-set - inputs-used: - description: | - - Optional list of quantities used as input to the ratings determination. - The particular information exchange determines which values may be expected - as well as the conventions used to represent those values. This property - is included to prescribe a way to include these inputs but - - type: array - minItems: 1 - maxItems: 50 - items: - type: object - properties: - name: - type: string - format: free-text - maxLength: 50 - value: - type: object - description: > - This could be any value: a bit, float, integer, string, etc. - unit: - type: string - description: | - If the `value` is dimensionless, this property should not be - provided. Since we are not specifying which inputs shall be - provided, we cannot specify a definitive list of units, but - implementors are encouraged to use UnitSymbol from CIM when - appropriate: The CIM may not include appropriate units for - all inputs, e.g., wind speed. - format: unit - maxLength: 50 - required: - - name - - value required: - continuous-operating-limit - emergency-operating-limits diff --git a/docs/_data/components/schemas/limit-proposal.yaml b/docs/_data/components/schemas/limit-proposal.yaml new file mode 100644 index 0000000..a8be1cd --- /dev/null +++ b/docs/_data/components/schemas/limit-proposal.yaml @@ -0,0 +1,41 @@ +type: object +allOf: + - $ref: ./limit-data.yaml + - type: object + properties: + inputs-used: + description: | + + Optional list of quantities used as input to the ratings determination. + The particular information exchange determines which values may be expected + as well as the conventions used to represent those values. This property + is included to prescribe a way to include these inputs. + + type: array + minItems: 1 + maxItems: 50 + items: + type: object + properties: + name: + type: string + format: free-text + maxLength: 50 + value: + type: object + description: > + This could be any value: a bit, float, integer, string, etc. + unit: + type: string + description: | + If the `value` is dimensionless, this property should not be + provided. Since we are not specifying which inputs shall be + provided, we cannot specify a definitive list of units, but + implementors are encouraged to use UnitSymbol from CIM when + appropriate: The CIM may not include appropriate units for + all inputs, e.g., wind speed. + format: unit + maxLength: 50 + required: + - name + - value diff --git a/docs/_data/components/schemas/limit-provenance.yaml b/docs/_data/components/schemas/limit-provenance.yaml index 359e498..1c9d4e4 100644 --- a/docs/_data/components/schemas/limit-provenance.yaml +++ b/docs/_data/components/schemas/limit-provenance.yaml @@ -3,36 +3,61 @@ description: Given a limit value, a set of data defining the provenance of that properties: proposals-considered: description: | - Set of IDs of proposals that affect this limit. + + The forecast proposals provided by the Ratings Providers during the + Forecast Window for this limits snapshot. + type: array - maxItems: 10 + maxItems: &max-proposals 10 items: - $ref: ./generic-identifier.yaml + allOf: + - $ref: 'forecast-limit-period.yaml#/proposal-considered' + - type: object + properties: + resource-id: + $ref: ./resource-id.yaml + temporary-aar-exceptions: description: | - Set of IDs temporary AAR exceptions that affect this limit. + + The temporary AAR exceptions for the facility that were active when this + snapshot was generated. + + type: array + maxItems: *max-proposals + items: + $ref: ./resource-id.yaml + + overrides: type: array - maxItems: 10 + minItems: 0 + maxItems: *max-proposals items: - $ref: ./generic-identifier.yaml - limiting-segment: - $ref: ./generic-identifier.yaml - override-reason: - type: string - description: > - If provided, indicates that this limit was overridden for some reason, the - reason itself. - - If not provided, users may assume no override is in place. - format: free-text - maxLength: 500 + type: object + properties: + override: + $ref: ./limit-data.yaml + override-reason: + type: string + description: + + Indicates that this limit was overridden for some reason, the reason + itself. + + format: free-text + maxLength: 500 + required: + - override + - override-reason + additional-data: - description: > + description: | + Implementors may use this object to provide freeform extensions with - additional traceability / provenance data to be included with the limit. + additional traceability / provenance data to be included with the limit. + Schema of this object is out of scope of the TROLIE specification. - 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/names.yaml b/docs/_data/components/schemas/names.yaml index e3aec4f..379f310 100644 --- a/docs/_data/components/schemas/names.yaml +++ b/docs/_data/components/schemas/names.yaml @@ -1,7 +1,7 @@ type: object properties: resource-id: - $ref: ./generic-identifier.yaml + $ref: ./resource-id.yaml alternate-identifiers: type: array maxItems: 10 diff --git a/docs/_data/components/schemas/realtime-limit-item.yaml b/docs/_data/components/schemas/realtime-limit-item.yaml index 20aece9..284b32a 100644 --- a/docs/_data/components/schemas/realtime-limit-item.yaml +++ b/docs/_data/components/schemas/realtime-limit-item.yaml @@ -2,10 +2,10 @@ type: object allOf: - type: object properties: - transmission-facility-id: - $ref: ./generic-identifier.yaml + resource-id: + $ref: ./resource-id.yaml updated-time: $ref: ./timestamp.yaml - $ref: ./limit-data.yaml required: - - transmission-facility-id \ No newline at end of file + - resource-id \ No newline at end of file diff --git a/docs/_data/components/schemas/resource-id.yaml b/docs/_data/components/schemas/resource-id.yaml new file mode 100644 index 0000000..d21df2a --- /dev/null +++ b/docs/_data/components/schemas/resource-id.yaml @@ -0,0 +1,9 @@ +type: string +description: | + + Contains a unique identifier for an a power system resources, such as a + transmission facility, segment, interface, etc. + +maxLength: 250 +pattern: ^(.){0,250}$ +example: "86753_1_1" diff --git a/docs/_data/components/schemas/temporary-rating.yaml b/docs/_data/components/schemas/temporary-rating.yaml index 42cb7fa..2869258 100644 --- a/docs/_data/components/schemas/temporary-rating.yaml +++ b/docs/_data/components/schemas/temporary-rating.yaml @@ -10,7 +10,7 @@ properties: id: $ref: ./generic-identifier.yaml resource-id: - $ref: ./generic-identifier.yaml + $ref: ./resource-id.yaml start-time: $ref: ./period-start.yaml end-time: diff --git a/docs/example-narratives/examples/forecast-limits-detailed.json b/docs/example-narratives/examples/forecast-limits-detailed.json index 66a2e05..fa29302 100644 --- a/docs/example-narratives/examples/forecast-limits-detailed.json +++ b/docs/example-narratives/examples/forecast-limits-detailed.json @@ -2,7 +2,7 @@ "snapshot-header": { "last-updated": "2023-07-12T16:00:00-07:00", "snapshot-provenance": { - "provider":"X-AMPL", + "provider":"X-AMPL-RC", "last-updated": "2023-07-12T16:00:00-07:00", "origin-id": "//trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00" }, @@ -30,7 +30,7 @@ }, { "name": "LINE1 SEG-X", - "authority": "RC-NERC-ID", + "authority": "X-AMPL-RC", "mrid": "8badf00d" } ] @@ -39,13 +39,13 @@ }, "limits": [ { - "transmission-facility-id": "8badf00d", + "resource-id": "8badf00d", "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"], + "proposals-considered": [], "temporary-aar-exceptions": ["2d8c80e8-f533-4be9-85bf-f7f81eb73d67"], "limiting-segment": "segmentX", "override-reason": "Any reason entered by the operator for an override.", diff --git a/docs/example-narratives/examples/forecast-limits-slim.json b/docs/example-narratives/examples/forecast-limits-slim.json index 6f9a481..5e1a76a 100644 --- a/docs/example-narratives/examples/forecast-limits-slim.json +++ b/docs/example-narratives/examples/forecast-limits-slim.json @@ -39,7 +39,7 @@ }, "limits": [ { - "transmission-facility-id": "8badf00d", + "resource-id": "8badf00d", "periods": [ { "period-start": "2023-07-12T16:00:00-07:00", diff --git a/docs/example-narratives/examples/realtime-limit-set-detailed.json b/docs/example-narratives/examples/realtime-limit-set-detailed.json index b445225..978430e 100644 --- a/docs/example-narratives/examples/realtime-limit-set-detailed.json +++ b/docs/example-narratives/examples/realtime-limit-set-detailed.json @@ -2,7 +2,7 @@ "snapshot-header": { "last-updated": "2023-07-12T15:05:43.044267100-07:00", "snapshot-provenance": { - "provider": "X-AMPL", + "provider": "X-AMPL-RC", "last-updated": "2023-07-12T15:05:43.044267100-07:00", "origin-id": "//trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00" }, @@ -39,10 +39,8 @@ }, "limits": [ { - "transmission-facility-id": "line2", - "proposals-considered": [ - "c386503e-ae8f-46e7-8fcf-bdee30f4f56b" - ], + "resource-id": "line2", + "proposals-considered": [], "temporary-aar-exceptions": [ "2d8c80e8-f533-4be9-85bf-f7f81eb73d67" ], diff --git a/docs/example-narratives/examples/realtime-limit-set-slim.json b/docs/example-narratives/examples/realtime-limit-set-slim.json index bb3c812..f3066be 100644 --- a/docs/example-narratives/examples/realtime-limit-set-slim.json +++ b/docs/example-narratives/examples/realtime-limit-set-slim.json @@ -39,7 +39,7 @@ }, "limits": [ { - "transmission-facility-id": "8badf00d", + "resource-id": "8badf00d", "updated-time": "2023-07-12T13:05:43.044267100-07:00", "continuous-operating-limit": { "mva": 160