up

.spectral.yaml

@@ -38,3 +38,76 @@ rules:
     then:
       field: operationId
       function: truthy
+
+  stella-2xx-response-examples:
+    description: "Every 2xx response must include at least one example"
+    message: "Add an example or examples block to 2xx responses"
+    given: "$.paths[*][*].responses[?(@property.match(/^2\\d\\d$/))].content.*"
+    severity: error
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          anyOf:
+            - required: [examples]
+            - required: [example]
+
+  stella-pagination-params:
+    description: "Paged GETs must expose limit/cursor parameters"
+    message: "Add limit/cursor parameters for paged collection endpoints"
+    given: "$.paths[*][get]"
+    severity: warn
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            parameters:
+              type: array
+              allOf:
+                - contains:
+                    $ref: '#/components/parameters/LimitParam'
+                - contains:
+                    $ref: '#/components/parameters/CursorParam'
+
+  stella-idempotency-header:
+    description: "POST/PUT/PATCH operations on collection/job endpoints should accept Idempotency-Key"
+    message: "Add Idempotency-Key header parameter for idempotent submissions"
+    given: "$.paths[*][?(@property.match(/^(post|put|patch)$/))]"
+    severity: warn
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: object
+          properties:
+            parameters:
+              type: array
+              contains:
+                type: object
+                properties:
+                  name:
+                    const: Idempotency-Key
+                  in:
+                    const: header
+                required: [name, in]
+
+
+  stella-jobs-idempotency-key:
+    description: "Orchestrator job submissions must accept Idempotency-Key header"
+    given: "$.paths['/jobs'].post.parameters"
+    severity: warn
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          contains:
+            type: object
+            properties:
+              name:
+                const: Idempotency-Key
+              in:
+                const: header
+            required: [name, in]