add snapshot-header to snapshots, update examples

docs/_data/components/schemas/array-max-monitored-elements.yaml

@@ -1,16 +1,28 @@
-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-limits-snapshot:
+  type: object
+  description: A snapshot of the forecast for a monitoring set.
+  properties:
+    snapshot-header:
+      $ref: ./headers.yaml#/snapshot-header
+    limits: &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
-  description: Forecast including provenance information.
-  items:
-    $ref: 'array-max-forecast-periods.yaml#/forecast-limit-item-detailed'
+forecast-limits-detailed-snapshot:
+  type: object
+  description: A snapshot of the forecast for a monitoring set.
+  properties:
+    snapshot-header:
+      $ref: ./headers.yaml#/snapshot-header
+    limits:
+      <<: *max
+      description: Forecast including provenance information.
+      items:
+        $ref: 'array-max-forecast-periods.yaml#/forecast-limit-item-detailed'
 
 named-power-system-objects:
   <<: *max
@@ -22,7 +34,7 @@ forecast-proposal:
   type: object
   properties:
     proposal-header:
-      $ref: ./rating-proposal-header.yaml
+      $ref: ./headers.yaml#/proposal-header
     ratings:
       <<: *max
       description: Forecasted Ratings
@@ -38,23 +50,35 @@ missing-forecast-rating-set:
   items:
     $ref: 'array-max-forecast-periods.yaml#/missing-forecast'
 
-realtime-limit-set:
-  <<: *max
-  description: Real-time limits
-  items:
-    $ref: ./realtime-limit-item.yaml
+realtime-limits-snapshot:
+  type: object
+  description: A snapshot of the realtime limits for a monitoring set.
+  properties:
+    snapshot-header:
+      $ref: ./headers.yaml#/snapshot-header
+    limits:
+      <<: *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
+realtime-limits-detailed-snapshot:
+  type: object
+  description: A snapshot of the realtime limits for a monitoring set.
+  properties:
+    snapshot-header:
+      $ref: ./headers.yaml#/snapshot-header
+    limits:
+      <<: *max
+      description: Real-time limits including provenance.
+      items:
+        $ref: ./realtime-limit-item-detailed.yaml
 
 realtime-proposal:
   type: object
   properties:
     proposal-header:
-      $ref: ./rating-proposal-header.yaml
+      $ref: ./headers.yaml#/proposal-header
     ratings:
       <<: *max
       description: Real-Time Ratings Proposals
@@ -71,8 +95,15 @@ seasonal-rating-proposal:
           <<: *max
           items:
             $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
+  type: object
+  description: A snapshot of the realtime limits for a monitoring set.
+  properties:
+    snapshot-header:
+      $ref: ./headers.yaml#/snapshot-header
+    limits:
+      <<: *max
+      description: Seasonal rating snapshot
+      items:
+        $ref: ./array-max-seasons.yaml#/seasonal-rating-snapshot-item

docs/_data/components/schemas/array-max-seasons.yaml

@@ -14,9 +14,9 @@ seasonal-rating-snapshot-item:
   type: object
   additionalProperties: false
   properties:
-    transmission-facility-id:
+    resource-id:
       $ref: ./generic-identifier.yaml
     seasons:
       <<: *max
       items:
-        $ref: ./seasonal-rating-snapshot-value.yaml
+        $ref: ./seasonal-rating-snapshot-value.yaml

docs/_data/components/schemas/headers.yaml

@@ -0,0 +1,48 @@
+proposal-header:
+  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
+
+snapshot-header:
+  properties:
+    last-updated:
+      $ref: ./timestamp.yaml
+    snapshot-provider:
+      $ref: ./entity-id.yaml
+    power-system-objects:
+      $ref: ./array-max-monitored-elements.yaml#/named-power-system-objects
+    default-emergency-durations:
+      $ref: ./array-max-emergency-durations.yaml#/emergency-durations
+  required:
+    - last-updated
+    - snapshot-provider
+    - power-system-objects

docs/_data/openapi-split.yaml

@@ -320,6 +320,9 @@ components:
         "application/problem+json":
           schema:
             $ref: '#/components/schemas/problem'
+        "application/json": # helpful errors when the request doesn't specify a TROLIE media type
+          schema:
+            $ref: '#/components/schemas/problem'
     '401-empty':
       <<: *unauthorized
       content: &empty
@@ -334,7 +337,7 @@ components:
       content: *empty
     '406-empty':
       <<: *not-acceptable
-      content: *empty
+      content: *problem
     '410-empty':
       <<: *gone
       content: *empty

docs/_data/paths/limits_forecast-snapshot.yaml

@@ -24,33 +24,30 @@ get:
   description: >
 
     Obtain the Limits Forecast the Transmission Provider is currently using in
-    Operations, relative to the current time. Clients SHOULD perform
-    Conditional `GET` using the `If-None-Match` header and the `ETag` of a
-    previous `GET` response. This operation uses media types to control
-    verbosity of the data fetched. The default media type
-    (application/vnd.trolie.forecast-limit-set-slim.v1+json) simply includes
+    Operations, relative to the current time. Clients SHOULD perform Conditional
+    `GET` using the `If-None-Match` header and the `ETag` of a previous `GET`
+    response. This operation uses media types to control verbosity of the data
+    fetched. The default media type,
+    `application/vnd.trolie.forecast-limits-snapshot.v1+json`, simply includes
     the rating data. For applications that need it, the media type
-    application/vnd.trolie.forecast-limit-set-detailed.v1+json may be requested,
-    which also references the source proposals used to generate the snapshot, as
-    well as reporting data from the ratings clearing process.
+    `application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json` may be
+    requested, which also references the source proposals used to generate the
+    snapshot, as well as reporting data from the ratings clearing process.
 
   responses:
     '200':
       description: The requested operating forecast snapshot is returned.
       content:
-        application/vnd.trolie.forecast-limit-set-slim.v1+json:
+        application/vnd.trolie.forecast-limits-snapshot.v1+json:
           schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set"
+            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limits-snapshot"
           example:
             $ref: '../../example-narratives/examples/forecast-limits-slim.json'
-        application/vnd.trolie.forecast-limit-set-detailed.v1+json:
+        application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json:
           schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set-detailed"
+            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limits-detailed-snapshot"
           example:
             $ref: "../../example-narratives/examples/forecast-limits-detailed.json"
-        application/json:
-          schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set"
       headers:
         $ref: '../openapi-split.yaml#/components/responses/200/headers'
     '304':

docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml

@@ -28,40 +28,16 @@ get:
     '200':
       description: The requested operating forecast snapshot is returned.
       content:
-        application/vnd.trolie.forecast-limit-set-slim.v1+json:
+        application/vnd.trolie.forecast-limits-snapshot.v1+json:
           schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set"
+            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limits-snapshot"
           example:
             $ref: "../../example-narratives/examples/forecast-limits-slim.json"
-        application/vnd.trolie.forecast-limit-set-detailed.v1+json:
+        application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json:
           schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set-detailed"
+            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limits-detailed-snapshot"
           example:
-            - 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
-                  temporary-aar-exceptions:
-                    - 2d8c80e8-f533-4be9-85bf-f7f81eb73d67
-                  limiting-segment: segmentX
-                  override-reason: Any reason entered by the operator for an override.
-                  additional-data:
-                    vendor-specific-data: {}
-                  continuous-operating-limit:
-                    mva: 160
-                  emergency-operating-limits:
-                    - duration-name: emergency
-                      limit:
-                        mva: 165
-                    - duration-name: load-shed
-                      limit:
-                        mva: 170
-        application/json:
-          schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set"
+            $ref: "../../example-narratives/examples/forecast-limits-detailed.json"
       headers:
         $ref: '../openapi-split.yaml#/components/responses/200/headers'
 

docs/_data/paths/limits_realtime-snapshot.yaml

@@ -27,19 +27,16 @@ get:
     '200':
       description: The System Operating Limits snapshot is returned.
       content:
-        application/vnd.trolie.realtime-limit-set-slim.v1+json:
+        application/vnd.trolie.realtime-limits-snapshot.v1+json:
           schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limit-set"
+            $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limits-snapshot"
           example:
             $ref: '../../example-narratives/examples/realtime-limit-set-slim.json'
-        application/vnd.trolie.realtime-limit-set-detailed.v1+json:
+        application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json:
           schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limit-set-detailed"
+            $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limits-detailed-snapshot"
           example:
               $ref: '../../example-narratives/examples/realtime-limit-set-detailed.json'
-        application/json:
-          schema:
-            $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limit-set"
       headers:
         $ref: '../openapi-split.yaml#/components/responses/200/headers'
     '304':

docs/_data/paths/seasonal-ratings_snapshot.yaml

@@ -29,19 +29,7 @@ get:
           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'
-                  continuous-operating-limit:
-                    mva: 160
-                  emergency-operating-limits:
-                    - duration-name: emergency
-                      limit:
-                        mva: 165
-                    - duration-name: load-shed
-                      limit:
-                        mva: 170
+            $ref: '../../example-narratives/examples/seasonal-limits-snapshot.json'
         application/json:
           schema: *seasonal-rating-snapshot
       headers:

docs/concepts.md

@@ -7,6 +7,8 @@ nav_order: 2
 
 Before reviewing examples, users may benefit from a basic understanding of the key constructs used by the TROLIE APIs.  Definitions of these concepts are included here.  
 
+![UML concept model](<images/data model.excalidraw.png>)
+
 ## Transmission Facilities
 A Transmission Facility is a logical part of the electrical network that may have a rating, whether simply seasonal or an AAR.  This most often represents a transmission line, but could also include transformers and other large pieces of equipment, or perhaps even logical points on the network such as interfaces.  Most importantly, these are points at which transmission providers need rating values to operate against.