Improve limits snapshot details (#96)

* 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
* polishing forecast limit provenance
* enhance descriptions

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

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

@@ -14,7 +14,11 @@ forecast-limits-snapshot:
 
 forecast-limits-detailed-snapshot:
   type: object
-  description: A snapshot of the forecast for a monitoring set.
+  description: |
+
+    A detailed snapshot of the forecast for a monitoring set. These details are
+    meant to support analysis, archival, and troubleshooting.
+
   properties:
     snapshot-header:
       $ref: ./headers.yaml#/snapshot-header
@@ -116,7 +120,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 +172,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

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:

docs/_data/components/schemas/data-provenance.yaml

@@ -27,4 +27,3 @@ properties:
 required:
   - provider
   - last-updated
-  - origin-id

docs/_data/components/schemas/forecast-limit-period.yaml

@@ -9,33 +9,56 @@ period:
     - period-start
     - period-end
 
-forecast-period-proposal:
+proposal:
   type: object
   title: Forecasted Period
   description: |
 
-    A Forecasted Period contains proposed limits for a power system
-    object, e.g., a segment, that were forecasted for a particular Period
-    in a Forecast Window. The status of the proposal as determined by the
-    Clearinghouse is also included.
+    A Forecasted Period contains proposed limits for a power system object,
+    e.g., a segment, that were forecasted for a particular Period in a Forecast
+    Window. The status of the proposal as determined by the Clearinghouse is
+    also included.
 
   allOf:
     - $ref: '#/period'
-    - $ref: ./limit-data.yaml
+    - $ref: ./limit-proposal.yaml
 
-forecast-period-snapshot-slim:
+proposal-considered:
+  type: object
+  description: Details a proposal that was considered by the Clearinghouse run.
   allOf:
-    - $ref: '#/forecast-period-proposal'
+    - $ref: '#/proposal'
     - type: object
       properties:
-        updated-time:
-          $ref: ./timestamp.yaml
+        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:
-        - updated-time
+        - source
+        - proposal-disposition
+
+snapshot-slim:
+  allOf:
+    - $ref: '#/period'
+    - $ref: ./limit-data.yaml
 
-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

docs/_data/components/schemas/limit-data.yaml

@@ -4,42 +4,6 @@ properties:
     $ref: ./limit.yaml
   emergency-operating-limits:
     $ref: ./array-max-emergency-durations.yaml#/limit-value-set
-  inputs-used:
-    description: |
-
-      Optional list of quantities used as input to the ratings determination.
-      The particular information exchange determines which values may be expected
-      as well as the conventions used to represent those values. This property
-      is included to prescribe a way to include these inputs but 
-
-    type: array
-    minItems: 1
-    maxItems: 50
-    items:
-      type: object
-      properties:
-        name:
-          type: string
-          format: free-text
-          maxLength: 50
-        value:
-          type: object
-          description: >
-            This could be any value: a bit, float, integer, string, etc.
-        unit:
-          type: string
-          description: |
-            If the `value` is dimensionless, this property should not be
-            provided. Since we are not specifying which inputs shall be
-            provided, we cannot specify a definitive list of units, but
-            implementors are encouraged to use UnitSymbol from CIM when
-            appropriate: The CIM may not include appropriate units for
-            all inputs, e.g., wind speed.
-          format: unit
-          maxLength: 50
-      required:
-        - name
-        - value
 required:
   - continuous-operating-limit
   - emergency-operating-limits

docs/_data/components/schemas/limit-proposal.yaml

@@ -0,0 +1,41 @@
+type: object
+allOf:
+  - $ref: ./limit-data.yaml
+  - type: object
+    properties:
+      inputs-used:
+        description: |
+
+          Optional list of quantities used as input to the ratings determination.
+          The particular information exchange determines which values may be expected
+          as well as the conventions used to represent those values. This property
+          is included to prescribe a way to include these inputs.
+
+        type: array
+        minItems: 1
+        maxItems: 50
+        items:
+          type: object
+          properties:
+            name:
+              type: string
+              format: free-text
+              maxLength: 50
+            value:
+              type: object
+              description: >
+                This could be any value: a bit, float, integer, string, etc.
+            unit:
+              type: string
+              description: |
+                If the `value` is dimensionless, this property should not be
+                provided. Since we are not specifying which inputs shall be
+                provided, we cannot specify a definitive list of units, but
+                implementors are encouraged to use UnitSymbol from CIM when
+                appropriate: The CIM may not include appropriate units for
+                all inputs, e.g., wind speed.
+              format: unit
+              maxLength: 50
+          required:
+            - name
+            - value

docs/_data/components/schemas/limit-provenance.yaml

@@ -3,36 +3,61 @@ description: Given a limit value, a set of data defining the provenance of that
 properties:
   proposals-considered:
     description: |
-      Set of IDs of proposals that affect this limit.  
+
+      The forecast proposals provided by the Ratings Providers during the
+      Forecast Window for this limits snapshot.
+
     type: array
-    maxItems: 10
+    maxItems: &max-proposals 10
     items:
-      $ref: ./generic-identifier.yaml
+      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: ./resource-id.yaml
+
+  overrides:
     type: array
-    maxItems: 10
+    minItems: 0
+    maxItems: *max-proposals
     items:
-      $ref: ./generic-identifier.yaml
-  limiting-segment:
-    $ref: ./generic-identifier.yaml
-  override-reason:
-    type: string
-    description: >
-      If provided, indicates that this limit was overridden for some reason, the
-      reason itself.
-
-      If not provided, users may assume no override is in place.  
-    format: free-text
-    maxLength: 500
+      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:
   - proposals-considered
-  - limiting-segment

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

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

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"