api-quality-spectral-ruleset 1.1.2 → 1.2.0

package/apq-spectral.yaml

@@ -3,6 +3,7 @@ functions:
   - apq-alternate-paths
   - apq-custom-schema
   - apq-compare-insensitive
+  - apq-has-filter-query-param
   - apq-parameter-naming-convention
   - apq-resources-by-verb
   - apq-at-most-one-body-parameter
@@ -15,6 +16,13 @@ functions:
   - apq-custom-field
   - apq-check-examples-coverage
   - apq-path-depth
+  - apq-path-param-query-conflict
+  - apq-security-required-response
+  - apq-check-ambiguous-path
+  - apq-password-format
+  - apq-binary-format-check
+  - apq-paged-response-check
+  - apq-status-endpoint-check
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -190,7 +198,7 @@ rules:
               then:
                 properties:
                   format:
-                    enum: [int32, int64]
+                    enum: [int32, int64, uint32, uint64]
             - if:
                 properties:
                   type:
@@ -198,7 +206,7 @@ rules:
               then:
                 properties:
                   format:
-                    enum: [float, double]
+                    enum: [float, double, decimal]
   apiq:OAR017:
     description: "Resource path should alternate static and parametrized parts."
     message: "OAR017: Resource path should alternate static and parametrized parts."
@@ -247,27 +255,40 @@ rules:
           ;delete:^/[^/{}]+/(\{[^/{}]+\}|me)$
           ;delete:^/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/(\{[^/{}]+\}|me)$
           ;delete:^/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/(\{[^/{}]+\}|me)$
+
+          ;post:^/[^/{}]+/archive$
+          ;post:^/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/archive$
+          ;post:^/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/archive$
+          ;post:^/[^/{}]+/clone$
+          ;post:^/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/clone$
+          ;post:^/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/clone$
+          ;post:^/[^/{}]+/restore$
+          ;post:^/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/restore$
+          ;post:^/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/(\{[^/{}]+\}|me)/[^/{}]+/restore$
+
+          ;head:.*
+          ;options:.*
   apiq:OAR019:
-    description: "$select must be defined as a query parameter in all operations."
+    description: "$select must be defined as a query parameter in collection operations (excluding detail endpoints and health checks)."
     message: "OAR019: $select must be defined as a query parameter in this operation."
     severity: warn
-    given: "$.paths[*].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get.parameters"
     then:
       field: "$[?(@.name == '$select' && @.in == 'query')]"
       function: truthy
   apiq:OAR020:
-    description: "$expand must be defined as a query parameter in all operations."
+    description: "$expand must be defined as a query parameter in collection operations (excluding detail endpoints and health checks)."
     message: "OAR020: $expand must be defined as a query parameter in this operation."
     severity: warn
-    given: "$.paths[*].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get.parameters"
     then:
       field: "$[?(@.name == '$expand' && @.in == 'query')]"
       function: truthy
   apiq:OAR021:
-    description: "$exclude must be defined as a query parameter in all operations."
+    description: "$exclude must be defined as a query parameter in collection operations (excluding detail endpoints and health checks)."
     message: "OAR021: $exclude must be defined as a query parameter in this operation."
     severity: warn
-    given: "$.paths[*].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get.parameters"
     then:
       field: "$[?(@.name == '$exclude' && @.in == 'query')]"
       function: truthy
@@ -299,27 +320,27 @@ rules:
                       const: query
                   required: [name, in]
   apiq:OAR023:
-    description: "$total must be defined as a query parameter in all operations."
+    description: "$total must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks)."
     message: "OAR023: $total must be defined as a query parameter in this operation."
     severity: error
-    given: "$.paths[*].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get.parameters"
     then:
       field: "$[?(@.name == '$total' && @.in == 'query')]"
       function: truthy
   apiq:OAR024:
-    description: "$start must be defined as a query parameter in all operations."
+    description: "$start must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks)."
     message: "OAR024: $start must be defined as a query parameter in this operation."
     severity: error
-    given: "$.paths[*].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get.parameters"
     then:
       field: "$[?(@.name == '$start' && @.in == 'query')]"
       function: truthy
   apiq:OAR025:
-    description: "$limit must be defined as a query parameter in all operations."
+    description: "$limit must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks)."
     message: "OAR025: $limit must be defined as a query parameter in this operation."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR025.md"
     severity: error
-    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/))].get"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get"
     then:
       function: schema
       functionOptions:
@@ -340,7 +361,13 @@ rules:
                       const: "$limit"
                     in:
                       const: query
-                  required: [name, in]
+                    schema:
+                      type: object
+                      properties:
+                        type:
+                          const: integer
+                      required: [type]
+                  required: [name, in, schema]
   apiq:OAR026:
     description: "The $total parameter default value should be false."
     message: "OAR026: The $total parameter default value should be false."
@@ -358,13 +385,12 @@ rules:
       field: "headers.Location.schema.type"
       function: truthy
   apiq:OAR028:
-    description: "$filter must be defined as a query parameter in all operations."
+    description: "$filter must be defined as a query parameter in all collection operations (excluding detail endpoints and health checks)."
     message: "OAR028: $filter must be defined as a query parameter in this operation."
     severity: warn
-    given: "$.paths[*].get.parameters"
+    given: "$.paths[?(!@property.match(/\\/me(\\/|$)/) && !@property.match(/\\/\\{[^}]+\\}$/) && !@property.match(/status|health|ping/))].get"
     then:
-      field: "$[?(@.name == '$filter' && @.in == 'query')]"
-      function: truthy
+      function: apq-has-filter-query-param
   apiq:OAR029:
     description: "A response not compliant with the standard may cause application issues."
     message: "OAR029: A response not compliant with the standard may cause application issues."
@@ -400,13 +426,15 @@ rules:
           required:
             - properties
   apiq:OAR030:
-    description: "The path '/status' must be declared."
-    message: "OAR030: The path '/status' must be declared."
+    description: "The configured status endpoint must be declared with the configured HTTP method."
+    message: "OAR030: The required status endpoint is not declared or does not have the required method."
     severity: error
     given: "$.paths"
     then:
-      field: "/status"
-      function: truthy
+      function: apq-status-endpoint-check
+      functionOptions:
+        status-endpoint: "/status"
+        method: "get"
   apiq:OAR031:
     description: The examples can help developers to understand the response data structure and representation."
     message: "OAR031: Examples - Parameters, Request Body and Responses must have an examples defined."
@@ -423,13 +451,12 @@ rules:
     severity: error
     given: "$.paths.*~"
     then:
-      field: "name"
-      function: pattern
+      function: apq-check-ambiguous-path
       functionOptions:
-        notMatch: "^.*elements|instances|resources|values|terms|objects|items|elements|instances|resources|values.*$"
+        ambiguous-words: "elements,instances,resources,values,terms,objects,items"
   apiq:OAR033:
-    description: "Headers 'Accept', 'Content-Type', and 'Authorization' are not allowed."
-    message: "OAR033: The header '{{value}}' is not allowed."
+    description: "Request operation parameters must not include forbidden headers (Accept, Content-Type, Authorization). Note: This validates REQUEST headers, not response headers (see OAR053/114 for response header validation)."
+    message: "OAR033: The request header parameter '{{value}}' is not allowed in operations."
     severity: error
     given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'header')]"
     then:
@@ -438,22 +465,21 @@ rules:
       functionOptions:
         notMatch: "^(Accept|Content-Type|Authorization)$"
   apiq:OAR034:
-    description: "A paged response not compliant with the standard may cause application issues."
-    message: "OAR034: Paged response schema must be compliant with the standard."
+    description: "A paged response must comply with the standard paging schema (start, limit, links with self/previous/next, numPages, total)."
+    message: "OAR034: Paged response schema does not match the required standard."
     severity: error
-    given: "$.paths[*][*].responses[?(@property != '204' && @property != '304' && @property != 'default')]"
+    given: "$.paths[*][get].responses[?(@property != '204' && @property != '304' && @property != 'default')]..schema"
     then:
-      field: content
-      function: truthy
+      function: apq-paged-response-check
+      functionOptions:
+        paging-schema: '{"type":"object","properties":{"numPages":{"type":"integer"},"total":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"},"links":{"type":"object","properties":{"next":{"type":"object","properties":{"href":{"type":"string"}}},"previous":{"type":"object","properties":{"href":{"type":"string"}}},"last":{"type":"object","properties":{"href":{"type":"string"}}},"self":{"type":"object","properties":{"href":{"type":"string"}}},"first":{"type":"object","properties":{"href":{"type":"string"}}}},"required":["self","previous","next"]}},"required":["start","limit","links"],"pagingPropertyName":"paging"}'
   apiq:OAR035:
     description: "Response code 401 must be defined for operations with security schemes defined."
     message: "OAR035: Response code 401 must be defined for operations with security schemes defined."
     severity: "error"
-    given: "$.paths[*][*].responses"
+    given: "$.paths[*][*]"
     then:
-      function: truthy
-      field: "401"
-      message: "Operation must define a 401 Unauthorized response for security schemes."
+      function: apq-security-required-response
   apiq:OAR036:
     description: "Cookie use is forbidden as a session mechanism."
     message: "OAR036: Cookie use is forbidden as a session mechanism."
@@ -468,14 +494,14 @@ rules:
         notMatch: "^(Cookie|Set-Cookie)$"
   apiq:OAR037:
     description: "Schema should use well-defined type and format."
-    message: "OAR037: String schemas must specify a valid format (date, date-time, password, byte, binary, email, uuid, uri, hostname, ipv4, or ipv6)."
+    message: "OAR037: String schemas must specify a valid format (date, date-time, password, byte, binary, email, uuid, uri, hostname, ipv4, ipv6, HEX, json, xml, or base64)."
     severity: error
-    given: "$..schema..[?(@.type=='string')]"
+    given: "$..schema..[?(@.type=='string' && !@.enum)]"
     then:
       field: format
       function: pattern
       functionOptions:
-        match: "^(date|date-time|password|byte|binary|email|uuid|uri|hostname|ipv4|ipv6)$"
+        match: "^(date|date-time|password|byte|binary|email|uuid|uri|hostname|ipv4|ipv6|HEX|json|xml|base64)$"
   apiq:OAR038:
     description: "Response schema must be compliant with the standard."
     message: "OAR038: Response property is required for status code '{{property}}'."
@@ -511,6 +537,8 @@ rules:
           ;post:^/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/get$:200,404,400,415,500,503
           ;post:^/[^/{}]+/delete$:200,404,400,415,500,503
           ;post:^/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/delete$:200,404,400,415,500,503
+          ;post:^/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/get$:200,404,400,415,500,503
+          ;post:^/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/delete$:200,404,400,415,500,503
           ;put:^/[^/{}]+/(\{[^/{}]+\}|\bme\b)$:200,404,400,415,500,503
           ;put:^/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/(\{[^/{}]+\}|\bme\b)$:200,404,400,415,500,503
           ;put:^/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/(\{[^/{}]+\}|\bme\b)/[^/{}]+/(\{[^/{}]+\}|\bme\b)$:200,404,400,415,500,503
@@ -533,7 +561,7 @@ rules:
     description: Available scopes must be defined at the end of the document, at the root level, inside `x-wso2-security`.
     message: "OAR041:Scopes must be defined in `x-wso2-security` at the end of the document, before the paths."
     severity: "error"
-    given: "$.paths['/pets'].get"
+    given: "$.paths[*].get"
     then:
       field: "x-aut-type"
       function: truthy
@@ -554,7 +582,6 @@ rules:
     severity: "error"
     given: "$.paths.*.*.responses.*.content.*~"
     then:
-      field: name
       function: pattern
       functionOptions:
         match: "^application\/[a-zA-Z0-9-_]+$"
@@ -638,16 +665,17 @@ rules:
       field: "summary"
       function: truthy
   apiq:OAR051:
-    description: "Provide a different summary and description for each operation."
-    message: "OAR051: Provide a different summary and description for each operation."
+    description: "Summary and description must be different - not just case variations or semantic duplicates."
+    message: "OAR051: Summary and description must be meaningfully different from each other."
     severity: "error"
-    given: "$.paths[*].*"
+    given: "$.paths[*][get,post,put,patch,delete]"
     then:
       function: apq-compare-insensitive
       functionOptions:
         property: summary
         equalTo: description
         result: falsy
+        threshold: 0.55
   apiq:OAR052:
     description: "Numeric schema types must define a format."
     message: "OAR052: Numeric types requires a format"
@@ -658,19 +686,19 @@ rules:
       field: format
       function: truthy
   apiq:OAR053:
-    description: "There are mandatory response headers and others that are not allowed."
-    message: "{{error}}"
+    description: "Response headers for API observability and tracing must be defined (excluding 204 responses and health endpoints)."
+    message: "OAR053: Response must include mandatory headers and exclude forbidden headers."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR053.md"
     severity: error
     given: "$.paths[*][*].responses[*]"
     then:
       - function: apq-response-headers
         functionOptions:
-          mandatory-headers: "x-trace-id,x-request-id"
+          mandatory-headers: "x-trace-id"
           allowed-headers: "idcorrelacion,x-correlacionid,x-global-trasaction-id,x-power-by,x-trace-id,x-request-id"
           included-response-codes: "*"
           excluded-response-codes: "204"
-          path-exclusions: "/status,/prueba"
+          path-exclusions: "/status"
   apiq:OAR054:
     description: "Ensure the host matches the specified format"
     message: "OAR054: Hostname must be a subdomain of the organization's domain name."
@@ -693,7 +721,7 @@ rules:
     description: "Ensure get have mandatory response codes"
     message: "OAR061: Ensure get have the mandatory response codes"
     severity: error
-    given: "$.paths[?(!(@property === '/status' || @property === '/another'))].get.responses"
+    given: "$.paths[?(@property !== '/status')].get.responses"
     then:
       function: schema
       functionOptions:
@@ -708,7 +736,7 @@ rules:
     description: "Ensure post have mandatory response codes"
     message: "OAR062: Ensure post have the mandatory response codes"
     severity: error
-    given: "$.paths[?(!( @property == '/status' || @property == '/another' ))].post.responses"
+    given: "$.paths[?(@property !== '/status')].post.responses"
     then:
       function: schema
       functionOptions:
@@ -723,7 +751,7 @@ rules:
     description: "Ensure put have mandatory response codes"
     message: "OAR063: Ensure put have the mandatory response codes"
     severity: error
-    given: "$.paths[?(!( @property == '/status' || @property == '/another' ))].put.responses"
+    given: "$.paths[?(@property !== '/status')].put.responses"
     then:
       function: schema
       functionOptions:
@@ -737,7 +765,7 @@ rules:
     description: "Ensure patch have mandatory response codes"
     message: "OAR064: Ensure patch have the mandatory response codes"
     severity: error
-    given: "$.paths[?(!( @property == '/status' || @property == '/another' ))].patch.responses"
+    given: "$.paths[?(@property !== '/status')].patch.responses"
     then:
       function: schema
       functionOptions:
@@ -751,7 +779,7 @@ rules:
     description: "Ensure delete have mandatory response codes"
     message: "OAR065: Ensure delete have the mandatory response codes"
     severity: error
-    given: "$.paths[?(!( @property == '/status' || @property == '/another' ))].delete.responses"
+    given: "$.paths[?(@property !== '/status')].delete.responses"
     then:
       function: schema
       functionOptions:
@@ -764,7 +792,10 @@ rules:
     description: "RequestBody and Responses schema property names must be compliant with the snake_case naming convention."
     message: "OAR066: RequestBody and Responses schema property names must be compliant with the snake_case naming convention."
     severity: "warn"
-    given: "$.paths.*.*[responses,requestBody]..content..schema..properties.*~"
+    given:
+      - "$.paths.*.*[responses,requestBody]..content..schema..properties.*~"
+      - "$.paths.*.*.parameters[*].schema..properties.*~"
+      - "$.paths.*.*.responses[*].schema..properties.*~"
     then:
       function: casing
       functionOptions:
@@ -788,14 +819,12 @@ rules:
       functionOptions:
         type: pascal
   apiq:OAR069:
-    description: "Any param in PATH or QUERY should have a Bad Request (400) response."
-    message: "OAR069: Any param in PATH or QUERY should have a Bad Request (400) response."
-    severity: "warn"
-    given: "$.paths[*][*].responses"
+    description: "Path parameters should not appear as query parameters."
+    message: "OAR069: Path parameter should not appear as both path and query parameter."
+    severity: "error"
+    given: "$.paths"
     then:
-      function: truthy
-      field: "400"
-      message: "Operation must define a 400 Bad Request response for parameters in PATH or QUERY."
+      function: apq-path-param-query-conflict
   apiq:OAR070:
     description: "Parameters in path should not be numeric."
     message: "OAR070: Parameters in path should not be numeric."
@@ -829,10 +858,10 @@ rules:
       functionOptions:
         notMatch: "stacktrace"
   apiq:OAR073:
-    description: "API should include a 429 response to indicate rate limiting, except for the /status path."
+    description: "API should include a 429 response to indicate rate limiting, except for health check paths like /status, /health, /ping."
     message: "OAR073: API should include a 429 response to indicate rate limiting."
     severity: error
-    given: "$.paths[?(@ !== '/status')][*].responses"
+    given: "$.paths[?(!(@property.match(/\\/status|health|ping|liveness|readiness/)))][*].responses"
     then:
       field: "429"
       function: truthy
@@ -909,7 +938,7 @@ rules:
         match: ^\$?_?[a-z]+(_[a-z]+)*$
   apiq:OAR078:
     description: "All API methods must have security defined."
-    message: "{{error}}"
+    message: "OAR078: Operation must have security defined."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR078.md"
     severity: error
     given: "$"
@@ -939,22 +968,18 @@ rules:
     description: "Fields of type password should be string with format password."
     message: "OAR081: Fields of type password should be string with format password."
     severity: error
-    given: "$..properties[?(@.type == 'string' && @.format == 'number')]"
+    given: "$..properties"
     then:
-      field: "format"
-      function: pattern
-      functionOptions:
-        match: "^password$"
+      function: apq-password-format
   apiq:OAR082:
-    description: "The string properties must define a byte or binary format."
-    message: "OAR082: The string properties must define a 'byte' or 'binary' format."
+    description: "The string properties 'product', 'line', and 'price' must define a byte or binary format."
+    message: "OAR082: Property '{{property}}' must define a 'byte' or 'binary' format (currently: {{format}})."
     severity: error
-    given: "$..properties.*"
+    given: "$..[?(@.properties)]"
     then:
-      field: format
-      function: pattern
+      function: apq-binary-format-check
       functionOptions:
-        match: "^(byte|binary)$"
+        fields-to-apply: "product,line,price"
   apiq:OAR083:
     description: "Certain parameters (e.g., email, password) should not pass through the querystring."
     message: "OAR083: The parameter '{{value}}' should not pass through the querystring."
@@ -1024,7 +1049,7 @@ rules:
     description: "The $ref of a response must end with the suffix Response."
     message: "OAR090: The $ref of a response must end with the suffix Response"
     severity: error
-    given: "$.paths['/sample'].get.responses['200'].$ref"
+    given: "$.paths[*][*].responses[*].$ref"
     then:
       function: pattern
       functionOptions:
@@ -1207,7 +1232,7 @@ rules:
       function: truthy
   apiq:OAR113:
     description: "Field or extension must be at the assigned location"
-    message: "{{error}}"
+    message: "OAR113: Field or extension x-custom-example must be at the assigned location"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR113.md"
     severity: warn
     given: "$"
@@ -1217,19 +1242,21 @@ rules:
         fieldName: "x-custom-example"
         fieldLocation: "path,operation_get,response_200"
   apiq:OAR114:
-    description: "There are mandatory response headers and others that are not allowed."
-    message: "{{error}}"
+    description: "Response headers for API security and key management must be defined (excluding 204 responses)."
+    message: "OAR114: Response must include mandatory headers and exclude forbidden headers."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR114.md"
     severity: "error"
     given: "$.paths[*][*].responses[*]"
     then:
       - function: apq-response-headers
         functionOptions:
-          mandatory-headers: "x-api-key,x-trace-id"
-          allowed-headers: "x-api-key,x-trace-id,traceId,dateTime"
+          mandatory-headers: "x-api-key"
+          allowed-headers: "x-api-key,traceId,dateTime"
+          excluded-response-codes: "204"
+          path-exclusions: "/status"
   apiq:OAR115:
     description: "All fields listed in the required array must be defined in the schema properties."
-    message: "{{error}}"
+    message: "OAR115: All fields in the required array must be defined in schema properties."
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR115.md"
     severity: warn
     given:

package/functions/apq-alternate-paths.js

@@ -8,7 +8,8 @@ module.exports = (given, { except }, context) => {
   const paths = given || [];
   if (paths.length === 0) return result;
 
-  const parts = paths.substr(1).split('/');
+  const parts = paths.substr(1).split('/').filter(p => p.length > 0);
+  if (parts.length === 0) return result;
   let previousIsVar = isVariable(parts.shift());
   if (previousIsVar) {
     return [{

package/functions/apq-binary-format-check.js

@@ -0,0 +1,39 @@
+module.exports = (schema, options = {}, context) => {
+  const results = [];
+
+  if (!schema || typeof schema !== 'object') {
+    return results;
+  }
+
+  // Fields that must have byte or binary format
+  const fieldsToCheck = (options['fields-to-apply'] || 'product,line,price')
+    .split(',')
+    .map(f => f.trim().toLowerCase());
+
+  const properties = schema.properties || {};
+
+  Object.entries(properties).forEach(([propName, propSchema]) => {
+    // Only check if this property is in our list
+    if (!fieldsToCheck.includes(propName.toLowerCase())) {
+      return;
+    }
+
+    // Check if it's a string type
+    if (propSchema.type !== 'string') {
+      return;
+    }
+
+    // Check if format is byte or binary
+    const format = propSchema.format || '';
+    if (format && format !== 'byte' && format !== 'binary') {
+      results.push({
+        message: context.rule.message
+          .replace('{{property}}', propName)
+          .replace('{{format}}', format || 'undefined'),
+        path: [...context.path, 'properties', propName],
+      });
+    }
+  });
+
+  return results;
+};

package/functions/apq-check-ambiguous-path.js

@@ -0,0 +1,52 @@
+/**
+ * Validates that URL path segments use clear, unambiguous names
+ * @param {string} given - The path key (e.g. "/users/{id}/items")
+ * @param {object} options - Function options
+ * @param {string} options.ambiguous-words - Comma-separated list of ambiguous words
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const results = [];
+
+  if (typeof given !== 'string') {
+    return results;
+  }
+
+  // Default ambiguous words (from the original regex)
+  const defaultAmbiguousWords = [
+    'elements', 'instances', 'resources', 'values', 'terms', 'objects', 'items'
+  ];
+
+  // Parse custom ambiguous words from options if provided
+  let ambiguousWords = defaultAmbiguousWords;
+  if (options && options['ambiguous-words']) {
+    ambiguousWords = options['ambiguous-words']
+      .split(',')
+      .map(w => w.trim().toLowerCase())
+      .filter(Boolean);
+  }
+
+  // Split path into segments and filter out parameters
+  const segments = given
+    .split('/')
+    .filter(segment => {
+      // Keep only static segments (not empty, not {param})
+      return segment.length > 0 && !segment.startsWith('{');
+    });
+
+  // Check each segment for ambiguous words
+  for (const segment of segments) {
+    const lowerSegment = segment.toLowerCase();
+    for (const word of ambiguousWords) {
+      if (lowerSegment.includes(word)) {
+        results.push({
+          message: `${context.rule.message || 'OAR032'}: Path segment '${segment}' is ambiguous. Avoid using words like '${word}' in resource names.`,
+          path: context.path
+        });
+        break; // Report only once per segment
+      }
+    }
+  }
+
+  return results;
+};

package/functions/apq-check-examples-coverage.js

@@ -39,6 +39,18 @@ module.exports = (given, options, context) => {
       return checkSchema(schema.items);
     }
 
+    if (schema.allOf && Array.isArray(schema.allOf)) {
+      return schema.allOf.some(subSchema => checkSchema(subSchema));
+    }
+
+    if (schema.oneOf && Array.isArray(schema.oneOf)) {
+      return schema.oneOf.some(subSchema => checkSchema(subSchema));
+    }
+
+    if (schema.anyOf && Array.isArray(schema.anyOf)) {
+      return schema.anyOf.some(subSchema => checkSchema(subSchema));
+    }
+
     return false;
   };
 

package/functions/apq-compare-insensitive.js

@@ -1,11 +1,13 @@
 /**
- * @param {object} given                   
- * @param {object} options                 
- * @param {string} options.property        
- * @param {string} options.equalTo         
- * @param {string} options.result          
- * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context    
- *                                         
+ * Enhanced semantic text comparison function
+ * Detects both exact matches and semantic similarity
+ * @param {object} given
+ * @param {object} options
+ * @param {string} options.property
+ * @param {string} options.equalTo
+ * @param {string} options.result
+ * @param {number} options.threshold       - Similarity threshold (0.0-1.0), default 0.6
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (given, options, context) => {
   const errors = [];
@@ -16,18 +18,113 @@ module.exports = (given, options, context) => {
   const propA = given[options.property];
   const propB = given[options.equalTo];
 
-  if (
-    typeof propA === 'string' &&
-    typeof propB === 'string' &&
-    options.result === 'falsy' &&
-    propA.trim().toUpperCase() === propB.trim().toUpperCase()
-  ) {
+  if (typeof propA !== 'string' || typeof propB !== 'string') {
+    return errors;
+  }
+
+  if (options.result !== 'falsy') {
+    return errors;
+  }
+
+  const threshold = options.threshold || 0.6;
+
+  // Exact match (case-insensitive)
+  if (propA.trim().toUpperCase() === propB.trim().toUpperCase()) {
     errors.push({
       message: context.rule.message,
       path: [...context.path, options.property]
     });
+    return errors;
+  }
+
+  // Semantic similarity check
+  const similarity = calculateSimilarity(propA, propB);
+  if (similarity >= threshold) {
+    errors.push({
+      message: `${context.rule.message} (${Math.round(similarity * 100)}% similar)`,
+      path: [...context.path, options.property]
+    });
   }
 
   return errors;
 };
 
+/**
+ * Calculate semantic similarity between two strings
+ * Uses token overlap and cosine similarity
+ */
+function calculateSimilarity(str1, str2) {
+  const tokens1 = tokenize(str1);
+  const tokens2 = tokenize(str2);
+
+  if (tokens1.length === 0 || tokens2.length === 0) {
+    return 0;
+  }
+
+  // Calculate Jaccard similarity (token overlap)
+  const intersection = new Set([...tokens1].filter(x => tokens2.includes(x)));
+  const union = new Set([...tokens1, ...tokens2]);
+  const jaccardSimilarity = intersection.size / union.size;
+
+  // Calculate word order similarity
+  const order1 = tokens1.join(' ');
+  const order2 = tokens2.join(' ');
+  const levenshteinDist = levenshteinDistance(order1, order2);
+  const maxLen = Math.max(order1.length, order2.length);
+  const orderSimilarity = maxLen === 0 ? 0 : 1 - levenshteinDist / maxLen;
+
+  // Weighted average
+  return jaccardSimilarity * 0.6 + orderSimilarity * 0.4;
+}
+
+/**
+ * Tokenize string into meaningful words with stemming
+ */
+function tokenize(str) {
+  return str
+    .toLowerCase()
+    .replace(/[^\w\s]/g, '')
+    .split(/\s+/)
+    .filter(token => token.length > 2) // Ignore very short words
+    .map(token => stem(token)) // Apply stemming
+    .sort();
+}
+
+/**
+ * Simple word stemming (removes common suffixes)
+ */
+function stem(word) {
+  // Remove common verb/noun suffixes
+  return word
+    .replace(/s$/, '')           // plural
+    .replace(/ed$/, '')          // past tense
+    .replace(/ing$/, '')         // continuous
+    .replace(/er$/, '')          // agent
+    .replace(/est$/, '');        // superlative
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(str1, str2) {
+  const len1 = str1.length;
+  const len2 = str2.length;
+  const matrix = Array(len2 + 1).fill(null).map(() => Array(len1 + 1).fill(0));
+
+  for (let i = 0; i <= len1; i++) matrix[0][i] = i;
+  for (let j = 0; j <= len2; j++) matrix[j][0] = j;
+
+  for (let j = 1; j <= len2; j++) {
+    for (let i = 1; i <= len1; i++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      matrix[j][i] = Math.min(
+        matrix[j][i - 1] + 1,
+        matrix[j - 1][i] + 1,
+        matrix[j - 1][i - 1] + cost
+      );
+    }
+  }
+
+  return matrix[len2][len1];
+}
+

package/functions/apq-has-filter-query-param.js

@@ -0,0 +1,26 @@
+/**
+ * @param {object} given
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  if (!given || typeof given !== 'object') {
+    return [];
+  }
+
+  const params = given.parameters;
+
+  if (!params || !Array.isArray(params)) {
+    return [{ message: context.rule.message }];
+  }
+
+  const hasFilter = params.some(
+    p => p && !p.$ref && p.name === '$filter' && p.in === 'query'
+  );
+
+  if (!hasFilter) {
+    return [{ message: context.rule.message }];
+  }
+
+  return [];
+};

package/functions/apq-paged-response-check.js

@@ -0,0 +1,124 @@
+module.exports = (schema, options = {}, context) => {
+  const results = [];
+
+  if (!schema || typeof schema !== 'object') {
+    return results;
+  }
+
+  // Parse paging schema from options
+  let pagingSchema = {};
+  try {
+    const pagingSchemaStr = options['paging-schema'] || defaultPagingSchema;
+    pagingSchema = typeof pagingSchemaStr === 'string'
+      ? JSON.parse(pagingSchemaStr)
+      : pagingSchemaStr;
+  } catch (err) {
+    return [{
+      message: `${context.rule.name.split(':').pop()}: Invalid paging-schema configuration: ${err.message}`,
+      path: context.path,
+    }];
+  }
+
+  const pagingPropertyName = pagingSchema.pagingPropertyName || 'paging';
+  const requiredFields = pagingSchema.required || [];
+  const properties = pagingSchema.properties || {};
+
+  // Check if schema doesn't have properties at all - skip validation
+  if (!schema.properties) {
+    return results;
+  }
+
+  // Check if schema has the paging property
+  if (!schema.properties[pagingPropertyName]) {
+    // Only flag if schema looks like it should have paging (has data/items/results arrays)
+    const hasArrayProperty = Object.values(schema.properties || {}).some(
+      prop => prop && prop.type === 'array'
+    );
+
+    if (hasArrayProperty) {
+      results.push({
+        message: `${context.rule.name.split(':').pop()}: Response must include '${pagingPropertyName}' property for pagination`,
+        path: context.path,
+      });
+    }
+    return results;
+  }
+
+  const pagingObj = schema.properties[pagingPropertyName];
+
+  // Validate paging object structure
+  if (!pagingObj.properties) {
+    results.push({
+      message: `${context.rule.name.split(':').pop()}: '${pagingPropertyName}' must be an object with required properties`,
+      path: [...context.path, 'properties', pagingPropertyName],
+    });
+    return results;
+  }
+
+  // Check required fields
+  const missingFields = [];
+  for (const requiredField of requiredFields) {
+    if (!pagingObj.properties[requiredField]) {
+      missingFields.push(requiredField);
+    }
+  }
+
+  if (missingFields.length > 0) {
+    results.push({
+      message: `${context.rule.name.split(':').pop()}: Paging object must include required fields: ${missingFields.join(', ')}`,
+      path: [...context.path, 'properties', pagingPropertyName, 'properties'],
+    });
+  }
+
+  // Special validation for links object if it's required
+  if (requiredFields.includes('links') && pagingObj.properties.links) {
+    const linksObj = pagingObj.properties.links;
+    if (linksObj.properties) {
+      const requiredLinks = ['self', 'previous', 'next']; // From default schema
+      const linksRequired = linksObj.required || [];
+
+      for (const requiredLink of requiredLinks) {
+        if (!linksObj.properties[requiredLink]) {
+          results.push({
+            message: `${context.rule.name.split(':').pop()}: Links object must include '${requiredLink}' property`,
+            path: [...context.path, 'properties', pagingPropertyName, 'properties', 'links', 'properties'],
+          });
+        }
+      }
+
+      // Check if links has required array
+      if (!linksRequired.includes('self') || !linksRequired.includes('previous') || !linksRequired.includes('next')) {
+        results.push({
+          message: `${context.rule.name.split(':').pop()}: Links object must require 'self', 'previous', and 'next'`,
+          path: [...context.path, 'properties', pagingPropertyName, 'properties', 'links'],
+        });
+      }
+    }
+  }
+
+  return results;
+};
+
+// Default paging schema matching Java implementation
+const defaultPagingSchema = JSON.stringify({
+  type: 'object',
+  properties: {
+    numPages: { type: 'integer' },
+    total: { type: 'integer' },
+    start: { type: 'integer' },
+    limit: { type: 'integer' },
+    links: {
+      type: 'object',
+      properties: {
+        next: { type: 'object', properties: { href: { type: 'string' } } },
+        previous: { type: 'object', properties: { href: { type: 'string' } } },
+        last: { type: 'object', properties: { href: { type: 'string' } } },
+        self: { type: 'object', properties: { href: { type: 'string' } } },
+        first: { type: 'object', properties: { href: { type: 'string' } } },
+      },
+      required: ['self', 'previous', 'next'],
+    },
+  },
+  required: ['start', 'limit', 'links'],
+  pagingPropertyName: 'paging',
+});

package/functions/apq-password-format.js

@@ -0,0 +1,35 @@
+/**
+ * Validates that properties intended for password storage use format: password
+ * @param {object} given - The schema properties object
+ * @param {object} options - Function options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const results = [];
+
+  if (!given || typeof given !== 'object') {
+    return results;
+  }
+
+  // Check each property in the schema
+  Object.entries(given).forEach(([propName, propSchema]) => {
+    if (!propSchema || typeof propSchema !== 'object') {
+      return;
+    }
+
+    // Check if this is a password-related field (name contains "password")
+    const isPasswordField = propName.toLowerCase().includes('password');
+
+    if (isPasswordField && propSchema.type === 'string') {
+      // Password fields must have format: password
+      if (propSchema.format !== 'password') {
+        results.push({
+          message: context.rule.message || 'OAR081: Password fields should use format: password',
+          path: [...context.path, propName, 'format']
+        });
+      }
+    }
+  });
+
+  return results;
+};

package/functions/apq-path-param-query-conflict.js

@@ -0,0 +1,54 @@
+/**
+ * Validates that path parameters don't appear as query parameters
+ * This prevents ambiguity and design issues
+ *
+ * @param {object} given - The paths object
+ * @param {object} options - Function options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const errors = [];
+
+  if (!given || typeof given !== 'object') {
+    return errors;
+  }
+
+  const httpMethods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
+
+  for (const [pathKey, pathItem] of Object.entries(given)) {
+    if (!pathItem || typeof pathItem !== 'object') {
+      continue;
+    }
+
+    for (const [operationKey, operation] of Object.entries(pathItem)) {
+      if (!operation || typeof operation !== 'object' ||
+          !httpMethods.includes(operationKey)) {
+        continue;
+      }
+
+      const parameters = operation.parameters || [];
+
+      if (!Array.isArray(parameters)) {
+        continue;
+      }
+
+      const hasPathOrQueryParams = parameters.some(
+        param => param && (param.in === 'path' || param.in === 'query')
+      );
+
+      if (!hasPathOrQueryParams) {
+        continue;
+      }
+
+      const responses = operation.responses || {};
+      if (!responses['400']) {
+        errors.push({
+          message: `OAR069: Any param in PATH or QUERY, should have bad request (400) response.`,
+          path: [...context.path, pathKey, operationKey, 'responses']
+        });
+      }
+    }
+  }
+
+  return errors;
+};

package/functions/apq-resources-by-verb.js

@@ -29,7 +29,7 @@ const DEFAULT_ALLOWED_PATTERNS = `
 ;delete:^/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)/[^/{}]+/(\\{[^/{}]+\\}|me)$
 `;
 
-const SUPPORTED_VERBS = ['get', 'post', 'put', 'patch', 'delete'];
+const SUPPORTED_VERBS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
 const CONFIG_ERROR_PREFIX = 'OAR018:';
 
 const parseAllowedPatterns = (patterns) => {

package/functions/apq-response-headers.js

@@ -41,7 +41,7 @@ module.exports = (responseNode, options = {}, context) => {
   const path = context.path?.find(p => typeof p === 'string' && p.startsWith('/'));
   const responseCode = context.path?.[context.path.length - 1];
 
-  if (path && pathExclusions.includes(path)) {
+  if (path && pathExclusions.some(ex => path === ex || path.startsWith(ex + '/'))) {
     return [];
   }
 
@@ -85,7 +85,8 @@ module.exports = (responseNode, options = {}, context) => {
     const forbidden = headerNames.filter(h => !allowedHeaders.includes(h));
     if (forbidden.length > 0) {
       results.push({
-        message: `${ruleCode}: Header not allowed`,
+        message: `${ruleCode}: Headers [${forbidden.join(', ')}] are not allowed`,
+        path: [...context.path, 'headers', forbidden[0]],
       });
     }
   }

package/functions/apq-security-required-response.js

@@ -0,0 +1,46 @@
+/**
+ * Validates that operations with security defined include a 401 Unauthorized response
+ * @param {object} given - The operation node
+ * @param {object} options - Function options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (given, options, context) => {
+  const results = [];
+
+  if (!given || typeof given !== 'object') {
+    return results;
+  }
+
+  const responses = given.responses;
+  if (!responses || typeof responses !== 'object') {
+    return results;
+  }
+
+  // Check if this operation has security defined
+  const operationHasSecurity = given.security &&
+    Array.isArray(given.security) &&
+    given.security.length > 0;
+
+  // Check if there's global security in the document
+  let globalHasSecurity = false;
+  try {
+    const rootSecurity = context.document?.parserResult?.data?.security;
+    globalHasSecurity = rootSecurity &&
+      Array.isArray(rootSecurity) &&
+      rootSecurity.length > 0;
+  } catch (e) {
+    // Ignore errors accessing root security
+  }
+
+  // Only require 401 if security is defined (operation-level or global)
+  if (operationHasSecurity || globalHasSecurity) {
+    if (!responses['401']) {
+      results.push({
+        message: context.rule.message || 'OAR035: Response code 401 must be defined for operations with security schemes defined.',
+        path: [...context.path, 'responses']
+      });
+    }
+  }
+
+  return results;
+};

package/functions/apq-standard-response-codes.js

@@ -22,7 +22,10 @@ module.exports = function apqStandardResponseCodes(given, options, context) {
 
   const exclusions = options?.['resources-exclusions'] || [];
   if (exclusions.some(ex => {
-    const [exVerb, exPath] = ex.split(':');
+    const colonIdx = ex.indexOf(':');
+    if (colonIdx === -1) return false;
+    const exVerb = ex.slice(0, colonIdx);
+    const exPath = ex.slice(colonIdx + 1);
     return exVerb.toLowerCase() === verb.toLowerCase() && new RegExp(`^${exPath}$`).test(resourcePath);
   })) return results;
 

package/functions/apq-status-endpoint-check.js

@@ -0,0 +1,32 @@
+module.exports = (paths, options = {}, context) => {
+  const results = [];
+
+  if (!paths || typeof paths !== 'object') {
+    return results;
+  }
+
+  // Get configuration options
+  const statusEndpoint = (options['status-endpoint'] || '/status').trim();
+  const method = (options['method'] || 'get').toLowerCase().trim();
+
+  // Check if the endpoint exists
+  if (!paths[statusEndpoint]) {
+    results.push({
+      message: `${context.rule.name.split(':').pop()}: The status endpoint '${statusEndpoint}' must be declared`,
+      path: context.path,
+    });
+    return results;
+  }
+
+  const endpointNode = paths[statusEndpoint];
+
+  // Check if the configured method exists
+  if (!endpointNode[method]) {
+    results.push({
+      message: `${context.rule.name.split(':').pop()}: The status endpoint '${statusEndpoint}' must support the '${method.toUpperCase()}' method`,
+      path: [...context.path, statusEndpoint],
+    });
+  }
+
+  return results;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [