Refactor using yaml merge (#23)

* lint with spectral too

* added summaries

* attempt at a canonical refactoring for HEAD/GET

* local dev config changes

* spelling and linting corrections

* disable step but keep for future use

.github/workflows/lint.yaml

@@ -11,10 +11,11 @@ permissions:
 
 jobs:
   build:
-    name: "Bundle and Build"
+    name: "Redocly Lint"
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      pull-requests: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -25,3 +26,13 @@ jobs:
       - run: >-
           npx --yes @redocly/cli bundle ./docs/_data/openapi-split.yaml -o ./docs/openapi.yaml &&
           npx @redocly/cli lint ./docs/openapi.yaml
+      - name: Redocly API Stats
+        id: api_stats
+        run: npx @redocly/cli stats ./docs/openapi.yaml > stats.txt 2>&1
+      - name: Comment PR with API Stats
+        #if: ${{ github.event.pull_request }}
+        if: ${{ false }}
+        uses: thollander/[email protected]
+        with:
+          comment_tag: api-stats
+          filePath: stats.txt

.github/workflows/owasp.yaml

@@ -24,4 +24,4 @@ jobs:
           node-version: 20
       - run: >-
           npx --yes @redocly/cli bundle ./docs/_data/openapi-split.yaml -o ./docs/openapi.yaml &&
-          npx --yes @stoplight/spectral-cli lint docs/openapi.yaml --ruleset https://unpkg.com/@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs
+          npx --yes @stoplight/spectral-cli lint docs/openapi.yaml --ruleset .spectral.yaml

.spectral.yaml

@@ -0,0 +1,25 @@
+extends:
+  - spectral:oas
+  # note this only covers the 2019 top ten https://github.com/stoplightio/spectral-owasp-ruleset/issues/47
+  - https://unpkg.com/@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs
+rules:
+  # override a couple of rules that erroneously apply to HEAD requests
+  "owasp:api3:2019-define-error-responses-500":
+    message: "Operation is missing {{property}}."
+    description: OWASP API Security recommends defining schemas for all responses, even errors. The 500 describes what happens when a request fails with an internal server error, so its important to define this not just for documentation, but to empower contract testing to make sure the proper JSON structure is being returned instead of leaking implementation details in backtraces.
+    given: $.paths.*[get,put,post,patch,delete].responses
+    then:
+      - field: "500"
+        function: truthy
+      - field: "500.content"
+        function: truthy
+
+  "owasp:api3:2019-define-error-responses-401":
+    message: "Operation is missing {{property}}."
+    description: "OWASP API Security recommends defining schemas for all responses, even errors. The 401 describes what happens when a request is unauthorized, so its important to define this not just for documentation, but to empower contract testing to make sure the proper JSON structure is being returned instead of leaking implementation details in backtraces."
+    given: $.paths.*[get,put,post,patch,delete].responses
+    then:
+      - field: "401"
+        function: truthy
+      - field: "401.content"
+        function: truthy

.vscode/settings.json

@@ -9,8 +9,7 @@
             }
         ]
     },
-    // note this only covers the 2019 top ten https://github.com/stoplightio/spectral-owasp-ruleset/issues/47
-    "spectral.rulesetFile": "https://unpkg.com/@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs",
+    "spectral.rulesetFile": ".spectral.yaml",
     "spectral.validateFiles": [
         "**/docs/openapi.yaml"
     ]

cspell.json

@@ -1,16 +1,23 @@
 {
     "version": "0.2",
-    "ignorePaths": [],
+    "ignorePaths": [
+        ".devcontainer/**"
+    ],
     "dictionaryDefinitions": [],
     "dictionaries": [],
     "words": [
+        "devcontainer",
         "excalidraw",
         "FERC",
+        "ICCP",
         "NERC",
         "openapi",
+        "owasp",
         "redoc",
         "Redocly",
-        "TROLIE"
+        "ruleset",
+        "TROLIE",
+        "Vernova"
     ],
     "ignoreWords": [],
     "import": []

docs/_data/components/headers/ETag-response.yaml

@@ -0,0 +1,34 @@
+ETag:
+  description: >
+    An opaque, unique identifier for a specific version of a resource. The modeled
+    resource state is what is versioned, not the content of any particular
+    representation. The server MUST use a strong validator so that the same ETag
+    is returned regardless of the media type of the representation.
+  schema:
+    additionalProperties: false
+    anyOf:
+      - $ref: ../schemas/hash.yaml
+      - $ref: ../schemas/origin-id.yaml
+
+# it seems redocly can't resolve more than 4 $ref deep, so we will repeat these here
+X-Rate-Limit-Limit:
+  description: The number of allowed requests in the current period
+  schema:
+    type: integer
+    format: int32
+    minimum: 0
+    maximum: 1000
+X-Rate-Limit-Remaining:
+  description: The number of remaining requests in the current period
+  schema:
+    type: integer
+    format: int32
+    minimum: 0
+    maximum: 1000
+X-Rate-Limit-Reset:
+  description: The number of seconds left in the current period
+  schema:
+    type: integer
+    format: int32
+    minimum: 0
+    maximum: 1000

docs/_data/components/headers/ETag.yaml

@@ -1,3 +1,4 @@
+# TODO: delete this and switch to ETag-response.yaml
 description: >
   An opaque, unique identifier for a specific version of a resource. The modeled
   resource state is what is versioned, not the content of any particular

docs/_data/components/headers/X-Rate-Limit-Limit.yaml

@@ -1,3 +1,6 @@
 description: The number of allowed requests in the current period
 schema:
   type: integer
+  format: int32
+  minimum: 0
+  maximum: 1000

docs/_data/components/headers/X-Rate-Limit-Remaining.yaml

@@ -1,3 +1,6 @@
 description: The number of remaining requests in the current period
 schema:
   type: integer
+  format: int32
+  minimum: 0
+  maximum: 1000

docs/_data/components/headers/X-Rate-Limit-Reset.yaml

@@ -1,3 +1,6 @@
 description: The number of seconds left in the current period
 schema:
   type: integer
+  format: int32
+  minimum: 0
+  maximum: 1000

docs/_data/components/headers/rate-limit-hit.yaml

@@ -0,0 +1,31 @@
+X-Rate-Limit-Limit:
+  description: The number of allowed requests in the current period
+  schema:
+    type: integer
+    format: int32
+    minimum: 0
+    maximum: 1000
+X-Rate-Limit-Remaining:
+  description: The number of remaining requests in the current period
+  schema:
+    type: integer
+    format: int32
+    minimum: 0
+    maximum: 1000
+# this would be identical to Retry-After if the latter
+# returns seconds to delay (as opposed to an HTTP date time)
+Retry-After:
+  schema:
+    oneOf:
+      - type: integer
+        format: int32
+        minimum: 0
+        maximum: 60
+        example: 60
+        description: The seconds to delay after the response is received.
+      # TODO: the HTTP spec allows for this but we probably should not support it
+      - type: string
+        pattern: "^[A-Z][a-z]{2}, \\d{2} [A-Z][a-z]{2} \\d{4} \\d{2}:\\d{2}:\\d{2} GMT$"
+        maxLength: 30
+        example: 'Wed, 21 Oct 2022 07:28:00 GMT'
+        description: A date after which to retry.

docs/_data/components/headers/rate-limited.yaml

@@ -0,0 +1,21 @@
+X-Rate-Limit-Limit:
+  description: The number of allowed requests in the current period
+  schema:
+    type: integer
+    format: int32
+    minimum: 0
+    maximum: 1000
+X-Rate-Limit-Remaining:
+  description: The number of remaining requests in the current period
+  schema:
+    type: integer
+    format: int32
+    minimum: 0
+    maximum: 1000
+X-Rate-Limit-Reset:
+  description: The number of seconds left in the current period
+  schema:
+    type: integer
+    format: int32
+    minimum: 0
+    maximum: 1000

docs/_data/components/responses/empty.yaml

@@ -0,0 +1,3 @@
+application/*:
+  schema:
+    $ref: ../schemas/empty.yaml

docs/_data/components/responses/rate-limit-hit-head.yaml

@@ -0,0 +1,3 @@
+description: Too many requests (rate limiting)
+headers:
+  $ref: ../headers/rate-limit-hit.yaml

docs/_data/components/responses/rate-limit-hit.yaml

@@ -0,0 +1,5 @@
+description: Too many requests (rate limiting)
+headers:
+  $ref: ../headers/rate-limit-hit.yaml
+content:
+  $ref: empty.yaml

docs/_data/components/schemas/constants/maximum-periods.yaml

@@ -0,0 +1 @@
+maxItems: 240

docs/_data/components/schemas/constants/maximum-proposals.yaml

@@ -0,0 +1 @@
+maxItems: 10000

docs/_data/components/schemas/entity-id.yaml

@@ -1,5 +1,6 @@
 description: Usually the NERC id of the entity.
 type: string
 maxLength: 10
-pattern: ^[A-Z]{3,10}$
+# I believe SPP uses for some of their market participants who are not NERC registered.
+pattern: ^[A-Z\-]{3,10}$
 example: MISO

docs/_data/components/schemas/forecast-limit-item-detailed.yaml

@@ -4,6 +4,8 @@ properties:
   transmission-facility-id:
     $ref: ./generic-identifier.yaml
   periods:
-    type: array
-    items:
-      $ref: ./forecast-limit-period-detailed.yaml
+    allOf: 
+      -  $ref: ./constants/maximum-periods.yaml
+      - type: array
+        items:
+          $ref: ./forecast-limit-period-detailed.yaml

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

@@ -4,6 +4,8 @@ properties:
   transmission-facility-id:
     $ref: ./generic-identifier.yaml
   periods:
-    type: array
-    items:
-      $ref: ./forecast-limit-period.yaml
+    allOf: 
+      -  $ref: ./constants/maximum-periods.yaml
+      - type: array
+        items:
+          $ref: ./forecast-limit-period.yaml

docs/_data/components/schemas/forecast-limit-set-detailed.yaml

@@ -2,6 +2,6 @@ description: |
   Forecast including provenance information.  
 type: array
 minItems: 0
-maxItems: 50000
+maxItems: 5000
 items:
   $ref: ./forecast-limit-item-detailed.yaml

docs/_data/components/schemas/forecast-proposal-for-segment.yaml

@@ -4,6 +4,8 @@ properties:
   segment-id:
     $ref: ./generic-identifier.yaml
   periods:
-    type: array
-    items:
-      $ref: ./forecast-rating-period.yaml
+    allOf: 
+      - $ref: ./constants/maximum-periods.yaml
+      - type: array
+        items:
+          $ref: ./forecast-rating-period.yaml

docs/_data/components/schemas/forecast-rating-proposal.yaml

@@ -3,6 +3,8 @@ allOf:
   - type: object
     properties:
       ratings:
-        type: array
-        items:
-          $ref: ./forecast-proposal-for-segment.yaml
+        allOf:
+          - $ref: ./constants/maximum-proposals.yaml
+          - type: array
+            items:
+              $ref: ./forecast-proposal-for-segment.yaml

docs/_data/components/schemas/immutable-rating-proposal.yaml

@@ -3,7 +3,7 @@ description: >
   General type for a ratings proposal that is immutable, such as those created
   for real-time.  
 
-  This includes fields generated by the system for such submittals.    
+  This includes fields generated by the system for such proposals.
 
   Filling in these fields before posting may be ignored, or result in a 400
   error from TROLIE.  
@@ -12,7 +12,7 @@ description: >
 
   * A unique, system generated identifier.  
 
-  * The time the proposal was recieved.  
+  * The time the proposal was received.  
 
   * The ratings provider that created the proposal.  
 properties:

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

@@ -1,16 +1,18 @@
 type: object
 description: Given a limit value, a set of data defining the provenance of that limit.
 properties:
-  provenant-proposals:
+  proposals-considered:
     description: |
       Set of IDs of proposals that affect this limit.  
     type: array
+    maxItems: 10
     items:
       $ref: ./generic-identifier.yaml
   temporary-aar-exceptions:
     description: |
       Set of IDs temporary AAR exceptions that affect this limit.  
     type: array
+    maxItems: 10
     items:
       $ref: ./generic-identifier.yaml
   limiting-segment:
@@ -22,6 +24,8 @@ properties:
 
       If not provided, users may assume no override is in place.  
     type: string
+    format: free-text
+    maxLength: 500
   additional-data:
     description: >
       Implementors may use this object to provide freeform extensions with

docs/_data/components/schemas/limit-type-set.yaml

@@ -9,4 +9,6 @@ items:
       $ref: ./generic-identifier.yaml
     description:
       type: string
+      format: free-text
+      maxLength: 1000
       example: Extreme cold winter day, -100 degrees fahrenheit

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

@@ -9,5 +9,5 @@ description: >
   operation.  
 type: string
 maxLength: 20
-pattern: ^[A-Za-z]{3,10}$
+pattern: ^[A-Za-z\-]{3,10}$
 example: normal

docs/_data/components/schemas/limit-value-set.yaml

@@ -11,6 +11,7 @@ description: >
 
   The value of the limits are in units as defined by the X-TROLIE-Limit-Units
   header.  
+maxItems: 10
 items:
   type: object
   properties:

docs/_data/components/schemas/period-start.yaml

@@ -25,6 +25,9 @@ description: >
 type: string
 format: date-time
 maxLength: 25
-pattern: >-
-  ^([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]([0-9]{2}):([0-9]{2}):([0-9]{2})([Zz]|([+-])([0-9]{2}):([0-9]{2}))$
-example: '2025-01-01T03:00:00-05:00'
+
+# Spectral treats format and patterns mutually exclusive.
+#pattern: >-
+#  ^([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]([0-9]{2}):([0-9]{2}):([0-9]{2})([Zz]|([+-])([0-9]{2}):([0-9]{2}))$
+
+example: '2025-07-12T03:00:00-05:00'