diff --git a/docs/_data/components/schemas/array-max-monitored-elements.yaml b/docs/_data/components/schemas/array-max-monitored-elements.yaml index 6299185..9ce7329 100644 --- a/docs/_data/components/schemas/array-max-monitored-elements.yaml +++ b/docs/_data/components/schemas/array-max-monitored-elements.yaml @@ -208,7 +208,7 @@ realtime-limits-snapshot: <<: *max description: Real-time limits items: - $ref: ./realtime-limit-item.yaml + $ref: './realtime-limit-item.yaml#/normal' realtime-limits-detailed-snapshot: type: object @@ -220,7 +220,7 @@ realtime-limits-detailed-snapshot: <<: *max description: Real-time limits including provenance. items: - $ref: ./realtime-limit-item-detailed.yaml + $ref: './realtime-limit-item.yaml#/detailed' realtime-limits-snapshot-slim: type: object @@ -243,7 +243,17 @@ realtime-proposal: <<: *max description: Real-Time Ratings Proposals items: - $ref: 'realtime-limit-period.yaml#/proposal' + type: object + description: > + Real-time ratings data for a segment. + allOf: + - type: object + properties: + resource-id: + $ref: ./resource-id.yaml + required: + - resource-id + - $ref: ./limit-proposal.yaml required: - proposal-header diff --git a/docs/_data/components/schemas/forecast-limit-period.yaml b/docs/_data/components/schemas/forecast-limit-period.yaml index 113cf33..f7fb7fe 100644 --- a/docs/_data/components/schemas/forecast-limit-period.yaml +++ b/docs/_data/components/schemas/forecast-limit-period.yaml @@ -23,34 +23,6 @@ proposal: - $ref: '#/period' - $ref: ./limit-proposal.yaml -proposal-considered: - - description: Details a proposal that was considered by the Clearinghouse run. - allOf: - - $ref: '#/proposal' - - type: object - properties: - 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: - - source - - proposal-disposition - snapshot: allOf: - $ref: '#/period' @@ -61,4 +33,4 @@ snapshot-detailed: description: Period detailed limits including provenance allOf: - $ref: '#/snapshot' - - $ref: ./limit-provenance.yaml + - $ref: './limit-provenance.yaml#/forecast' diff --git a/docs/_data/components/schemas/limit-provenance.yaml b/docs/_data/components/schemas/limit-provenance.yaml index 1c9d4e4..db75277 100644 --- a/docs/_data/components/schemas/limit-provenance.yaml +++ b/docs/_data/components/schemas/limit-provenance.yaml @@ -1,63 +1,75 @@ -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. - - type: array - maxItems: &max-proposals 10 - items: - allOf: - - $ref: 'forecast-limit-period.yaml#/proposal-considered' - - type: object - properties: - resource-id: - $ref: ./resource-id.yaml - - temporary-aar-exceptions: - description: | - - 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 - minItems: 0 - maxItems: *max-proposals - items: - type: object - properties: - override: - $ref: ./limit-data.yaml - override-reason: - type: string - description: +forecast: &forecast + type: object + description: Contains the provenance data for a given limit. + properties: &props + proposals-considered: &considered + description: | + + The ratings proposals provided by the Ratings Providers that were + considered when determining the limits of the facility for a specific + period. + + If `resource-id` is not provided for a proposal, the ratings proposal is + assumed to be for the overall facility nominated by the `resource-id` of + this limit. + + If it is provided, it corresponds to the [segment](https://trolie.energy/concepts#segments). + + type: array + maxItems: &max-proposals 10 + items: + $ref: 'proposal-considered.yaml#/forecast' + + temporary-aar-exceptions: + description: | - Indicates that this limit was overridden for some reason, the reason - itself. + The temporary AAR exceptions for the facility that were active when this + snapshot was generated. - format: free-text - maxLength: 500 - required: - - override - - override-reason + type: array + maxItems: *max-proposals + items: + $ref: ./resource-id.yaml - additional-data: - description: | + overrides: + type: array + minItems: 0 + maxItems: *max-proposals + items: + type: object + properties: + override: + $ref: ./limit-data.yaml + override-reason: + type: string + description: - Implementors may use this object to provide freeform extensions with - additional traceability / provenance data to be included with the limit. - Schema of this object is out of scope of the TROLIE specification. + Indicates that this limit was overridden for some reason, the reason + itself. + + format: free-text + maxLength: 500 + required: + - override + - override-reason + + additional-data: + description: | + + Implementors may use this object to provide freeform extensions with + additional traceability / provenance data to be included with the limit. + Schema of this object is out of scope of the TROLIE specification. + + type: object - type: object + required: + - proposals-considered -required: - - proposals-considered +real-time: + <<: *forecast + properties: + <<: *props + proposals-considered: + <<: *considered + items: + $ref: 'proposal-considered.yaml#/real-time' diff --git a/docs/_data/components/schemas/proposal-considered.yaml b/docs/_data/components/schemas/proposal-considered.yaml new file mode 100644 index 0000000..e38db66 --- /dev/null +++ b/docs/_data/components/schemas/proposal-considered.yaml @@ -0,0 +1,38 @@ +provenance: + type: object + properties: + 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 + resource-id: + $ref: ./resource-id.yaml + required: + - source + - proposal-disposition + +forecast: + description: > + Details a proposal that was considered by the Clearinghouse run. + If `resource-id` is not provided, the ratings data is assumed to be for the + overall facility. + allOf: + - $ref: './forecast-limit-period.yaml#/proposal' + - $ref: '#/provenance' +real-time: + allOf: + - $ref: ./limit-proposal.yaml + - $ref: '#/provenance' diff --git a/docs/_data/components/schemas/realtime-limit-item-detailed.yaml b/docs/_data/components/schemas/realtime-limit-item-detailed.yaml index 14816e0..e69de29 100644 --- a/docs/_data/components/schemas/realtime-limit-item-detailed.yaml +++ b/docs/_data/components/schemas/realtime-limit-item-detailed.yaml @@ -1,4 +0,0 @@ -type: object -allOf: - - $ref: ./realtime-limit-item.yaml - - $ref: ./limit-provenance.yaml diff --git a/docs/_data/components/schemas/realtime-limit-item.yaml b/docs/_data/components/schemas/realtime-limit-item.yaml index 247f03f..ec29180 100644 --- a/docs/_data/components/schemas/realtime-limit-item.yaml +++ b/docs/_data/components/schemas/realtime-limit-item.yaml @@ -1,9 +1,16 @@ -type: object -allOf: - - type: object - properties: - resource-id: - $ref: ./resource-id.yaml - - $ref: ./limit-data.yaml -required: - - resource-id \ No newline at end of file +normal: + type: object + allOf: + - type: object + properties: + resource-id: + $ref: ./resource-id.yaml + required: + - resource-id + - $ref: ./limit-data.yaml + +detailed: + type: object + allOf: + - $ref: '#/normal' + - $ref: './limit-provenance.yaml#/real-time' diff --git a/docs/_data/components/schemas/realtime-limit-period.yaml b/docs/_data/components/schemas/realtime-limit-period.yaml deleted file mode 100644 index 070b17c..0000000 --- a/docs/_data/components/schemas/realtime-limit-period.yaml +++ /dev/null @@ -1,14 +0,0 @@ -proposal: - type: object - description: > - Real-time ratings data for a segment. - allOf: - - type: object - properties: - resource-id: - $ref: ./resource-id.yaml - - $ref: ./limit-proposal.yaml - required: - - resource-id - - continuous-operating-limit - - emergency-operating-limits diff --git a/docs/example-narratives/examples/forecast-limits-detailed.json b/docs/example-narratives/examples/forecast-limits-detailed.json index b115a79..b5a41cb 100644 --- a/docs/example-narratives/examples/forecast-limits-detailed.json +++ b/docs/example-narratives/examples/forecast-limits-detailed.json @@ -44,7 +44,42 @@ { "period-start": "2023-07-12T16:00:00-07:00", "period-end": "2023-07-12T17:00:00-07:00", - "proposals-considered": [], + "proposals-considered": [ + { + "resource-id": "8badf00d-UTILITY-A-SEG-id", + "source": { + "last-updated": "2023-07-12T16:00:00-07:00", + "provider": "UTILITY-A", + "origin-id": "8badf00d-UTILITY-A-correlation-id" + }, + "period-start": "2023-07-12T16:00:00-07:00", + "period-end": "2023-07-12T17:00:00-07:00", + "proposal-disposition": "Used", + "continuous-operating-limit": { + "mva": 150 + }, + "emergency-operating-limits": [ + { + "duration-name": "lte", + "limit": { + "mva": 160 + } + }, + { + "duration-name": "ste", + "limit": { + "mva": 165 + } + }, + { + "duration-name": "dal", + "limit": { + "mva": 170 + } + } + ] + } + ], "temporary-aar-exceptions": ["2d8c80e8-f533-4be9-85bf-f7f81eb73d67"], "override-reason": "Any reason entered by the operator for an override.", "additional-data": { diff --git a/docs/example-narratives/examples/realtime-limit-set-detailed.json b/docs/example-narratives/examples/realtime-limit-set-detailed.json index 91a6566..8230940 100644 --- a/docs/example-narratives/examples/realtime-limit-set-detailed.json +++ b/docs/example-narratives/examples/realtime-limit-set-detailed.json @@ -43,9 +43,11 @@ "period-end":"2025-07-12T16:00:00-07:00", "proposals-considered": [ { + "resource-id": "8badf00d-UTILITY-A-SEG-id", "source":{ "last-updated": "2025-07-12T14:10:12-07:00", - "provider": "UTILITY-A" + "provider": "UTILITY-A", + "origin-id": "8badf00d-UTILITY-A-correlation-id" }, "period-start":"2025-07-12T15:00:00-07:00", "period-end":"2025-07-12T16:00:00-07:00", @@ -74,9 +76,11 @@ } ] },{ + "resource-id": "8badf00d-UTILITY-B-SEG-id", "source":{ "last-updated": "2025-07-12T14:10:12-07:00", - "provider": "UTILITY-B" + "provider": "UTILITY-B", + "origin-id": "8badf00d-UTILITY-B-correlation-id" }, "period-start":"2025-07-12T15:00:00-07:00", "period-end":"2025-07-12T16:00:00-07:00",