adopt RFC9457 (#26)

* adopt RFC9457 `application/problem+json` * require 422 with that media type for put, post, and patch
trolie · Jan 19, 2024 · 9d86a0e · 9d86a0e
1 parent 09c9da2
commit 9d86a0e
Show file tree

Hide file tree

Showing 19 changed files with 97 additions and 32 deletions.
diff --git a/.spectral.yaml b/.spectral.yaml
@@ -23,3 +23,14 @@ rules:
         function: truthy
       - field: "401.content"
         function: truthy
+
+
+  "should-have-422":
+    message: "Operation is missing {{property}}."
+    description: ""
+    given: $.paths.*[put,post,patch].responses
+    then:
+      - field: "422"
+        function: truthy
+      - field: "422.content.application/problem+json"
+        function: truthy
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -14,7 +14,7 @@ GEM
     addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
     base64 (0.2.0)
-    bigdecimal (3.1.5)
+    bigdecimal (3.1.6)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
@@ -224,7 +224,7 @@ GEM
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    minitest (5.21.1)
+    minitest (5.21.2)
     mutex_m (0.2.0)
     net-http (0.4.1)
       uri

diff --git a/docs/_data/components/responses/content/problem.yaml b/docs/_data/components/responses/content/problem.yaml
@@ -0,0 +1,3 @@
+"application/problem+json":
+  schema:
+    $ref: ../../schemas/problem.yaml
diff --git a/docs/_data/components/responses/unprocessable.yaml b/docs/_data/components/responses/unprocessable.yaml
@@ -0,0 +1,5 @@
+description: Unprocessable Content
+headers:
+  $ref: ../headers/rate-limited.yaml
+content:
+  $ref: ../responses/content/problem.yaml
diff --git a/docs/_data/components/schemas/problem.yaml b/docs/_data/components/schemas/problem.yaml
@@ -0,0 +1,41 @@
+description: See [RFC9457](https://www.rfc-editor.org/rfc/rfc9457#appendix-A).
+type: object
+properties:
+  type:
+    allOf:
+      - $ref: ./uri-reference.yaml
+      - description: |
+          A URI reference that identifies the problem type.
+          See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-type)
+    example: "https://iana.org/assignments/http-problem-types#date"
+  title:
+    allOf:
+      - $ref: ./description.yaml
+      - description: |
+          A short, human-readable summary of the problem type.
+          See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-title)
+
+  status:
+    type: number
+    minimum: 100
+    maximum: 599
+    description: |
+      The HTTP status code generated by the origin server for this occurrence of the problem.
+      See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-status)
+
+  detail:
+    allOf:
+      - $ref: ./description.yaml
+      - description:
+          A human-readable explanation specific to this occurrence of the problem.
+          See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-detail)
+
+  instance:
+    allOf:
+      - $ref: ./uri-reference.yaml
+      - description: |
+          A URI reference that identifies the specific occurrence of the problem.
+          It may or may not yield further information if dereferenced.
+          See [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457#name-status)
+
+required: [ type ]
diff --git a/docs/_data/components/schemas/uri-reference.yaml b/docs/_data/components/schemas/uri-reference.yaml
@@ -0,0 +1,3 @@
+type: string
+format: "uri-reference"
+maxLength: 2048
diff --git a/docs/_data/paths/limits_forecast-snapshot.yaml b/docs/_data/paths/limits_forecast-snapshot.yaml
@@ -22,8 +22,10 @@ head: &head
         $ref: ../components/headers/ETag-response.yaml
     '400': &malformed
       description: Malformed request, based on misuse of filters.
+      content:
+        $ref: ../components/responses/content/problem.yaml
       headers: &rate-limited
-        $ref: ../components/headers/rate-limit-hit.yaml
+        $ref: ../components/headers/rate-limited.yaml
     '401': &unauthorized
       description: Unauthorized
       headers: *rate-limited
@@ -39,9 +41,6 @@ head: &head
     '410': &gone
       description: Gone. The requested forecast should be available in archive.
       headers: *rate-limited
-    '422':
-      description: Unprocessable Content
-      headers: *rate-limited
     '429':
       $ref: ../components/responses/rate-limit-hit-head.yaml
     '500': &unexpected-error
@@ -108,15 +107,7 @@ get:
           schema:
             $ref: ../components/schemas/forecast-limit-set.yaml
     '304': *not-modified
-    '400':
-      <<: *malformed
-      content:
-        application/json:
-          schema:
-            $ref: ../components/schemas/validation-messages.yaml
-        application/vnd.trolie.validation-messages.v1+json:
-          schema:
-            $ref: ../components/schemas/validation-messages.yaml
+    '400': *malformed
     '401':
       <<: *unauthorized
       content: &empty

diff --git a/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml b/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml
@@ -75,23 +75,12 @@ get:
           $ref: ../components/headers/ETag.yaml
     '304':
       $ref: ../components/responses/not-modified.yaml
-    '400': &ref_0
-      description: |
-        Malformed request, based on misuse of filters.
+    '400': &malformed
+      description: Malformed request, based on misuse of filters.
       content:
-        application/json:
-          schema:
-            $ref: ../components/schemas/validation-messages.yaml
-        application/vnd.trolie.validation-messages.v1+json:
-          schema:
-            $ref: ../components/schemas/validation-messages.yaml
-      headers:
-        X-Rate-Limit-Limit:
-          $ref: ../components/headers/X-Rate-Limit-Limit.yaml
-        X-Rate-Limit-Remaining:
-          $ref: ../components/headers/X-Rate-Limit-Remaining.yaml
-        X-Rate-Limit-Reset:
-          $ref: ../components/headers/X-Rate-Limit-Reset.yaml
+        $ref: ../components/responses/content/problem.yaml
+      headers: &rate-limited
+        $ref: ../components/headers/rate-limited.yaml
     '401':
       $ref: ../components/responses/unauthorized.yaml
     '403':
@@ -133,7 +122,7 @@ head:
           $ref: ../components/headers/ETag.yaml
     '304':
       $ref: ../components/responses/not-modified.yaml
-    '400': *ref_0
+    '400': *malformed
     '401':
       $ref: ../components/responses/unauthorized-head.yaml
     '403':

diff --git a/docs/_data/paths/monitoring-sets.yaml b/docs/_data/paths/monitoring-sets.yaml
@@ -170,6 +170,8 @@ post:
     '406': *ref_6
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_7
     '500': &unexpected_error
       $ref: ../components/responses/unexpected-error.yaml

diff --git a/docs/_data/paths/monitoring-sets_{id}.yaml b/docs/_data/paths/monitoring-sets_{id}.yaml
@@ -150,6 +150,8 @@ put:
     '406': *ref_4
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_5
     '500': &unexpected_error
       $ref: ../components/responses/unexpected-error.yaml

diff --git a/docs/_data/paths/rating-proposals_forecasts.yaml b/docs/_data/paths/rating-proposals_forecasts.yaml
@@ -236,6 +236,8 @@ patch:
     '406': *ref_6
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_7
     default: *ref_8
   security:

diff --git a/docs/_data/paths/rating-proposals_forecasts_{ratings-provider}.yaml b/docs/_data/paths/rating-proposals_forecasts_{ratings-provider}.yaml
@@ -189,6 +189,8 @@ patch:
     '406': *ref_4
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_5
     default: *ref_6
   security:

diff --git a/docs/_data/paths/rating-proposals_realtime.yaml b/docs/_data/paths/rating-proposals_realtime.yaml
@@ -212,6 +212,8 @@ post:
     '406': *ref_6
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_7
     default: *ref_8
   security:

diff --git a/docs/_data/paths/rating-proposals_seasonal.yaml b/docs/_data/paths/rating-proposals_seasonal.yaml
@@ -225,6 +225,8 @@ patch:
     '406': *ref_6
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_7
     default: *ref_8
   security:

diff --git a/docs/_data/paths/rating-proposals_seasonal_{ratings-provider}.yaml b/docs/_data/paths/rating-proposals_seasonal_{ratings-provider}.yaml
@@ -183,6 +183,8 @@ patch:
     '406': *ref_4
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_5
     default: *ref_6
   security:

diff --git a/docs/_data/paths/temporary-aar-exceptions.yaml b/docs/_data/paths/temporary-aar-exceptions.yaml
@@ -220,6 +220,8 @@ post:
     '406': *ref_6
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_7
     default: *ref_8
   security:

diff --git a/docs/_data/paths/temporary-aar-exceptions_{id}.yaml b/docs/_data/paths/temporary-aar-exceptions_{id}.yaml
@@ -168,6 +168,8 @@ put:
     '406': *ref_4
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_5
     default: *ref_6
   security: *ref_8
diff --git a/docs/_data/paths/temporary-seasonal-ratings.yaml b/docs/_data/paths/temporary-seasonal-ratings.yaml
@@ -222,6 +222,8 @@ post:
     '406': *ref_6
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_7
     default: *ref_8
   security:

diff --git a/docs/_data/paths/temporary-seasonal-ratings_{id}.yaml b/docs/_data/paths/temporary-seasonal-ratings_{id}.yaml
@@ -166,6 +166,8 @@ put:
     '406': *ref_4
     '413':
       $ref: ../components/responses/payload-too-large.yaml
+    '422':
+      $ref: ../components/responses/unprocessable.yaml
     '429': *ref_5
     default: *ref_6
   security: *ref_8