up

.spectral.yaml

@@ -53,7 +53,7 @@ rules:
             - required: [example]
 
   stella-pagination-params:
-    description: "Paged GETs must expose limit/cursor parameters"
+    description: "Collection GETs (list/search) must expose limit/cursor parameters"
     message: "Add limit/cursor parameters for paged collection endpoints"
     given: "$.paths[*][get]"
     severity: warn
@@ -63,16 +63,46 @@ rules:
         schema:
           type: object
           properties:
-            parameters:
-              type: array
-              allOf:
-                - contains:
-                    $ref: '#/components/parameters/LimitParam'
-                - contains:
-                    $ref: '#/components/parameters/CursorParam'
+            operationId:
+              type: string
+          allOf:
+            - if:
+                properties:
+                  operationId:
+                    pattern: "([Ll]ist|[Ss]earch|[Qq]uery)"
+              then:
+                required: [parameters]
+                properties:
+                  parameters:
+                    type: array
+                    allOf:
+                      - contains:
+                          anyOf:
+                            - required: ['$ref']
+                              properties:
+                                $ref:
+                                  pattern: 'parameters/LimitParam$'
+                            - required: [name, in]
+                              properties:
+                                name:
+                                  const: limit
+                                in:
+                                  const: query
+                      - contains:
+                          anyOf:
+                            - required: ['$ref']
+                              properties:
+                                $ref:
+                                  pattern: 'parameters/CursorParam$'
+                            - required: [name, in]
+                              properties:
+                                name:
+                                  const: cursor
+                                in:
+                                  const: query
 
   stella-idempotency-header:
-    description: "POST/PUT/PATCH operations on collection/job endpoints should accept Idempotency-Key"
+    description: "State-changing operations returning 201/202 should accept Idempotency-Key headers"
     message: "Add Idempotency-Key header parameter for idempotent submissions"
     given: "$.paths[*][?(@property.match(/^(post|put|patch)$/))]"
     severity: warn
@@ -82,16 +112,40 @@ rules:
         schema:
           type: object
           properties:
+            responses:
+              type: object
             parameters:
               type: array
-              contains:
-                type: object
+          allOf:
+            - if:
                 properties:
-                  name:
-                    const: Idempotency-Key
-                  in:
-                    const: header
-                required: [name, in]
+                  responses:
+                    type: object
+                    anyOf:
+                      - required: ['201']
+                      - required: ['202']
+              then:
+                required: [parameters]
+                properties:
+                  parameters:
+                    type: array
+                    contains:
+                      type: object
+                      properties:
+                        name:
+                          const: Idempotency-Key
+                        in:
+                          const: header
+                      required: [name, in]
+
+  stella-operationId-style:
+    description: "operationId must be lowerCamelCase"
+    given: "$.paths[*][*].operationId"
+    severity: warn
+    then:
+      function: casing
+      functionOptions:
+        type: camel
 
 
   stella-jobs-idempotency-key: