From db944468ce62f2e12f40db6b3d76e9710dcccb3d Mon Sep 17 00:00:00 2001 From: Christopher Atkins Date: Wed, 27 Mar 2024 22:36:18 +0000 Subject: [PATCH] updates to limit provenance * new resource-id schema to distinguish power system resources from generic objects in the description / example * allow for multiple overrides per limit * include entire segment rating in considered-proposals * some minor schema refactoring --- .../array-max-emergency-durations.yaml | 4 -- .../schemas/array-max-forecast-periods.yaml | 45 +++++++-------- .../schemas/array-max-monitored-elements.yaml | 4 +- .../components/schemas/array-max-seasons.yaml | 4 +- .../schemas/forecast-limit-period.yaml | 26 +++++++-- .../components/schemas/limit-provenance.yaml | 57 ++++++++++++++----- docs/_data/components/schemas/names.yaml | 2 +- .../schemas/realtime-limit-item.yaml | 6 +- .../_data/components/schemas/resource-id.yaml | 9 +++ .../components/schemas/temporary-rating.yaml | 2 +- .../examples/forecast-limits-detailed.json | 2 +- .../examples/forecast-limits-slim.json | 2 +- .../examples/realtime-limit-set-detailed.json | 2 +- .../examples/realtime-limit-set-slim.json | 2 +- 14 files changed, 104 insertions(+), 63 deletions(-) create mode 100644 docs/_data/components/schemas/resource-id.yaml diff --git a/docs/_data/components/schemas/array-max-emergency-durations.yaml b/docs/_data/components/schemas/array-max-emergency-durations.yaml index f5e2a4e..b47a7e9 100644 --- a/docs/_data/components/schemas/array-max-emergency-durations.yaml +++ b/docs/_data/components/schemas/array-max-emergency-durations.yaml @@ -38,7 +38,3 @@ limit-value-set: duration-name: *emergency-kind-name limit: $ref: ./limit.yaml - - -# TODO: add way to reference emergency-kind-name from limit-provenance.yaml -# or change forecast-limit-period.yaml#/forecast-period-snapshot-detailed to reference a new limit-snapshot.yaml that has the association \ No newline at end of file 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..bdc01f5 100644 --- a/docs/_data/components/schemas/array-max-monitored-elements.yaml +++ b/docs/_data/components/schemas/array-max-monitored-elements.yaml @@ -116,7 +116,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 +168,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/forecast-limit-period.yaml b/docs/_data/components/schemas/forecast-limit-period.yaml index 2eb6f4f..2b46fc2 100644 --- a/docs/_data/components/schemas/forecast-limit-period.yaml +++ b/docs/_data/components/schemas/forecast-limit-period.yaml @@ -9,7 +9,7 @@ period: - period-start - period-end -forecast-period-proposal: +proposal: type: object title: Forecasted Period description: | @@ -23,20 +23,36 @@ forecast-period-proposal: - $ref: '#/period' - $ref: ./limit-proposal.yaml -forecast-period-snapshot-slim: +proposal-considered: + type: object + allOf: + - $ref: '#/proposal' + - type: object + properties: + source: + $ref: ./data-provenance.yaml + proposal-disposition: + type: string + enum: + - Used + - Rejected + required: + - proposal-disposition + +snapshot-slim: allOf: - $ref: '#/period' - $ref: ./limit-data.yaml - type: object properties: - updated-time: + updated-time: #TODO: remove this property??? $ref: ./timestamp.yaml required: - updated-time -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-provenance.yaml b/docs/_data/components/schemas/limit-provenance.yaml index 7eab568..1c9d4e4 100644 --- a/docs/_data/components/schemas/limit-provenance.yaml +++ b/docs/_data/components/schemas/limit-provenance.yaml @@ -2,34 +2,61 @@ type: object description: Given a limit value, a set of data defining the provenance of that limit. properties: proposals-considered: - description: The forecast proposals provided by the Ratings Providers during the Forecast Window for this limits snapshot. + description: | + + The forecast proposals provided by the Ratings Providers during the + Forecast Window for this limits snapshot. + type: array maxItems: &max-proposals 10 items: - $ref: 'forecast-limit-period.yaml#/forecast-period-proposal' + 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: ./generic-identifier.yaml - override-reason: - type: string - description: > - If provided, indicates that this limit was overridden for some reason, the - reason itself. + $ref: ./resource-id.yaml - If not provided, users may assume no override is in place. - format: free-text - maxLength: 500 + overrides: + type: array + minItems: 0 + maxItems: *max-proposals + items: + 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: 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 c300319..fa29302 100644 --- a/docs/example-narratives/examples/forecast-limits-detailed.json +++ b/docs/example-narratives/examples/forecast-limits-detailed.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/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 ec3dd2c..978430e 100644 --- a/docs/example-narratives/examples/realtime-limit-set-detailed.json +++ b/docs/example-narratives/examples/realtime-limit-set-detailed.json @@ -39,7 +39,7 @@ }, "limits": [ { - "transmission-facility-id": "line2", + "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