Merge pull request #164 from trolie/103-proposals-considered-examples

reconciliation article

cspell.json

@@ -13,10 +13,13 @@
     "dictionaries": [],
     "words": [
         "affordance"
+        ,"affordances"
         ,"auditability"
         ,"brotli"
         ,"CGMES"
         ,"debuggability"
+        ,"derate"
+        ,"derated"
         ,"devcontainer"
         ,"ENTSO"
         ,"excalidraw"

docs/Gemfile.lock

@@ -35,8 +35,9 @@ GEM
       ffi (>= 1.15.0)
     eventmachine (1.2.7)
     execjs (2.9.1)
-    faraday (2.11.0)
+    faraday (2.12.0)
       faraday-net_http (>= 2.0, < 3.4)
+      json
       logger
     faraday-net_http (3.3.0)
       net-http
@@ -211,6 +212,7 @@ GEM
       gemoji (>= 3, < 5)
       html-pipeline (~> 2.2)
       jekyll (>= 3.0, < 5.0)
+    json (2.7.2)
     just-the-docs (0.10.0)
       jekyll (>= 3.8.5)
       jekyll-include-cache

docs/_data/paths/limits_realtime-snapshot.yaml

@@ -23,7 +23,7 @@ get:
           schema:
             $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limits-snapshot"
           example:
-            $ref: '../../example-narratives/examples/realtime-limit-set-slim.json'
+            $ref: '../../example-narratives/examples/realtime-limit-set.json'
         application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json:
           schema:
             $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limits-detailed-snapshot"

docs/example-narratives/examples/realtime-limit-set-detailed.json

@@ -16,7 +16,7 @@
       },
       {
         "name": "dal",
-        "duration-minutes": 15
+        "duration-minutes": 5
       }
     ],
     "power-system-resources": [
@@ -38,8 +38,74 @@
   },
   "limits": [
     {
-      "resource-id": "line2",
-      "proposals-considered": [],
+      "resource-id": "8badf00d",
+      "period-start":"2025-07-12T15:00:00-07:00",
+      "period-end":"2025-07-12T16:00:00-07:00",
+      "proposals-considered": [
+        {
+          "source":{
+            "last-updated": "2025-07-12T14:10:12-07:00",
+            "provider": "UTILITY-A"
+          },
+          "period-start":"2025-07-12T15:00:00-07:00",
+          "period-end":"2025-07-12T16:00:00-07:00",
+          "proposal-disposition": "Used",
+          "continuous-operating-limit": {
+                "mva": 150
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "lte",
+              "limit": {
+                "mva": 165
+              }
+            },
+            {
+              "duration-name": "ste",
+              "limit": {
+                "mva": 170
+              }
+            },
+            {
+              "duration-name": "dal",
+              "limit": {
+                "mva": 180
+              }
+            }
+          ]
+        },{
+          "source":{
+            "last-updated": "2025-07-12T14:10:12-07:00",
+            "provider": "UTILITY-B"
+          },
+          "period-start":"2025-07-12T15:00:00-07:00",
+          "period-end":"2025-07-12T16:00:00-07:00",
+          "proposal-disposition": "Used",
+          "continuous-operating-limit": {
+                "mva": 150
+          },
+          "emergency-operating-limits": [
+            {
+              "duration-name": "lte",
+              "limit": {
+                "mva": 166
+              }
+            },
+            {
+              "duration-name": "ste",
+              "limit": {
+                "mva": 171
+              }
+            },
+            {
+              "duration-name": "dal",
+              "limit": {
+                "mva": 175
+              }
+            }
+          ]
+        }
+      ],
       "temporary-aar-exceptions": [
         "2d8c80e8-f533-4be9-85bf-f7f81eb73d67"
       ],
@@ -66,7 +132,7 @@
         {
           "duration-name": "dal",
           "limit": {
-            "mva": 180
+            "mva": 175
           }
         }
       ]

docs/example-narratives/in-use-realtime-limits.md

@@ -9,7 +9,7 @@ nav_order: 4
 Assuming a MonitoringSet "my-monitoring-set" that contains TransmissionFacilities of interest, then the current in-use real-time limits may be fetched with the following command:
 
 ```bash
-curl -H "Accept: application/vnd.trolie.realtime-limits-slim-snapshot.v1+json" \
+curl -H "Accept: application/vnd.trolie.realtime-limits-snapshot.v1+json" \
 -o output.json \
 "https://trolie.example.com/limits/realtime-snapshot?monitoring-set=my-monitoring-set"
 ```
@@ -20,7 +20,7 @@ they were submitted through TROLIE, through ICCP, or derived by the Transmission
 through some other means.  See the following for an example:
 
 ```json
-{% include_relative examples/realtime-limit-set-slim.json %}
+{% include_relative examples/realtime-limit-set.json %}
 ```
 
 **NOTE**: This query is an example of an HTTP GET.  In addition to curl, the same URL may also be placed in a web browser to see the data.  

docs/example-narratives/reconciliation.md

@@ -0,0 +1,57 @@
+---
+title: Reconciliation with Limit Snapshots
+parent: Usage Examples
+nav_order: 6
+---
+
+# Reconciliation with Limit Snapshots
+
+A central concept in TROLIE is the Clearinghouse. [Ratings
+Providers](../concepts#ratings-provider) propose ratings, and the [Clearinghouse
+Provider](../concepts#clearinghouse-provider) determines operating limits:
+**ratings in, limits out**.
+
+<img src="../images/reconciliation.excalidraw.png" alt="Reconciliation Diagram" width="600">
+
+Crucially, the limits determined by the Clearinghouse Provider may differ from
+the ratings proposed by any individual Ratings Provider.  In this article we
+will briefly describe the API affordances that support reconciliation of limits
+(produced by the Clearinghouse) with the ratings proposed by the Ratings
+Provider. Our example with focus on real-time ratings, but the basic approach
+applies to forecast ratings as well.
+
+We have discussed [Real-Time Rating Submittal](submitting-realtime-ratings) and
+[Querying in-use Real-Time Limits](in-use-realtime-limits) elsewhere. Here we
+will focus on making use of the provenance information in
+`application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json`. For more
+details on the different response messages available in TROLIE, see the article
+on [Media Types](../articles/media-types#read-requests).
+
+
+#### Request
+```bash
+curl -H "Accept: application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json" \
+  $TROLIE_SERVER_URL/limits/realtime-snapshot?monitoring-set=my-monitoring-set
+```
+
+#### Response
+
+Some headers are elided for clarity, but a successful response will start with:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json
+```
+
+Here's an example of the body of the response:
+
+```json
+{% include_relative examples/realtime-limit-set-detailed.json %}
+```
+
+#### Discussion
+
+The `proposals-considered` array contains the salient details of the ratings
+proposals that were considered.  Note that in this example the continuous,
+"lte", and "ste" limits were determined by UTILITY-A but the "dal" limit was set
+by UTILITY-B.