api-quality-spectral-ruleset 1.6.1 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 <!-- README.md -->
 
-[![Node.js CI](https://github.com/apiaddicts/apquality-spectral/actions/workflows/node.js.yml/badge.svg)](https://github.com/apiaddicts/apquality-spectral/actions/workflows/node.js.yml) ![Coverage](./coverage/badges.svg)
+[![Node.js CI](https://github.com/apiaddicts/apiaddicts-style-guide-spectral/actions/workflows/node.js.yml/badge.svg)](https://github.com/apiaddicts/apiaddicts-style-guide-spectral/actions/workflows/node.js.yml) ![Coverage](./coverage/badges.svg)
 
 # APIAddicts Style Guide Spectral
 
@@ -26,19 +26,19 @@ The Spectral Ruleset requires Node version 14 or later.
 
 You can specify the ruleset directly on the command line:
 
-`spectral lint -r https://raw.githubusercontent.com/apiaddicts/apquality-spectral/refs/heads/main/apq-spectral.yaml <api definition file>`
+`spectral lint -r https://raw.githubusercontent.com/apiaddicts/apiaddicts-style-guide-spectral/refs/heads/main/apq-spectral.yaml <api definition file>`
 
 Or you can create a Spectral configuration file (`.spectral.yaml`) that references the ruleset:
 
 ```yaml
 extends:
-  - https://raw.githubusercontent.com/apiaddicts/apquality-spectral/refs/heads/main/apq-spectral.yaml
+  - https://raw.githubusercontent.com/apiaddicts/apiaddicts-style-guide-spectral/refs/heads/main/apq-spectral.yaml
 ```
 
 ### Example
 
 ```bash
-spectral lint -r https://raw.githubusercontent.com/apiaddicts/apquality-spectral/refs/heads/main/apq-spectral.yaml petstore.yaml
+spectral lint -r https://raw.githubusercontent.com/apiaddicts/apiaddicts-style-guide-spectral/refs/heads/main/apq-spectral.yaml petstore.yaml
 ```
 
 ### Using the Spectral VSCode extension

package/apq-spectral.yaml

@@ -58,7 +58,7 @@ rules:
   apiq:OAR001:
     description: "For security reasons and as a REST best practice, the HTTPS protocol is mandatory."
     message: "OAR001: HTTPS protocol is mandatory."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR001.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR001.md"
     severity: "error"
     given: "$.servers[*].url"
     then:
@@ -68,7 +68,7 @@ rules:
   apiq:OAR002:
     description: "A wrong scope definition may cause problems to import the API definition into WSO2."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR002.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR002.md"
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes"
     then:
@@ -76,7 +76,7 @@ rules:
   apiq:OAR003:
     description: "A description can help other developers to understand the correct use of the scope."
     message: "OAR003: Scope must define a 'description' attribute."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR003.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR003.md"
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes[*]"
     then:
@@ -86,7 +86,7 @@ rules:
   apiq:OAR004:
     description: "A role with forbidden characters may cause problems in some applications."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR004.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR004.md"
     severity: "error"
     given: "$.x-wso2-security.apim.x-wso2-scopes[*].roles"
     then:
@@ -96,7 +96,7 @@ rules:
   apiq:OAR005:
     description: "A wrong scope may cause problems to import the API definition into WSO2 or allow all users to call the endpoint."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR005.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR005.md"
     severity: "error"
     resolved: false
     given: "$"
@@ -106,7 +106,7 @@ rules:
     description: "Routes must define request media types supported by the API."
     message: "OAR006: Specify at least one Media Type in the content of the request body."
     severity: "error"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR006.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR006.md"
     given: "$.paths[*][post,put,patch]"
     then:
       - field: "requestBody"
@@ -116,7 +116,7 @@ rules:
   apiq:OAR007:
     description: "Routes must define response media types supported by the API"
     message: "OAR007: Specify at least one Media Type in the content of the response body."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR007.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR007.md"
     severity: "error"
     given:
       - "$.paths[*][post,put,patch]"
@@ -128,7 +128,7 @@ rules:
   apiq:OAR008:
     description: "HTTP verbs not encouraged."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR008.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR008.md"
     severity: error
     given: "$.paths[*]"
     then:
@@ -162,7 +162,7 @@ rules:
   apiq:OAR011:
     description: "URLs should follow the configured naming convention (default kebab-case): all literal path segments must comply."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR011.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR011.md"
     severity: error
     given:
       - "$.paths[*]~"
@@ -174,7 +174,7 @@ rules:
   apiq:OAR012:
     description: "Path params, query params, object names and property names should follow the configured naming convention. You can configure snake_case (default), kebab-case, camelCase or UpperCamelCase"
     message: "OAR012: Path params, query params, object names and property names must follow the configured naming convention."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR012.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR012.md"
     severity: warn
     given:
       - "$.paths[*][*].parameters[?(@.in == 'path' || @.in == 'query')].name"
@@ -197,7 +197,7 @@ rules:
   apiq:OAR014:
     description: "Resources depth level should be below the non-suggested range."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR014.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR014.md"
     severity: warn
     given: "$.paths.*~"
     then:
@@ -221,7 +221,7 @@ rules:
   apiq:OAR016:
     description: "Numeric types requires a valid format."
     message: "OAR016: Numeric types must use a valid format for their type."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR016.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR016.md"
     severity: error
     resolved: false
     given: "$..[?(@ && @.type)]"
@@ -230,7 +230,7 @@ rules:
   apiq:OAR017:
     description: "Resource path should alternate static and parametrized parts."
     message: "OAR017: Resource path should alternate static and parametrized parts"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR017.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR017.md"
     severity: error
     given: "$.paths.*~"
     then:
@@ -240,7 +240,7 @@ rules:
   apiq:OAR018:
     description: Operation not recommended for resource path depending on HTTP verb
     message: "OAR018: Operation not recommended for resource path: {{path}} ({{verb}})"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR018.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR018.md"
     severity: warn
     given: "$.paths"
     then:
@@ -322,7 +322,7 @@ rules:
   apiq:OAR022:
     description: "$orderby must be defined as a query parameter in the collection GET operations selected by the configured paths."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR022.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR022.md"
     severity: warn
     given: "$.paths"
     then:
@@ -350,7 +350,7 @@ rules:
   apiq:OAR025:
     description: "$limit must be defined as an integer query parameter in the collection GET operations selected by the configured paths."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR025.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR025.md"
     severity: error
     given: "$.paths"
     then:
@@ -439,7 +439,7 @@ rules:
       functionOptions:
         notMatch: "^(Accept|Content-Type|Authorization)$"
   apiq:OAR034:
-    description: "GET collection responses must include a paging block that complies with the standard paging schema (required start, limit and links with self/previous/next; optional numPages and total as integers)."
+    description: "GET success JSON responses on collection paths must define an object schema with a paging block that complies with paging-schema (required start, limit and links with self/previous/next; optional numPages and total as integers)."
     message: "{{error}}"
     severity: error
     given: "$.paths[*].get.responses[*]"
@@ -447,6 +447,8 @@ rules:
       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"}'
+        paths: "/status,/health,/ping,**/me"
+        pathValidationStrategy: "/exclude"
   apiq:OAR035:
     description: "Response code 401 must be defined for operations with security schemes defined."
     message: "{{error}}"
@@ -477,7 +479,7 @@ rules:
     then:
       function: apq-schema-format
   apiq:OAR038:
-    description: "The 201 response schema of a POST operation must have properties named 'data' or 'error' with at least one sub-property."
+    description: "The 201 response schema of a POST operation must only have the allowed top-level properties ('data' or 'error' by default), each with at least one sub-property, and every required one."
     message: "{{error}}"
     severity: error
     given: "$.paths.*.post.responses['201']"
@@ -485,10 +487,14 @@ rules:
       function: apq-valid-response-schema
       functionOptions:
         data-property: data
+        allowed-properties: ""
+        required-properties: ""
+        paths: "/me,/health,/ping,/status"
+        pathValidationStrategy: "/exclude"
   apiq:OAR039:
     description: "Response codes must be defined according to the standard depending on the HTTP verb and resource path."
     message: "{{error}}"
-    documentationUrl: https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR039.md
+    documentationUrl: https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR039.md
     severity: error
     given: "$.paths[*][*]"
     then:
@@ -533,7 +539,7 @@ rules:
   apiq:OAR041:
     description: "A WSO2 x-scope on an operation always requires an x-auth-type definition."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR041.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR041.md"
     severity: "error"
     resolved: false
     given: "$"
@@ -553,7 +559,7 @@ rules:
   apiq:OAR043:
     description: "OpenAPI definition contains structural errors that would be detected by a strict parser or validator."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR043.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR043.md"
     severity: error
     given:
       - $.paths.*.*.parameters.*.in
@@ -602,7 +608,7 @@ rules:
     - "$.paths[*].patch"
     - "$.paths[*].delete"
     then:
-      function: schema              
+      function: schema
       functionOptions:
         schema:
           type: object
@@ -621,7 +627,7 @@ rules:
   apiq:OAR048:
     description: APIs must define at most one body parameter.
     message: "OAR048: An operation can have at most one body parameter"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR048.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR048.md"
     severity: error
     given: "$.paths[*][*]"
     then:
@@ -657,7 +663,7 @@ rules:
   apiq:OAR052:
     description: "Numeric schema types must define a format."
     message: "OAR052: Numeric types requires a format"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR052.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR052.md"
     severity: warn
     resolved: false
     given: "$..[?(@ && @.type)]"
@@ -666,7 +672,7 @@ rules:
   apiq:OAR053:
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR053.md"
     severity: error
     given: "$.paths[*][*].responses[*]"
     then:
@@ -863,7 +869,7 @@ rules:
   apiq:OAR076:
     description: "Schema should use well-defined type and format."
     message: "OAR076: Schema should use well-defined type and format."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR076.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR076.md"
     severity: error
     resolved: false
     given: "$..[?(@ && @.type)]"
@@ -884,7 +890,7 @@ rules:
   apiq:OAR078:
     description: "All API methods must have security defined."
     message: "OAR078: Operation must have security defined."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR078.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR078.md"
     severity: error
     given: "$"
     then:
@@ -892,7 +898,7 @@ rules:
   apiq:OAR079:
     description: "Operations with path parameters should include a 404 Not Found response."
     message: "OAR079: Path parameter present, but missing 404 Not Found response."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR079.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR079.md"
     severity: "warn"
     given: "$.paths[*][get,post,put,patch,delete]"
     then:
@@ -1010,7 +1016,7 @@ rules:
   apiq:OAR091:
     description: "Parameters must contain only $ref references."
     message: "OAR091: Parameters must contain only $ref references."
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR091.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR091.md"
     severity: error
     resolved: false
     given: "$.paths[*][get,post,put,patch,delete].parameters[*]"
@@ -1176,7 +1182,7 @@ rules:
   apiq:OAR113:
     description: "Field or extension must be at the assigned location"
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR113.md"
     severity: warn
     given: "$"
     then:
@@ -1187,7 +1193,7 @@ rules:
   apiq:OAR114:
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR114.md"
     severity: "error"
     given: "$.paths[*][*].responses[*]"
     then:
@@ -1200,7 +1206,7 @@ rules:
   apiq:OAR115:
     description: "All fields listed in the required array must be defined in the schema properties."
     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"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR115.md"
     severity: warn
     resolved: false
     given: "$..[?(@ && @.required)]"
@@ -1209,7 +1215,7 @@ rules:
   apiq:OAR116:
     description: "Every API path must match the configured regular expression."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR116.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR116.md"
     severity: error
     given: "$.paths.*~"
     then:
@@ -1219,10 +1225,10 @@ rules:
   apiq:OAR117:
     description: "The API title must not match the configured forbidden regular expression."
     message: "{{error}}"
-    documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR117.md"
+    documentationUrl: "https://github.com/apiaddicts/apiaddicts-style-guide-spectral/blob/main/docs/resources/OAR117.md"
     severity: error
     given: "$.info.title"
     then:
       function: apq-forbidden-title-pattern
       functionOptions:
-        forbidden-pattern: "(?!)"
+        forbidden-pattern: "(?!)"

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

@@ -22,12 +22,11 @@ const DEFAULT_PAGING_SCHEMA = {
 };
 
 const DEFAULT_PAGING_PROPERTY = 'paging';
-
-const COLLECTION_PROPERTY_NAMES = ['data', 'items', 'results', 'content', 'elements', 'records', 'entries', 'values', 'list', 'rows', 'payload'];
+const DEFAULT_PATHS = '/status,/health,/ping,**/me';
 
 const SUCCESS_CODE_REGEX = /^2(\d\d|XX)$/i;
 const NO_CONTENT_CODE = '204';
-const DETAIL_PATH_REGEX = /\/\{[^}]+\}$/;
+const MEDIA_TYPE_TOKEN = /^[a-z0-9!#$&^_.+-]+$/;
 
 const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 
@@ -143,15 +142,6 @@ const isArrayView = (view) => view.types.has('array');
 
 const typePath = (view) => (isObject(view.rootSchema) && view.rootSchema.type !== undefined ? [...view.path, 'type'] : view.path);
 
-const findCollectionProperty = (view) => {
-  for (const [name, property] of view.properties) {
-    if (COLLECTION_PROPERTY_NAMES.includes(name.toLowerCase()) && isArrayView(buildView(property.schema, property.path))) {
-      return name;
-    }
-  }
-  return null;
-};
-
 const validateAgainstTemplate = (template, view, label, report) => {
   if (!isObject(template)) return;
   const type = expectedType(template);
@@ -189,56 +179,130 @@ const validateAgainstTemplate = (template, view, label, report) => {
   });
 };
 
-const responseSchemas = (response, responsePath, isOas2) => {
+const isJsonMediaType = (mediaType) => {
+  const essence = String(mediaType).split(';')[0].trim().toLowerCase();
+  const parts = essence.split('/');
+  if (parts.length !== 2 || parts[0] === '*') return true;
+  const [type, subtype] = parts;
+  if (!MEDIA_TYPE_TOKEN.test(type) || (subtype !== '*' && !MEDIA_TYPE_TOKEN.test(subtype))) return true;
+  if (type === 'application' && (subtype === 'json' || subtype === '*')) return true;
+  return subtype.endsWith('+json');
+};
+
+const pathPatterns = (raw) => {
+  let items = [];
+  if (raw === undefined) items = DEFAULT_PATHS.split(',');
+  else if (typeof raw === 'string') items = raw.split(',');
+  else if (Array.isArray(raw)) items = raw;
+  return items
+    .filter((item) => typeof item === 'string')
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((pattern) => pattern.split('/'));
+};
+
+const isIncludeStrategy = (value) => typeof value === 'string' && value.trim().replace(/^\//, '').toLowerCase() === 'include';
+
+const matchesPattern = (pattern, segments) => {
+  const match = (patternIndex, segmentIndex) => {
+    if (patternIndex === pattern.length) return segmentIndex === segments.length;
+    if (pattern[patternIndex] === '**') {
+      for (let next = segmentIndex; next <= segments.length; next += 1) {
+        if (match(patternIndex + 1, next)) return true;
+      }
+      return false;
+    }
+    if (segmentIndex === segments.length) return false;
+    return (pattern[patternIndex] === '*' || pattern[patternIndex] === segments[segmentIndex]) && match(patternIndex + 1, segmentIndex + 1);
+  };
+  return match(0, 0);
+};
+
+const isDetailPath = (pathKey) => pathKey.slice(pathKey.lastIndexOf('/') + 1).startsWith('{');
+
+const isUnresolvedRef = (value) => isObject(value) && typeof value.$ref === 'string';
+
+const producedMediaTypes = (document, pathKey) => {
+  const pathItem = isObject(document) && isObject(document.paths) ? document.paths[pathKey] : null;
+  const operation = isObject(pathItem) ? pathItem.get : null;
+  const listed = (value) => (Array.isArray(value) && value.length > 0 ? value : null);
+  return listed(isObject(operation) ? operation.produces : null) || listed(isObject(document) ? document.produces : null);
+};
+
+const evaluatedSchemas = (response, responsePath, document, pathKey, isOas2) => {
+  const schemas = [];
+  const missing = [];
   if (isOas2) {
-    return isObject(response.schema) ? [{ schema: response.schema, path: [...responsePath, 'schema'] }] : [];
+    const produces = producedMediaTypes(document, pathKey);
+    if (produces && !produces.some(isJsonMediaType)) return { schemas, missing };
+    if (isUnresolvedRef(response.schema)) return { schemas, missing };
+    if (isObject(response.schema)) schemas.push({ schema: response.schema, path: [...responsePath, 'schema'] });
+    else missing.push(responsePath);
+    return { schemas, missing };
+  }
+  if (!isObject(response.content) || Object.keys(response.content).length === 0) {
+    missing.push(isObject(response.content) ? [...responsePath, 'content'] : responsePath);
+    return { schemas, missing };
   }
-  if (!isObject(response.content)) return [];
-  return Object.entries(response.content)
-    .filter(([, mediaType]) => isObject(mediaType) && isObject(mediaType.schema))
-    .map(([mediaTypeName, mediaType]) => ({ schema: mediaType.schema, path: [...responsePath, 'content', mediaTypeName, 'schema'] }));
+  Object.entries(response.content)
+    .filter(([mediaTypeName]) => isJsonMediaType(mediaTypeName))
+    .forEach(([mediaTypeName, mediaType]) => {
+      const mediaTypePath = [...responsePath, 'content', mediaTypeName];
+      if (isUnresolvedRef(mediaType) || (isObject(mediaType) && isUnresolvedRef(mediaType.schema))) return;
+      if (isObject(mediaType) && isObject(mediaType.schema)) schemas.push({ schema: mediaType.schema, path: [...mediaTypePath, 'schema'] });
+      else missing.push(mediaTypePath);
+    });
+  return { schemas, missing };
 };
 
 /**
  * @param {object} response - a resolved response of a GET operation
- * @param {object} options - { 'paging-schema': JSON string or object }
+ * @param {object} options
+ * @param {string|object} options['paging-schema'] - JSON string or object with the paging structure and its pagingPropertyName (default "paging")
+ * @param {string|string[]} options.paths - comma-separated path patterns matched segment by segment; "*" matches one segment and "**" zero or more (default "/status,/health,/ping,**\/me")
+ * @param {string} options.pathValidationStrategy - "/exclude" (default) skips the matching paths, "/include" only evaluates them
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (response, options = {}, context) => {
-  if (!isObject(response)) return [];
+  if (!isObject(response) || isUnresolvedRef(response)) return [];
+  const opts = options || {};
 
   const responsePath = context.path || [];
   const statusCode = String(responsePath[responsePath.length - 1]);
   if (!SUCCESS_CODE_REGEX.test(statusCode) || statusCode === NO_CONTENT_CODE) return [];
 
   const pathKey = typeof responsePath[1] === 'string' ? responsePath[1] : '';
-  const isDetailPath = DETAIL_PATH_REGEX.test(pathKey);
+  if (isDetailPath(pathKey)) return [];
+  const segments = pathKey.split('/');
+  const isListed = pathPatterns(opts.paths).some((pattern) => matchesPattern(pattern, segments));
+  if (isIncludeStrategy(opts.pathValidationStrategy) ? !isListed : isListed) return [];
 
-  const pagingSchema = parsePagingSchema((options || {})['paging-schema']);
+  const pagingSchema = parsePagingSchema(opts['paging-schema']);
   const pagingPropertyName = typeof pagingSchema.pagingPropertyName === 'string' && pagingSchema.pagingPropertyName.trim() !== ''
     ? pagingSchema.pagingPropertyName.trim()
     : DEFAULT_PAGING_PROPERTY;
 
-  const document = context.document && context.document.data;
-  const isOas2 = isObject(document) && typeof document.swagger === 'string';
+  const rawDocument = context.document && context.document.data;
+  const resolvedDocument = context.documentInventory && context.documentInventory.resolved;
+  const document = isObject(resolvedDocument) ? resolvedDocument : rawDocument;
+  const isOas2 = isObject(rawDocument) && typeof rawDocument.swagger === 'string';
   const ruleCode = context.rule && context.rule.name ? context.rule.name.split(':').pop() : 'OAR034';
 
   const results = [];
   const report = (message, path) => results.push({ message: `${ruleCode}: ${message}`, path });
 
-  responseSchemas(response, responsePath, isOas2).forEach(({ schema, path }) => {
+  const { schemas, missing } = evaluatedSchemas(response, responsePath, document, pathKey, isOas2);
+  missing.forEach((path) => report(`Collection response must define a schema with a '${pagingPropertyName}' property`, path));
+
+  schemas.forEach(({ schema, path }) => {
     const view = buildView(schema, path);
     const paging = view.properties.get(pagingPropertyName);
 
     if (!paging) {
-      if (isDetailPath) return;
       if (isArrayView(view)) {
         report(`Collection response must be an object with a '${pagingPropertyName}' property, not a top-level array`, view.path);
-        return;
-      }
-      const collectionProperty = findCollectionProperty(view);
-      if (collectionProperty) {
-        report(`Response with collection property '${collectionProperty}' must include '${pagingPropertyName}' property for pagination`, view.path);
+      } else {
+        report(`Collection response must include '${pagingPropertyName}' property for pagination`, view.path);
       }
       return;
     }

package/functions/apq-valid-response-schema.js

@@ -18,9 +18,40 @@ function mergedProperties(schema, visited) {
   return properties;
 }
 
+function parseList(value) {
+  let items = [];
+  if (Array.isArray(value)) {
+    items = value;
+  } else if (typeof value === 'string') {
+    items = value.split(',');
+  }
+  const names = items
+    .filter((item) => typeof item === 'string' || typeof item === 'number')
+    .map((item) => String(item).trim())
+    .filter(Boolean);
+  return [...new Set(names)];
+}
+
+function formatNames(names) {
+  const quoted = names.map((name) => `'${name}'`);
+  if (quoted.length <= 1) {
+    return quoted.join('');
+  }
+  return `${quoted.slice(0, -1).join(', ')} or ${quoted[quoted.length - 1]}`;
+}
+
+function isIncludeStrategy(value) {
+  return typeof value === 'string' && value.trim().replace(/^\//, '').toLowerCase() === 'include';
+}
+
 /**
  * @param {object} given - the 201 response object of a POST operation
  * @param {object} options
+ * @param {string} options['data-property'] - name accepted next to 'error' when allowed-properties is not set (default "data")
+ * @param {string|string[]} options['allowed-properties'] - top-level property names accepted in the schema, array or comma-separated; blank falls back to [data-property, 'error']
+ * @param {string|string[]} options['required-properties'] - top-level property names that must be present, array or comma-separated
+ * @param {string|string[]} options.paths - paths to include/exclude (exact match), array or comma-separated
+ * @param {string} options.pathValidationStrategy - "/include" or "/exclude" (default "/exclude")
  * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
  */
 module.exports = (given, options, context) => {
@@ -28,17 +59,28 @@ module.exports = (given, options, context) => {
     return [];
   }
 
-  const dataProperty = (options && options['data-property']) || 'data';
-  const VALID_NAMES = [dataProperty, 'error'];
+  const opts = options || {};
+  const basePath = context.path || [];
+
+  const paths = parseList(opts.paths);
+  const isListed = paths.includes(basePath[1]);
+  if (isIncludeStrategy(opts.pathValidationStrategy) ? !isListed : isListed) {
+    return [];
+  }
+
+  const dataProperty = opts['data-property'] || 'data';
+  const configuredNames = parseList(opts['allowed-properties']);
+  const allowedNames = configuredNames.length > 0 ? configuredNames : [...new Set([dataProperty, 'error'])];
+  const requiredNames = parseList(opts['required-properties']);
+  const allowedText = formatNames(allowedNames);
   const doc = context.document?.data ?? {};
   const isOAP2 = typeof doc.swagger === 'string';
-  const basePath = context.path || [];
   const errors = [];
 
   const checkSchema = (schema, schemaPath) => {
     if (!schema || typeof schema !== 'object') {
       errors.push({
-        message: `OAR038: 201 response must define a schema with a '${dataProperty}' or 'error' property.`,
+        message: `OAR038: 201 response must define a schema with a ${allowedText} property.`,
         path: schemaPath,
       });
       return;
@@ -49,16 +91,16 @@ module.exports = (given, options, context) => {
 
     if (propNames.length === 0) {
       errors.push({
-        message: `OAR038: Response schema must have properties named '${dataProperty}' or 'error'.`,
+        message: `OAR038: Response schema must have properties named ${allowedText}.`,
         path: schemaPath,
       });
       return;
     }
 
     for (const propName of propNames) {
-      if (!VALID_NAMES.includes(propName)) {
+      if (!allowedNames.includes(propName)) {
         errors.push({
-          message: `OAR038: Response property must be named '${dataProperty}' or 'error'. Got '${propName}'.`,
+          message: `OAR038: Response property must be named ${allowedText}. Got '${propName}'.`,
           path: [...schemaPath, 'properties', propName],
         });
         continue;
@@ -71,6 +113,15 @@ module.exports = (given, options, context) => {
         });
       }
     }
+
+    for (const requiredName of requiredNames) {
+      if (!Object.prototype.hasOwnProperty.call(properties, requiredName)) {
+        errors.push({
+          message: `OAR038: Response schema must define the required property '${requiredName}'.`,
+          path: schemaPath,
+        });
+      }
+    }
   };
 
   if (isOAP2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-quality-spectral-ruleset",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Spectral ruleset by API Quality",
   "main": "apq-spectral.yaml",
   "files": [
@@ -22,7 +22,7 @@
   "license": "GNU AGPLv3",
   "repository": {
     "type": "git",
-    "url": "https://github.com/apiaddicts/apquality-spectral"
+    "url": "https://github.com/apiaddicts/apiaddicts-style-guide-spectral"
   },
   "devDependencies": {
     "@stoplight/spectral-core": "1.23.0",