Merge pull request #194 from trolie/182-provenance-ids-clarification

clean up resource-id vs origin-id in provenance

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

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'

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'

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'

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

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
+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'

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": {

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",