add provenance (source metadata) to snapshots

* `last-updated` has been moved into data-provenance.yaml along with provider
* instead of calling it "document level provenance", I've labeled that info simply `source`
* require it for both requests and responses
* maintain a separate header schema for the snapshot from the proposal but reuse the proposal header schema

cspell.json

@@ -25,6 +25,6 @@
         ,"Vernova"
         ,"SCADA"
     ],
-    "ignoreWords": [],
+    "ignoreWords": ["AMPL"],
     "import": []
 }

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

@@ -0,0 +1,30 @@
+type: object
+description: |
+
+  Provides information about where the associated representation came from. *No
+  functional aspects of the exchange are contingent upon this data.* However,
+  this information is meant to support debugging and application support use
+  cases, so it is required, and implementors are encouraged to provide
+  meaningful values.
+
+  * `provider` identifies that entity, e.g., a Ratings Provider or Clearinghouse
+    Provider, that created the object. The `provider`'s NERC id is recommended.
+  * `last-updated` indicates the wall-clock time at the `provider` when the
+    object was last modified. N.b. this is not when the message
+    describing the object was sent or received, i.e., implementors should not
+    simply insert the current timestamp here when preparing the object serialization.
+  * `origin-id` is the identifier used by the `provider` to uniquely nominate
+    the object. It is recommended but not required that this be a URI.
+
+properties:
+  provider:
+    $ref: ./entity-id.yaml
+  last-updated:
+    $ref: ./timestamp.yaml
+  origin-id:
+    $ref: ./generic-identifier.yaml
+
+required:
+  - provider
+  - last-updated
+  - origin-id

docs/_data/components/schemas/generic-identifier.yaml

@@ -1,4 +1,11 @@
 type: string
+description: |
+
+  Contains a unique identifier for an object. Where practicable, using a URI is
+  generally recommended. However there is no functionality defined by TROLIE
+  that is contingent upon the properties or structure of a `generic-identifier`;
+  they are effectively opaque in the exchange.
+
 maxLength: 100
-pattern: ^(.){0,100}$
-example: fded654c-64f5-4db9-9467-8937d2b3f027
+pattern: ^(.){0,500}$
+example: "//trolie.example.com/limits/forecast-snapshot/2025-07-05T01:00:00-0500"

docs/_data/components/schemas/headers.yaml

@@ -1,48 +1,29 @@
-proposal-header:
+proposal-header: &header
   type: object
-  description: >
-    General type for ratings proposal that is mutable over time, such as forecasts
-    and seasonal ratings.  
+  description: |
 
-    Like the immutable proposal, it includes general fields created by the
-    system.  
+    For simplicity, a single Proposal media type is used for both requests and
+    responses. The `provenance` object populated by the Ratings Provider in a
+    request. The Clearinghouse implementation may record this information, but
+    the response `provenance` should reflect the appropriate metadata from the
+    Clearinghouse Provider's perspective. Concretely, in a request
+    `provenance.provider` should be the Ratings Provider and in a response the
+    `provenance.provider` should be the Clearinghouse Provider.
 
-    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
+    source:
+      $ref: ./data-provenance.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:
+    - source
     - 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
+  <<: *header
+  description: Details about the snapshot provided by the Clearinghouse provider.

docs/example-narratives/examples/forecast-limits-detailed.json

@@ -1,7 +1,10 @@
 {
     "snapshot-header": {
-        "last-updated": "2023-07-12T16:00:00-07:00",
-        "snapshot-provider": "X-RC",
+        "source": {
+            "provider":"X-RC",
+            "last-updated": "2024-08-05T10:00:01-07:00",
+            "origin-id": "//trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00"
+        },
         "default-emergency-durations": [
             {
                 "name": "lte",

docs/example-narratives/examples/forecast-limits-slim.json

@@ -1,7 +1,10 @@
 {
     "snapshot-header": {
-        "last-updated": "2023-07-12T16:00:00-07:00",
-        "snapshot-provider": "X-RC",
+        "source": {
+            "last-updated": "2023-07-12T16:00:00-07:00",
+            "provider":"X-RC",
+            "origin-id": "//trolie.example.com/limits/forecast-snapshot/2025-07-05T01:00:00-0500"
+        },
         "default-emergency-durations": [
             {
                 "name": "lte",

docs/example-narratives/examples/forecast-ratings-proposal-get.json

@@ -1,7 +1,10 @@
 {
   "proposal-header": {
-    "last-updated": "2023-07-12T15:05:43.044267100-07:00",
-    "ratings-provider": "UTILITY-A",
+    "source": {
+      "last-updated": "2023-07-12T15:05:43.044267100-07:00",
+      "provider": "UTILITY-A",
+      "origin-id": "5aeacb25-9b65-4738-8a00-ac10afa63640"
+    },
     "default-emergency-durations": [
       {
         "name": "lte",

docs/example-narratives/examples/forecast-ratings-proposal-patch.json

@@ -1,5 +1,10 @@
 {
   "proposal-header" : {
+    "source": {
+      "last-updated": "2023-07-12T15:05:43.044267100-07:00",
+      "provider": "UTILITY-A",
+      "origin-id": "5aeacb25-9b65-4738-8a00-ac10afa63640"
+    },
     "default-emergency-durations": [
       { "name": "emergency", "duration-minutes": 60}
     ],

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

@@ -1,7 +1,10 @@
 {
   "snapshot-header": {
-    "last-updated": "2023-07-12T16:00:00-07:00",
-    "snapshot-provider": "X-RC",
+    "source": {
+      "last-updated": "2023-07-12T15:05:43.044267100-07:00",
+      "provider": "X-AMPL",
+      "origin-id": "//trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00"
+    },
     "default-emergency-durations": [
       {
         "name": "lte",

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

@@ -1,7 +1,10 @@
 {
     "snapshot-header": {
-        "last-updated": "2023-07-12T16:00:00-07:00",
-        "snapshot-provider": "X-RC",
+        "source": {
+        "last-updated": "2023-07-12T15:05:43.044267100-07:00",
+        "provider": "X-AMPL",
+        "origin-id": "//trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00"
+        },
         "default-emergency-durations": [
             {
                 "name": "lte",

docs/example-narratives/examples/seasonal-limits-snapshot.json

@@ -1,7 +1,10 @@
 {
     "snapshot-header": {
-        "last-updated": "2023-07-12T16:00:00-07:00",
-        "snapshot-provider": "X-RC",
+        "source": {
+            "last-updated": "2023-07-12T15:05:43.044267100-07:00",
+            "provider": "X-AMPL",
+            "origin-id": "//trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00"
+        },
         "default-emergency-durations": [
             {
                 "name": "lte",