Monitoring sets (#173)

* Monitoring set API spec 1st pass

* Added monitoringset reconciliation article

* Fixing OWASP errors

* Update docs/_data/openapi-split.yaml

Co-authored-by: Christopher Atkins <57670484+catkins-miso@users.noreply.github.com>
Signed-off-by: Tory McKeag <143734462+getorymckeag@users.noreply.github.com>

* Update docs/articles/examples/RC-A-monitoring-set.json

Co-authored-by: Christopher Atkins <57670484+catkins-miso@users.noreply.github.com>
Signed-off-by: Tory McKeag <143734462+getorymckeag@users.noreply.github.com>

* Update docs/articles/examples/RC-B-monitoring-set.json

Co-authored-by: Christopher Atkins <57670484+catkins-miso@users.noreply.github.com>
Signed-off-by: Tory McKeag <143734462+getorymckeag@users.noreply.github.com>

* First round review comments

* Linting error

* Round 2 review comments

* Update docs/articles/peer-monitoring-sets.md

Co-authored-by: Christopher Atkins <57670484+catkins-miso@users.noreply.github.com>
Signed-off-by: Tory McKeag <143734462+getorymckeag@users.noreply.github.com>

* Set up dedicated default MS path

---------

Signed-off-by: Tory McKeag <143734462+getorymckeag@users.noreply.github.com>
Co-authored-by: Christopher Atkins <57670484+catkins-miso@users.noreply.github.com>

cspell.json

@@ -50,6 +50,10 @@
         ,"adrs"
         ,"puml"
         ,"rgba"
+        ,"MYSUBST"
+        ,"MYSUBSTN"
+        ,"EMSID"
+        ,"CIMMRID"
     ],
     "import": []
 }

docs/_config.yml

@@ -36,6 +36,9 @@ kramdown:
     block:
       line_numbers: true
 
+mermaid:
+  version: "11.3.0"
+
 callouts:
   announcement:
     color: green

docs/_data/components/parameters/monitoring-set-id.yaml

@@ -0,0 +1,12 @@
+name: id
+description: |
+
+  Identity of the associated
+  `monitoring-set`. The identifier for a `monitoring-set` is pre-coordinated,
+  but using the NERC id of the associated Ratings Provider is recommended.
+
+
+in: path
+required: true
+schema:
+  $ref: ../schemas/generic-identifier.yaml

docs/_data/components/schemas/monitoring-set.yaml

@@ -0,0 +1,27 @@
+type: object
+description: |
+  See https://trolie.energy/concepts.html#monitoring-sets for info on the 
+  monitoring set concept in TROLIE.  
+
+  This representation is intended to be enough for consumers to read it and tell where 
+  the monitoring set came from, using metadata such as a source and an optional description.  
+  It also includes the list of resources included in the monitoring set, as well as all
+  their known aliases.  
+
+properties:
+  source:
+    $ref: ./data-provenance.yaml
+  id:
+    $ref: ./generic-identifier.yaml
+  description:
+    type: string
+    format: free-form
+    description: |
+      A freeform text description of this monitoring set
+    maxLength: 1000
+  power-system-resources:
+    $ref: ./array-max-monitored-elements.yaml#/named-power-system-resources
+required:
+- source
+- id
+- power-system-resources

docs/_data/components/schemas/name-type.yaml

@@ -0,0 +1,5 @@
+description: Type of the name being referenced.  Corresponds to the IEC CIM `NameType` concept.
+type: string
+maxLength: 20
+pattern: ^[A-Za-z0-9\-]{3,20}$
+example: EMSID

docs/_data/components/schemas/names.yaml

@@ -11,6 +11,8 @@ properties:
       properties:
         name:
           $ref: ./generic-identifier.yaml
+        type:
+          $ref: ./name-type.yaml
         authority:
           $ref: ./entity-id.yaml
         mrid:

docs/_data/openapi-split.yaml

@@ -170,6 +170,15 @@ tags:
       data feed could be down for some reason.  Therefore, this provides a
       placeholder set of numbers until the AAR data feed is repaired.
 
+  - name: Monitoring Sets
+    description: >      
+      
+      Monitoring Sets are named sets of power system resources that may be used to
+      filter ratings and limits returned by queries against these APIs. How Monitoring
+      Sets are defined is beyond the scope of the TROLIE specification, and it is
+      assumed that the sender and receiver have predefined the appropriate Monitoring
+      Sets.  More on monitoring sets may be found at https://trolie.energy/concepts.html#monitoring-sets
+
   - name: limit-type
     description: <SchemaDefinition schemaRef="#/components/schemas/limit" />
     x-displayName: Limit Type
@@ -182,6 +191,7 @@ x-tagGroups:
     - Seasonal
     - Seasonal Overrides
     - Temporary AAR Exceptions
+    - Monitoring Sets
   - name: Common Schemas
     tags:
     - limit-type
@@ -212,6 +222,11 @@ paths:
   /temporary-aar-exceptions/{id}:
     $ref: paths/temporary-aar-exceptions_{id}.yaml
 
+  /monitoring-sets/{id}:
+    $ref: paths/monitoring-sets_{id}.yaml
+  /default-monitoring-set:
+    $ref: paths/monitoring-sets-default.yaml
+
 
 components:
   responses:
@@ -435,6 +450,7 @@ components:
         clientCredentials:
           tokenUrl: https://no-server/oauth2
           scopes:
+            read:monitoring-sets: Read monitoring sets
             read:forecast-proposals: Read Forecast rating proposals
             read:realtime-proposals: Read real-time rating proposals
             read:seasonal-proposals: Read seasonal rating proposals

docs/_data/paths/monitoring-sets-default.yaml

@@ -0,0 +1,39 @@
+get:
+  operationId: getDefaultMonitoringSet
+  description: &get_desc Obtain the logged in rating provider's default monitoring set.  
+  summary: *get_desc
+  tags: 
+    - Monitoring Sets
+  responses:
+    '200':
+      description: OK
+      content:
+        application/vnd.trolie.monitoring-set.v1+json:
+          schema:
+            $ref: ../components/schemas/monitoring-set.yaml
+          example:
+            $ref: ../../example-narratives/examples/monitoring-set-get.json
+      headers:
+        $ref: '../openapi-split.yaml#/components/responses/204/headers'
+
+    '304':
+      $ref: '../openapi-split.yaml#/components/responses/304'
+    '400': 
+      $ref: '../openapi-split.yaml#/components/responses/400-problem'
+    '401': 
+      $ref: '../openapi-split.yaml#/components/responses/401-empty'
+    '403': 
+      $ref: '../openapi-split.yaml#/components/responses/403-empty'
+    '404': 
+      $ref: '../openapi-split.yaml#/components/responses/404-empty'
+    '406': 
+      $ref: '../openapi-split.yaml#/components/responses/406-empty'
+    '429': 
+      $ref: '../openapi-split.yaml#/components/responses/429-empty'
+    '500': &unexpected-error-empty
+      $ref: '../openapi-split.yaml#/components/responses/500-empty'
+    default: *unexpected-error-empty
+
+  security:
+    - oauth2-primary-flow:
+        - read:monitoring-sets

docs/_data/paths/monitoring-sets_{id}.yaml

@@ -0,0 +1,41 @@
+get:
+  operationId: getMonitoringSet
+  description: &get_desc Obtain a specific monitoring set by identifier.  
+  summary: *get_desc
+  tags: 
+    - Monitoring Sets
+  parameters:
+    - $ref: ../components/parameters/monitoring-set-id.yaml
+  responses:
+    '200':
+      description: OK
+      content:
+        application/vnd.trolie.monitoring-set.v1+json:
+          schema:
+            $ref: ../components/schemas/monitoring-set.yaml
+          example:
+            $ref: ../../example-narratives/examples/monitoring-set-get.json
+      headers:
+        $ref: '../openapi-split.yaml#/components/responses/204/headers'
+
+    '304':
+      $ref: '../openapi-split.yaml#/components/responses/304'
+    '400': 
+      $ref: '../openapi-split.yaml#/components/responses/400-problem'
+    '401': 
+      $ref: '../openapi-split.yaml#/components/responses/401-empty'
+    '403': 
+      $ref: '../openapi-split.yaml#/components/responses/403-empty'
+    '404': 
+      $ref: '../openapi-split.yaml#/components/responses/404-empty'
+    '406': 
+      $ref: '../openapi-split.yaml#/components/responses/406-empty'
+    '429': 
+      $ref: '../openapi-split.yaml#/components/responses/429-empty'
+    '500': &unexpected-error-empty
+      $ref: '../openapi-split.yaml#/components/responses/500-empty'
+    default: *unexpected-error-empty
+
+  security:
+    - oauth2-primary-flow:
+        - read:monitoring-sets

docs/articles/examples/RC-A-monitoring-set.json

@@ -0,0 +1,25 @@
+{
+  "source": {
+    "last-updated": "2025-10-01T12:00:00.044267100-07:00",
+    "provider": "RC-A",
+    "origin-id": "efa3f807-9a5c-4448-8e63-273fb173d183"
+  },  
+  "id":"RC-B",
+  "description": "RC B's Tier 1 facilities",
+  "power-system-resources": [
+    { "resource-id": "e300d2c2-45bb-49f6-a3bc-a3e5d5a30ce6",
+      "alternate-identifiers": [
+        {
+          "name": "MYSUBSTN.LN.12345", 
+          "type": "EMSID",
+          "authority":"RC-A"
+        },
+        {
+          "name": "DLR_OUT_LINE_5742_NORM",
+          "type": "ICCP-NORM-MVA-OUT",
+          "authority": "RC-A"
+        }
+      ]
+    }
+  ]
+}

docs/articles/examples/RC-B-monitoring-set.json

@@ -0,0 +1,25 @@
+{
+  "source": {
+    "last-updated": "2024-10-06T19:23:18-07:00",
+    "provider": "RC-B",
+    "origin-id": "27a6b9ac-db4d-4340-a5ea-080271f7b072"
+  },  
+  "id":"RC-A",
+  "description": "RC A's Tier 1 facilities",
+  "power-system-resources": [
+    { "resource-id": "MYSUBST-LINE-5742",
+      "alternate-identifiers": [
+        {
+          "name": "a276c684-aa68-4799-8c00-44913c61e77a", 
+          "type": "CIMMRID",
+          "authority": "RC-B"
+        },
+        {
+          "name": "DLR_OUT_LINE_5742_NORM",
+          "type": "ICCP-NORM-MVA-OUT",
+          "authority": "RC-A"
+        }
+      ]
+    }
+  ]
+}