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
trolie · Mar 27, 2024 · db94446 · db94446
1 parent 5fda9ff
commit db94446
Show file tree

Hide file tree

Showing 14 changed files with 104 additions and 63 deletions.
diff --git 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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
+  - resource-id
diff --git a/docs/_data/components/schemas/resource-id.yaml 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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