api-quality-spectral-ruleset 1.5.0-beta.1 → 1.5.0-beta.3

package/apq-spectral.yaml

@@ -30,8 +30,16 @@ functions:
   - apq-status-endpoint-check
   - apq-validate-structure
   - apq-numeric-parameter-integrity
+  - apq-path-pattern
+  - apq-query-params-optional
   - apq-wso2-scopes-valid
   - apq-numeric-path-param
+  - apq-numeric-invalid-format
+  - apq-numeric-missing-format
+  - apq-numeric-well-defined-format
+  - apq-string-parameter-integrity
+  - apq-example-schema-types
+  - apq-standard-response-schema
 extends:
   - spectral:asyncapi
   - spectral:oas
@@ -194,29 +202,10 @@ rules:
     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"
     severity: error
-    given: "$..[?(@ && (@.type=='number' || @.type=='integer' || (@.type && @.type.indexOf && (@.type.indexOf('number') > -1 || @.type.indexOf('integer') > -1))))]"
+    resolved: false
+    given: "$..[?(@ && @.type)]"
     then:
-      function: schema
-      functionOptions:
-        schema:
-          required: [format]
-          allOf:
-            - if:
-                properties:
-                  type:
-                    const: integer
-              then:
-                properties:
-                  format:
-                    enum: [int32, int64, uint32, uint64]
-            - if:
-                properties:
-                  type:
-                    const: number
-              then:
-                properties:
-                  format:
-                    enum: [float, double, decimal]
+      function: apq-numeric-invalid-format
   apiq:OAR017:
     description: "Resource path should alternate static and parametrized parts."
     message: "OAR017: Resource path should alternate static and parametrized parts"
@@ -374,38 +363,14 @@ rules:
       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."
+    message: "{{error}}"
     severity: error
-    given: "$.components.schemas.errorResponse"
+    given: "$.paths"
     then:
-      function: schema
+      function: apq-standard-response-schema
       functionOptions:
-        schema:
-          type: object
-          properties:
-            properties:
-              type: object
-              properties:
-                error:
-                  type: object
-                  properties:
-                    properties:
-                      type: object
-                      properties:
-                        code:
-                          type: string
-                        message:
-                          type: string
-                        details:
-                          type: array
-                        httpStatus:
-                          type: integer
-                      required:
-                        - code
-                        - message
-                        - httpStatus
-          required:
-            - properties
+        response-schema: '{"type":"object","properties":{"status":{"type":"object","properties":{"code":{"type":"integer"},"description":{"type":"string"},"internal_code":{"type":"string"},"errors":{"type":"array","nullable":true,"items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}},"required":["code"]},"payload":{"type":"any"}},"required":["status","payload"]}'
+        path-exclusions: "/status"
   apiq:OAR030:
     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."
@@ -686,10 +651,10 @@ rules:
     message: "OAR052: Numeric types requires a format"
     documentationUrl: "https://github.com/apiaddicts/apquality-spectral/blob/main/docs/resources/OAR052.md"
     severity: warn
-    given: "$..[?(@ && (@.type == 'integer' || @.type == 'number' || (@.type && @.type.indexOf && (@.type.indexOf('integer') > -1 || @.type.indexOf('number') > -1))))]"
+    resolved: false
+    given: "$..[?(@ && @.type)]"
     then:
-      field: format
-      function: truthy
+      function: apq-numeric-missing-format
   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."
@@ -716,12 +681,18 @@ rules:
         match: ^(http(s)?:\/\/.)[-a-zA-Z0-9@:%._\+~#=]{2,256}\.apiquality.io\b([-a-zA-Z0-9@:%_\+.~#?&\/=]*)$
   apiq:OAR060:
     description: "All query parameters must be defined as optional."
-    message: "OAR060: All query parameter must be optional (required: false)."
+    message: "{{error}}"
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@.in == 'query')]"
+    given:
+      - "$.paths[*][get,put,post,delete,options,head,patch,trace].parameters[?(@.in == 'query')]"
+      - "$.paths[*].parameters[?(@.in == 'query')]"
+      - "$.components.parameters[?(@.in == 'query')]"
+      - "$.parameters[?(@.in == 'query')]"
     then:
       field: "required"
-      function: falsy
+      function: apq-query-params-optional
+      functionOptions:
+        path-exclusions: "/status"
   apiq:OAR061:
     description: "Ensure get have mandatory response codes"
     message: "OAR061: Ensure get have the mandatory response codes"
@@ -881,47 +852,25 @@ rules:
     description: "String parameters should have minLength, maxLength, pattern (regular expression), or enum restriction."
     message: "OAR075: String parameters should have minLength, maxLength, pattern, or enum restriction."
     severity: error
-    given: "$.paths[*][get,post,put,patch,delete].parameters[?(@ && @.schema && (@.schema.type == 'string' || (@.schema.type && @.schema.type.indexOf && @.schema.type.indexOf('string') > -1)) && @.in == 'path')]"
+    resolved: false
+    given:
+      - "$.paths[*][*].parameters[*]"
+      - "$.paths[*].parameters[*]"
+      - "$.components.parameters[*]"
+      - "$.parameters[*]"
     then:
-      function: schema
+      function: apq-string-parameter-integrity
       functionOptions:
-        schema:
-          type: object
-          properties:
-            schema:
-              anyOf:
-                - required: ["minLength"]
-                - required: ["maxLength"]
-                - required: ["pattern"]
-                - required: ["enum"]
+        parameter_integrity: "minLength,maxLength,pattern,enum"
   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"
     severity: error
-    given: "$..[?(@ && (@.type=='number' || @.type=='integer' || (@.type && @.type.indexOf && (@.type.indexOf('number') > -1 || @.type.indexOf('integer') > -1))))]"
+    resolved: false
+    given: "$..[?(@ && @.type)]"
     then:
-      function: schema
-      functionOptions:
-        schema:
-          required: [format]
-          allOf:
-            - if:
-                properties:
-                  type:
-                    const: integer
-              then:
-                properties:
-                  format:
-                    enum: [int32, int64]
-            - if:
-                properties:
-                  type:
-                    const: number
-              then:
-                properties:
-                  format:
-                    enum: [float, double]
+      function: apq-numeric-well-defined-format
   apiq:OAR077:
     description: "All parameters in query must be snake_case."
     message: "OAR077: All parameters in query must be snake_case."
@@ -1191,19 +1140,10 @@ rules:
     description: "The schemas should match the provided examples."
     message: "OAR108: Schema does not match the provided example."
     severity: "error"
-    given: 
-      - "$.paths['/item'].get.responses['200'].content['application/json'].example"
-      - "$.paths['/item'].get.responses['200'].examples['application/json']"
+    resolved: false
+    given: "$.paths[*][*].responses[*]"
     then:
-      - function: "schema"
-        functionOptions:
-          schema:
-            type: "object"
-            properties:
-              id:
-                type: "integer"
-              nombre:
-                type: "string" 
+      function: apq-example-schema-types
   apiq:OAR109:
     description: "Use default response instead of directly specifying 5XX codes."
     message: "OAR109: Use default response instead of specifying 5XX codes directly."
@@ -1257,8 +1197,17 @@ rules:
     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:
-      - "$.components.schemas[*]"
-      - "$.definitions[*]"
+    resolved: false
+    given: "$..[?(@ && @.required)]"
     then:
-      function: apq-required-fields-exist
+      function: apq-required-fields-exist
+  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"
+    severity: error
+    given: "$.paths.*~"
+    then:
+      function: apq-path-pattern
+      functionOptions:
+        pattern: "^/"

package/functions/apq-example-schema-types.js

@@ -0,0 +1,116 @@
+function getPrimaryType(type) {
+  if (type === undefined || type === null) return null;
+  if (Array.isArray(type)) {
+    for (const element of type) {
+      if (element === null || element === undefined) continue;
+      const value = String(element);
+      if (value !== 'null') return value;
+    }
+    return null;
+  }
+  if (typeof type === 'object') return null;
+  return String(type);
+}
+
+function determineExampleType(value) {
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'object') return 'object';
+  if (typeof value === 'boolean') return 'boolean';
+  if (typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'number';
+  return 'string';
+}
+
+function schemaTypes(schema) {
+  const types = new Map();
+  if (!schema || typeof schema !== 'object') return types;
+  const { properties } = schema;
+  if (!properties || typeof properties !== 'object') return types;
+  Object.keys(properties).forEach((name) => {
+    const property = properties[name];
+    const type = property && typeof property === 'object' ? property.type : undefined;
+    types.set(name, getPrimaryType(type));
+  });
+  return types;
+}
+
+function exampleTypes(example) {
+  const types = new Map();
+  if (!example || typeof example !== 'object' || Array.isArray(example)) return types;
+  Object.keys(example).forEach((name) => {
+    types.set(name, determineExampleType(example[name]));
+  });
+  return types;
+}
+
+function swaggerExampleTypes(examples) {
+  const types = new Map();
+  if (!examples || typeof examples !== 'object' || Array.isArray(examples)) return types;
+  Object.keys(examples).forEach((mediaType) => {
+    const payload = examples[mediaType];
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return;
+    Object.keys(payload).forEach((name) => {
+      types.set(name, determineExampleType(payload[name]));
+    });
+  });
+  return types;
+}
+
+function isCompatible(expectedType, actualType) {
+  if (expectedType === null) return true;
+  if (actualType === 'null') return true;
+  if (expectedType === actualType) return true;
+  return expectedType === 'number' && actualType === 'integer';
+}
+
+function mismatches(schema, example, isSwagger) {
+  const expected = schemaTypes(schema);
+  if (expected.size === 0) return false;
+  const actual = isSwagger ? swaggerExampleTypes(example) : exampleTypes(example);
+
+  for (const [name, expectedType] of expected) {
+    const actualType = actual.has(name) ? actual.get(name) : 'unknown';
+    if (!isCompatible(expectedType, actualType)) return true;
+  }
+  return false;
+}
+
+function isPresent(value) {
+  return value !== undefined && value !== null;
+}
+
+/**
+ * @param {object} targetVal a Response Object
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, options, context) => {
+  if (!targetVal || typeof targetVal !== 'object') return [];
+
+  const results = [];
+  const { content } = targetVal;
+
+  if (isPresent(content) && typeof content === 'object' && !Array.isArray(content)) {
+    Object.keys(content).forEach((mediaType) => {
+      const mediaTypeNode = content[mediaType];
+      if (!mediaTypeNode || typeof mediaTypeNode !== 'object') return;
+      const { schema, example } = mediaTypeNode;
+      if (!isPresent(schema) || !isPresent(example)) return;
+      if (mismatches(schema, example, false)) {
+        results.push({
+          message: context.rule.message,
+          path: [...context.path, 'content', mediaType, 'example'],
+        });
+      }
+    });
+    return results;
+  }
+
+  const { schema, examples } = targetVal;
+  if (!isPresent(schema) || !isPresent(examples)) return results;
+  if (mismatches(schema, examples, true)) {
+    results.push({ message: context.rule.message, path: [...context.path, 'examples'] });
+  }
+
+  return results;
+};

package/functions/apq-numeric-invalid-format.js

@@ -0,0 +1,64 @@
+const VALID_INTEGER_FORMATS = new Set(['int32', 'int64']);
+const VALID_NUMBER_FORMATS = new Set(['float', 'double']);
+
+function getPrimaryType(type) {
+  if (type === undefined || type === null) return null;
+  if (Array.isArray(type)) {
+    for (const element of type) {
+      if (element === null || element === undefined) continue;
+      const value = String(element);
+      if (value !== 'null') return value;
+    }
+    return null;
+  }
+  if (typeof type === 'object') return null;
+  return String(type);
+}
+
+function readFormat(node) {
+  if (!Object.prototype.hasOwnProperty.call(node, 'format')) return { present: false, blank: false };
+  const raw = node.format;
+  if (raw === null || raw === undefined) return { present: false, blank: false };
+  if (typeof raw === 'object') return { present: true, blank: true };
+  const value = String(raw).trim();
+  if (value === '') return { present: true, blank: true };
+  return { present: true, blank: false, value };
+}
+
+const NON_SCHEMA_CONTAINERS = new Set(['example', 'examples', 'default', 'enum']);
+
+function isInsideNonSchemaValue(path) {
+  for (let i = 0; i < path.length; i += 1) {
+    const segment = path[i];
+    if (typeof segment !== 'string' || !NON_SCHEMA_CONTAINERS.has(segment)) continue;
+    if (i > 0 && path[i - 1] === 'properties') continue;
+    return true;
+  }
+  return false;
+}
+
+function isSwaggerResponseHeader(path) {
+  const i = path.length - 2;
+  return i >= 0 && path[i] === 'headers' && (i === 0 || path[i - 1] !== 'properties');
+}
+
+/**
+ * @param {object} targetVal
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, options, context) => {
+  if (!targetVal || typeof targetVal !== 'object') return [];
+  if (isInsideNonSchemaValue(context.path) || isSwaggerResponseHeader(context.path)) return [];
+
+  const type = getPrimaryType(targetVal.type);
+  if (type !== 'integer' && type !== 'number') return [];
+
+  const format = readFormat(targetVal);
+  if (!format.present || format.blank) return [];
+
+  const valid = type === 'integer' ? VALID_INTEGER_FORMATS : VALID_NUMBER_FORMATS;
+  if (valid.has(format.value)) return [];
+
+  return [{ message: context.rule.message, path: [...context.path, 'type'] }];
+};

package/functions/apq-numeric-missing-format.js

@@ -0,0 +1,58 @@
+function getPrimaryType(type) {
+  if (type === undefined || type === null) return null;
+  if (Array.isArray(type)) {
+    for (const element of type) {
+      if (element === null || element === undefined) continue;
+      const value = String(element);
+      if (value !== 'null') return value;
+    }
+    return null;
+  }
+  if (typeof type === 'object') return null;
+  return String(type);
+}
+
+function readFormat(node) {
+  if (!Object.prototype.hasOwnProperty.call(node, 'format')) return { present: false, blank: false };
+  const raw = node.format;
+  if (raw === null || raw === undefined) return { present: false, blank: false };
+  if (typeof raw === 'object') return { present: true, blank: true };
+  const value = String(raw).trim();
+  if (value === '') return { present: true, blank: true };
+  return { present: true, blank: false, value };
+}
+
+const NON_SCHEMA_CONTAINERS = new Set(['example', 'examples', 'default', 'enum']);
+
+function isInsideNonSchemaValue(path) {
+  for (let i = 0; i < path.length; i += 1) {
+    const segment = path[i];
+    if (typeof segment !== 'string' || !NON_SCHEMA_CONTAINERS.has(segment)) continue;
+    if (i > 0 && path[i - 1] === 'properties') continue;
+    return true;
+  }
+  return false;
+}
+
+function isSwaggerResponseHeader(path) {
+  const i = path.length - 2;
+  return i >= 0 && path[i] === 'headers' && (i === 0 || path[i - 1] !== 'properties');
+}
+
+/**
+ * @param {object} targetVal
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, options, context) => {
+  if (!targetVal || typeof targetVal !== 'object') return [];
+  if (isInsideNonSchemaValue(context.path) || isSwaggerResponseHeader(context.path)) return [];
+
+  const type = getPrimaryType(targetVal.type);
+  if (type !== 'integer' && type !== 'number') return [];
+
+  const format = readFormat(targetVal);
+  if (format.present) return [];
+
+  return [{ message: context.rule.message, path: [...context.path, 'type'] }];
+};

package/functions/apq-numeric-well-defined-format.js

@@ -0,0 +1,64 @@
+const VALID_INTEGER_FORMATS = new Set(['int32', 'int64']);
+const VALID_NUMBER_FORMATS = new Set(['float', 'double']);
+
+function getPrimaryType(type) {
+  if (type === undefined || type === null) return null;
+  if (Array.isArray(type)) {
+    for (const element of type) {
+      if (element === null || element === undefined) continue;
+      const value = String(element);
+      if (value !== 'null') return value;
+    }
+    return null;
+  }
+  if (typeof type === 'object') return null;
+  return String(type);
+}
+
+function readFormat(node) {
+  if (!Object.prototype.hasOwnProperty.call(node, 'format')) return { present: false, blank: false };
+  const raw = node.format;
+  if (raw === null || raw === undefined) return { present: false, blank: false };
+  if (typeof raw === 'object') return { present: true, blank: true };
+  const value = String(raw).trim();
+  if (value === '') return { present: true, blank: true };
+  return { present: true, blank: false, value };
+}
+
+const NON_SCHEMA_CONTAINERS = new Set(['example', 'examples', 'default', 'enum']);
+
+function isInsideNonSchemaValue(path) {
+  for (let i = 0; i < path.length; i += 1) {
+    const segment = path[i];
+    if (typeof segment !== 'string' || !NON_SCHEMA_CONTAINERS.has(segment)) continue;
+    if (i > 0 && path[i - 1] === 'properties') continue;
+    return true;
+  }
+  return false;
+}
+
+function isSwaggerResponseHeader(path) {
+  const i = path.length - 2;
+  return i >= 0 && path[i] === 'headers' && (i === 0 || path[i - 1] !== 'properties');
+}
+
+/**
+ * @param {object} targetVal
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, options, context) => {
+  if (!targetVal || typeof targetVal !== 'object') return [];
+  if (isInsideNonSchemaValue(context.path) || isSwaggerResponseHeader(context.path)) return [];
+
+  const type = getPrimaryType(targetVal.type);
+  if (type !== 'integer' && type !== 'number') return [];
+
+  const format = readFormat(targetVal);
+  if (format.blank) return [];
+
+  const valid = type === 'integer' ? VALID_INTEGER_FORMATS : VALID_NUMBER_FORMATS;
+  if (format.present && valid.has(format.value)) return [];
+
+  return [{ message: context.rule.message, path: [...context.path, 'type'] }];
+};

package/functions/apq-path-pattern.js

@@ -0,0 +1,14 @@
+module.exports = (targetVal, options = {}) => {
+  const patternStr = (options && options.pattern) || '^/';
+
+  if (typeof targetVal !== 'string') {
+    return [];
+  }
+
+  const regex = new RegExp(patternStr);
+  if (!regex.test(targetVal)) {
+    return [{ message: `OAR116: Path does not match the required pattern: ${patternStr}` }];
+  }
+
+  return [];
+};

package/functions/apq-query-params-optional.js

@@ -0,0 +1,182 @@
+const HTTP_VERBS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+
+// Guards against a cycle in a `$ref` chain (A -> B -> A).
+const MAX_REF_DEPTH = 10;
+
+// The `$ref` usage map depends only on the source document, so cache it per document instead of
+// rebuilding it on every matched parameter.
+const usageCache = new WeakMap();
+
+const issue = () => [{ message: 'OAR060: All query parameter must be optional (required: false).' }];
+
+function parseExclusions(value) {
+  return new Set(
+    String(value === undefined || value === null ? '' : value)
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Split a local JSON pointer (`#/components/parameters/Foo`) into its decoded segments.
+ * Returns null for external refs and for anything that is not a document-local pointer.
+ */
+function refToSegments(ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) {
+    return null;
+  }
+  return ref.slice(2).split('/').map((raw) => {
+    let segment = raw;
+    try {
+      segment = decodeURIComponent(raw);
+    } catch (e) {
+      segment = raw;
+    }
+    return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+  });
+}
+
+function getAt(doc, segments) {
+  return segments.reduce(
+    (node, segment) => (node !== null && typeof node === 'object' ? node[segment] : undefined),
+    doc,
+  );
+}
+
+const keyOf = (segments) => JSON.stringify(segments);
+
+/**
+ * The two containers the rule's `given` scans for shared parameter definitions:
+ * `components.parameters.<name>` (OpenAPI 3) and `parameters.<name>` (OpenAPI 2).
+ */
+function definitionSegments(path) {
+  if (path[0] === 'components' && path[1] === 'parameters' && path.length >= 3) {
+    return path.slice(0, 3);
+  }
+  if (path[0] === 'parameters' && path.length >= 2) {
+    return path.slice(0, 2);
+  }
+  return null;
+}
+
+const isSharedDefinitionRef = (segments) => segments !== null
+  && ((segments.length === 3 && segments[0] === 'components' && segments[1] === 'parameters')
+    || (segments.length === 2 && segments[0] === 'parameters'));
+
+/** Map of shared-definition pointer -> set of API paths that reference it through a `$ref`. */
+function buildRefUsages(doc) {
+  const usages = new Map();
+  const paths = doc && typeof doc === 'object' ? doc.paths : undefined;
+  if (!paths || typeof paths !== 'object') {
+    return usages;
+  }
+
+  Object.keys(paths).forEach((apiPath) => {
+    const pathItem = paths[apiPath];
+    if (!pathItem || typeof pathItem !== 'object') {
+      return;
+    }
+
+    const parameterLists = [pathItem.parameters];
+    HTTP_VERBS.forEach((verb) => {
+      const operation = pathItem[verb];
+      if (operation && typeof operation === 'object') {
+        parameterLists.push(operation.parameters);
+      }
+    });
+
+    parameterLists.forEach((list) => {
+      if (!Array.isArray(list)) {
+        return;
+      }
+      list.forEach((parameter) => {
+        let current = parameter;
+        for (let depth = 0; depth < MAX_REF_DEPTH; depth += 1) {
+          if (!current || typeof current !== 'object' || typeof current.$ref !== 'string') {
+            break;
+          }
+          const segments = refToSegments(current.$ref);
+          if (segments === null) {
+            break;
+          }
+          const key = keyOf(segments);
+          if (!usages.has(key)) {
+            usages.set(key, new Set());
+          }
+          usages.get(key).add(apiPath);
+          const next = getAt(doc, segments);
+          if (!next || next === current) {
+            break;
+          }
+          current = next;
+        }
+      });
+    });
+  });
+
+  return usages;
+}
+
+function refUsagesFor(doc) {
+  if (!doc || typeof doc !== 'object') {
+    return new Map();
+  }
+  let cached = usageCache.get(doc);
+  if (cached === undefined) {
+    cached = buildRefUsages(doc);
+    usageCache.set(doc, cached);
+  }
+  return cached;
+}
+
+/**
+ * True when the match landed on a `$ref` to a shared definition the rule also scans on its own —
+ * either a use site under `paths`, or one shared definition aliasing another.
+ *
+ * Spectral runs the rule over the resolved document, so it matches such a parameter once here and
+ * once at the definition it points to. Reporting is left to the definition-site match, which is
+ * also the only place Sonar reports it (its AST visits the definition, never the use sites).
+ */
+function isRefToSharedDefinition(source, path) {
+  const parameterPath = path[path.length - 1] === 'required' ? path.slice(0, -1) : path;
+  const node = getAt(source, parameterPath);
+  if (!node || typeof node !== 'object' || typeof node.$ref !== 'string') {
+    return false;
+  }
+  return isSharedDefinitionRef(refToSegments(node.$ref));
+}
+
+module.exports = (targetVal, options = {}, context = {}) => {
+  const exclusions = parseExclusions((options || {})['path-exclusions']);
+  const path = (context && context.path) || [];
+  const source = context && context.document ? context.document.data : undefined;
+
+  if (isRefToSharedDefinition(source, path)) {
+    return [];
+  }
+
+  if (path[0] === 'paths') {
+    const apiPath = path.find((p) => typeof p === 'string' && p.startsWith('/'));
+    if (apiPath && exclusions.has(apiPath)) {
+      return [];
+    }
+  } else if (exclusions.size > 0) {
+    // A shared definition has no path of its own: the AST/JSONPath match lands on
+    // `components.parameters.<name>` (or `parameters.<name>` in OpenAPI 2). Exclude it only when
+    // every path that references it is excluded — an unreferenced definition stays in scope.
+    const definition = definitionSegments(path);
+    const usages = definition === null
+      ? undefined
+      : refUsagesFor(source).get(keyOf(definition));
+    if (usages !== undefined && usages.size > 0 && [...usages].every((u) => exclusions.has(u))) {
+      return [];
+    }
+  }
+
+  if (targetVal === true || targetVal === 'true') {
+    return issue();
+  }
+
+  return [];
+};

package/functions/apq-required-fields-exist.js

@@ -1,3 +1,28 @@
+const NON_SCHEMA_CONTAINERS = new Set(['example', 'examples', 'default', 'enum']);
+
+function isInsideNonSchemaValue(path) {
+  for (let i = 0; i < path.length; i += 1) {
+    const segment = path[i];
+    if (typeof segment !== 'string' || !NON_SCHEMA_CONTAINERS.has(segment)) continue;
+    if (i > 0 && path[i - 1] === 'properties') continue;
+    return true;
+  }
+  return false;
+}
+
+function isResponseJsonSchema(path) {
+  const n = path.length;
+  if (path[n - 1] !== 'schema') return false;
+  if (n >= 5 && path[n - 2] === 'application/json' && path[n - 3] === 'content' && path[n - 5] === 'responses') {
+    return true;
+  }
+  return n >= 3 && path[n - 3] === 'responses';
+}
+
+function isObjectType(type) {
+  return type === 'object' || (Array.isArray(type) && type.indexOf('object') > -1);
+}
+
 /**
  * @param {object} given
  * @param {object} options
@@ -6,10 +31,10 @@
 module.exports = (given, options, context) => {
   const results = [];
 
-  if (!given) return results;
-  const t = given.type;
-  const isObjectType = t === 'object' || (Array.isArray(t) && t.indexOf('object') > -1);
-  if (!isObjectType) return results;
+  if (!given || typeof given !== 'object') return results;
+  if (isInsideNonSchemaValue(context.path)) return results;
+
+  if (!isObjectType(given.type) && !isResponseJsonSchema(context.path)) return results;
 
   const { required, properties } = given;
   if (!Array.isArray(required)) return results;
@@ -21,7 +46,7 @@ module.exports = (given, options, context) => {
     if (!propertyNames.has(field)) {
       results.push({
         message: `${ruleCode}: This value does not exist, '${field}' must be defined in the schema properties.`,
-        path: [...context.path, 'required', index]
+        path: [...context.path, 'required', index],
       });
     }
   });

package/functions/apq-schema-format.js

@@ -13,7 +13,24 @@ function isValidPattern(pattern) {
   }
 }
 
+const NON_SCHEMA_CONTAINERS = new Set(['example', 'examples', 'default', 'enum']);
+
+function isNotASchemaNode(path) {
+  for (let i = 0; i < path.length; i += 1) {
+    const segment = path[i];
+    if (typeof segment !== 'string' || !NON_SCHEMA_CONTAINERS.has(segment)) continue;
+    if (i > 0 && path[i - 1] === 'properties') continue;
+    return true;
+  }
+  const last = path.length - 2;
+  return last >= 0 && path[last] === 'headers' && (last === 0 || path[last - 1] !== 'properties');
+}
+
 module.exports = (targetVal, _options, context) => {
+  if (isNotASchemaNode(context.path)) {
+    return [];
+  }
+
   const typePath = [...context.path, 'type'];
 
   const type = targetVal.type;

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

@@ -0,0 +1,318 @@
+const DEFAULT_RESPONSE_SCHEMA = '{"type":"object","properties":{"status":{"type":"object","properties":{"code":{"type":"integer"},"description":{"type":"string"},"internal_code":{"type":"string"},"errors":{"type":"array","nullable":true,"items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}},"required":["code"]},"payload":{"type":"any"}},"required":["status","payload"]}';
+const DEFAULT_PATH_EXCLUSIONS = '/status';
+
+const TYPE_ANY = '*';
+const OPERATIONS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+
+const MESSAGES = {
+  propertyMissing: (name) => `'${name}' property is missing`,
+  propertyWrongType: (name, type) => `'${name}' must be of type ${type}`,
+  propertyItemsMissing: (name) => `'${name}' items are missing`,
+  propertyItemsWrongType: (name, type) => `'${name}' items must be of type ${type}`,
+  requiredProperties: (fields) => `The following fields must be required: ${fields}`,
+  requiredOneProperty: () => 'At least one property must be defined',
+};
+
+function isType(type, name) {
+  if (name === TYPE_ANY) return true;
+  if (type === undefined || type === null) return false;
+  if (Array.isArray(type)) return type.some((element) => String(element) === name);
+  return String(type) === name;
+}
+
+function typeOf(node) {
+  return node && typeof node === 'object' ? node.type : undefined;
+}
+
+function getAllProperties(schema, basePath) {
+  const properties = new Map();
+  if (!schema || typeof schema !== 'object') return properties;
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    Object.keys(schema.properties).forEach((name) => {
+      properties.set(name, {
+        value: schema.properties[name],
+        path: [...basePath, 'properties', name],
+      });
+    });
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    schema.allOf.forEach((member, index) => {
+      getAllProperties(member, [...basePath, 'allOf', index]).forEach((entry, name) => {
+        properties.set(name, entry);
+      });
+    });
+  }
+
+  return properties;
+}
+
+function matchesTypeViaAllOf(node, expectedType) {
+  if (!node || !Array.isArray(node.allOf)) return false;
+  return node.allOf.some((member) => member && typeof member === 'object' && isType(member.type, expectedType));
+}
+
+function declaredTypeOf(declared) {
+  let type = declared && typeof declared === 'object' && typeof declared.type === 'string'
+    ? declared.type.trim()
+    : '';
+  if (type === '' || type === 'any') type = TYPE_ANY;
+  if (type === TYPE_ANY && declared && typeof declared === 'object' && declared.properties) type = 'object';
+  return type;
+}
+
+function createValidator(config, ruleCode) {
+  const results = [];
+
+  const push = (path, text) => results.push({ message: `${ruleCode}: ${text}`, path });
+
+  function validateProperty(properties, propertyName, propertyType, parentPath) {
+    const entry = properties.get(propertyName);
+    if (!entry) {
+      push(parentPath, MESSAGES.propertyMissing(propertyName));
+      return null;
+    }
+    const { value, path } = entry;
+    if (isType(typeOf(value), propertyType)) return entry;
+    if (matchesTypeViaAllOf(value, propertyType)) return entry;
+
+    const hasType = typeOf(value) !== undefined;
+    push(hasType ? [...path, 'type'] : path, MESSAGES.propertyWrongType(propertyName, propertyType));
+    return null;
+  }
+
+  function validateRequiredProperties(schema, schemaPath, requiredValues) {
+    const declared = schema && typeof schema === 'object' ? schema.required : undefined;
+    const present = new Set(Array.isArray(declared) ? declared.map(String) : []);
+    if (requiredValues.every((name) => present.has(name))) return;
+    push(
+      Array.isArray(declared) ? [...schemaPath, 'required'] : schemaPath,
+      MESSAGES.requiredProperties(requiredValues.join(', ')),
+    );
+  }
+
+  function validateItems(entry, propertyName, itemsType) {
+    const { value, path } = entry;
+    if (!isType(typeOf(value), 'array')) return null;
+
+    const items = value.items;
+    if (items === undefined || items === null) {
+      push(path, MESSAGES.propertyItemsMissing(propertyName));
+      return null;
+    }
+    const itemsPath = [...path, 'items'];
+    if (!isType(typeOf(items), itemsType)) {
+      push(
+        typeOf(items) === undefined ? itemsPath : [...itemsPath, 'type'],
+        MESSAGES.propertyItemsWrongType(propertyName, itemsType),
+      );
+      return null;
+    }
+    return { value: items, path: itemsPath };
+  }
+
+  function validateObject(declaredSchema, entry) {
+    const declaredProperties = declaredSchema && typeof declaredSchema === 'object'
+      ? declaredSchema.properties
+      : null;
+    if (declaredProperties && typeof declaredProperties === 'object') {
+      Object.keys(declaredProperties).sort().forEach((child) => {
+        validateProperties(child, declaredProperties[child], entry);
+      });
+    }
+
+    const declaredRequired = declaredSchema && typeof declaredSchema === 'object'
+      ? declaredSchema.required
+      : null;
+    if (Array.isArray(declaredRequired) && declaredRequired.length > 0) {
+      const required = [...new Set(declaredRequired.map(String))].sort();
+      validateRequiredProperties(entry.value, entry.path, required);
+    }
+  }
+
+  function validateArray(declaredSchema, entry, propertyName) {
+    const declaredItems = declaredSchema && typeof declaredSchema === 'object' ? declaredSchema.items : null;
+    const itemsType = declaredTypeOf(declaredItems);
+
+    if (itemsType === 'object') {
+      const items = validateItems(entry, propertyName, itemsType);
+      if (items) validateObject(declaredItems, items);
+      return;
+    }
+    if (itemsType === 'array') {
+      const items = validateItems(entry, propertyName, itemsType);
+      if (items) validateArray(declaredItems, items, propertyName);
+      return;
+    }
+    validateItems(entry, propertyName, itemsType);
+  }
+
+  function validateProperties(propertyName, declaredSchema, containerEntry) {
+    const propertyMap = getAllProperties(containerEntry.value, containerEntry.path);
+    const schemaType = declaredTypeOf(declaredSchema);
+
+    if (schemaType === 'object') {
+      const entry = validateProperty(propertyMap, propertyName, 'object', containerEntry.path);
+      if (entry) validateObject(declaredSchema, entry);
+      return;
+    }
+    if (schemaType === 'array') {
+      const entry = validateProperty(propertyMap, propertyName, 'array', containerEntry.path);
+      if (entry) validateArray(declaredSchema, entry, propertyName);
+      return;
+    }
+    validateProperty(propertyMap, propertyName, schemaType, containerEntry.path);
+  }
+
+  function validateDataProperty(name, declaredSchema, properties, parentEntry) {
+    let type = declaredSchema && typeof declaredSchema === 'object' && typeof declaredSchema.type === 'string'
+      ? declaredSchema.type
+      : TYPE_ANY;
+    if (type === 'any') type = TYPE_ANY;
+
+    const entry = validateProperty(properties, name, type, parentEntry.path);
+    if (!entry) return;
+
+    const parentIsArray = isType(typeOf(parentEntry.value), 'array');
+    if (getAllProperties(entry.value, entry.path).size === 0 && !parentIsArray) {
+      push(entry.path, MESSAGES.requiredOneProperty());
+    }
+  }
+
+  function validateRootProperties(requiredNames, properties, parentEntry) {
+    if (!Array.isArray(requiredNames) || requiredNames.length === 0) return;
+    requiredNames.map(String).forEach((name) => {
+      const declaredSchema = config.properties && Object.prototype.hasOwnProperty.call(config.properties, name)
+        ? config.properties[name]
+        : null;
+      if (name === config.dataProperty) {
+        validateDataProperty(name, declaredSchema, properties, parentEntry);
+      } else {
+        validateProperties(name, declaredSchema, parentEntry);
+      }
+    });
+  }
+
+  function resolveRootNode(properties, schemaEntry) {
+    let rootProperty = config.rootProperty;
+    if (rootProperty === TYPE_ANY) {
+      const first = properties.keys().next();
+      if (first.done) return null;
+      rootProperty = first.value;
+    }
+
+    const rootEntry = validateProperty(properties, rootProperty, 'object', schemaEntry.path);
+    if (rootEntry && getAllProperties(rootEntry.value, rootEntry.path).size === 0) {
+      push(rootEntry.path, MESSAGES.requiredOneProperty());
+    }
+    return rootEntry;
+  }
+
+  function visitSchemaNode(schemaEntry, statusCode) {
+    let successCode = false;
+    let code = 0;
+    if (String(statusCode).toLowerCase() !== 'default') {
+      code = Number.parseInt(String(statusCode), 10);
+      if (Number.isNaN(code)) return;
+      successCode = code >= 200 && code < 300 && code !== 204;
+    }
+    if (code === 204) return;
+
+    let entry = schemaEntry;
+    let properties = getAllProperties(entry.value, entry.path);
+
+    if (config.rootProperty !== null) {
+      const rootEntry = resolveRootNode(properties, entry);
+      if (!rootEntry) return;
+      entry = rootEntry;
+      properties = getAllProperties(rootEntry.value, rootEntry.path);
+    }
+
+    validateRootProperties(successCode ? config.requiredOnSuccess : config.requiredOnError, properties, entry);
+    validateRootProperties(config.requiredAlways, properties, entry);
+  }
+
+  return { results, visitSchemaNode };
+}
+
+function parseConfig(options) {
+  const raw = options && options['response-schema'] !== undefined && options['response-schema'] !== null
+    ? options['response-schema']
+    : DEFAULT_RESPONSE_SCHEMA;
+  const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  return {
+    requiredOnSuccess: Array.isArray(parsed.requiredOnSuccess) ? parsed.requiredOnSuccess : null,
+    requiredOnError: Array.isArray(parsed.requiredOnError) ? parsed.requiredOnError : null,
+    requiredAlways: Array.isArray(parsed.requiredAlways) ? parsed.requiredAlways : null,
+    properties: parsed.properties && typeof parsed.properties === 'object' ? parsed.properties : null,
+    dataProperty: typeof parsed.dataProperty === 'string' ? parsed.dataProperty : null,
+    rootProperty: typeof parsed.rootProperty === 'string' ? parsed.rootProperty : null,
+  };
+}
+
+/**
+ * @param {object} targetVal the Paths Object
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, options, context) => {
+  if (!targetVal || typeof targetVal !== 'object') return [];
+
+  const ruleCode = context.rule.name.split(':').pop();
+
+  let config;
+  try {
+    config = parseConfig(options);
+  } catch (err) {
+    return [{ message: `${ruleCode}: Error parsing Standard Response Schemas`, path: context.path }];
+  }
+
+  const rawExclusions = options && options['path-exclusions'] !== undefined && options['path-exclusions'] !== null
+    ? String(options['path-exclusions'])
+    : DEFAULT_PATH_EXCLUSIONS;
+  const exclusions = new Set(rawExclusions.split(',').map((item) => item.trim()));
+
+  const validator = createValidator(config, ruleCode);
+
+  Object.keys(targetVal).forEach((pathName) => {
+    if (exclusions.has(pathName)) return;
+    const pathItem = targetVal[pathName];
+    if (!pathItem || typeof pathItem !== 'object') return;
+
+    Object.keys(pathItem).forEach((operationName) => {
+      if (!OPERATIONS.has(operationName.toLowerCase())) return;
+      const operation = pathItem[operationName];
+      if (!operation || typeof operation !== 'object') return;
+      const { responses } = operation;
+      if (!responses || typeof responses !== 'object') return;
+
+      Object.keys(responses).forEach((statusCode) => {
+        const response = responses[statusCode];
+        if (!response || typeof response !== 'object') return;
+        const responsePath = [...context.path, pathName, operationName, 'responses', statusCode];
+
+        if (response.content && typeof response.content === 'object') {
+          Object.keys(response.content).forEach((mediaType) => {
+            if (!mediaType.toLowerCase().includes('json')) return;
+            const mediaTypeNode = response.content[mediaType];
+            if (!mediaTypeNode || typeof mediaTypeNode !== 'object') return;
+            const { schema } = mediaTypeNode;
+            if (schema === undefined || schema === null) return;
+            validator.visitSchemaNode(
+              { value: schema, path: [...responsePath, 'content', mediaType, 'schema'] },
+              statusCode,
+            );
+          });
+          return;
+        }
+
+        const { schema } = response;
+        if (schema === undefined || schema === null) return;
+        validator.visitSchemaNode({ value: schema, path: [...responsePath, 'schema'] }, statusCode);
+      });
+    });
+  });
+
+  return validator.results;
+};

package/functions/apq-string-parameter-integrity.js

@@ -0,0 +1,35 @@
+const DEFAULT_INTEGRITY = 'minLength,maxLength,pattern,enum';
+
+function isStringType(type) {
+  return type === 'string' || (Array.isArray(type) && type.indexOf('string') > -1);
+}
+
+/**
+ * @param {object} targetVal a Parameter Object
+ * @param {object} options
+ * @param {import('@stoplight/spectral-core').RulesetFunctionContext} context
+ */
+module.exports = (targetVal, options, context) => {
+  if (!targetVal || typeof targetVal !== 'object') return [];
+
+  const hasOwnType = Object.prototype.hasOwnProperty.call(targetVal, 'type');
+  const isSwaggerBody = targetVal.in === 'body';
+  const container = hasOwnType || isSwaggerBody ? targetVal : targetVal.schema;
+  const containerPath = hasOwnType || isSwaggerBody ? context.path : [...context.path, 'schema'];
+  if (!container || typeof container !== 'object') return [];
+
+  if (!isStringType(container.type)) return [];
+
+  const raw = options && options.parameter_integrity !== undefined && options.parameter_integrity !== null
+    ? String(options.parameter_integrity)
+    : DEFAULT_INTEGRITY;
+  const checks = raw.split(',').map((key) => key.trim());
+
+  const satisfied = checks.some((key) => {
+    if (!Object.prototype.hasOwnProperty.call(container, key)) return false;
+    return container[key] !== undefined && container[key] !== null;
+  });
+  if (satisfied) return [];
+
+  return [{ message: context.rule.message, path: [...containerPath, 'type'] }];
+};

package/package.json

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