@scalar/openapi-validator 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @scalar/openapi-validator
 
+## 0.1.11
+
+### Patch Changes
+
+- [#10489](https://github.com/scalar/scalar/pull/10489): Report invalid non-exploded structured cookies in OpenAPI 3.2 documents and prevent invalid request and code sample generation. Recommend `style: cookie` with `explode: true`.
+- [#10485](https://github.com/scalar/scalar/pull/10485): Validate missing and mismatched path parameters for QUERY and methods under additionalOperations, including inherited path-level parameters.
+
 ## 0.1.10
 
 ## 0.1.9

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { OpenApiVersions as supportedVersions } from './specifications.js';
 export type { ErrorObject, OpenApiVersion, ThrowOnErrorOption, ValidationOutcome } from './types.js';
 export { type ValidateOptions, validate } from './validate.js';
+export { validateCookieParameters } from './validate-cookie-parameters.js';
 export { validatePathParameters } from './validate-path-parameters.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,IAAI,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACvE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AACjG,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,IAAI,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACvE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AACjG,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAA;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { OpenApiVersions as supportedVersions } from './specifications.js';
 export { validate } from './validate.js';
+export { validateCookieParameters } from './validate-cookie-parameters.js';
 export { validatePathParameters } from './validate-path-parameters.js';

package/dist/validate-cookie-parameters.d.ts

@@ -0,0 +1,9 @@
+import type { AnyObject } from '@scalar/types/utils';
+import type { ErrorObject } from './types.js';
+/**
+ * Checks cookie serialization declarations in OpenAPI 3.2 documents.
+ * Resolve references before calling to also check referenced parameters and schemas.
+ * Only OpenAPI parameter locations are visited; examples and extensions are data.
+ */
+export declare const validateCookieParameters: (specification: AnyObject) => ErrorObject[];
+//# sourceMappingURL=validate-cookie-parameters.d.ts.map

package/dist/validate-cookie-parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-cookie-parameters.d.ts","sourceRoot":"","sources":["../src/validate-cookie-parameters.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,eAAe,SAAS,KAAG,WAAW,EAoG9E,CAAA"}

package/dist/validate-cookie-parameters.js

@@ -0,0 +1,103 @@
+import { getCookieSerializationError } from '@scalar/helpers/http/get-cookie-serialization-error';
+import { isHttpMethod } from '@scalar/helpers/http/is-http-method';
+import { isObject } from '@scalar/helpers/object/is-object';
+/**
+ * Checks cookie serialization declarations in OpenAPI 3.2 documents.
+ * Resolve references before calling to also check referenced parameters and schemas.
+ * Only OpenAPI parameter locations are visited; examples and extensions are data.
+ */
+export const validateCookieParameters = (specification) => {
+    const [major, minor] = String(specification.openapi).split('.');
+    if (major !== '3' || minor !== '2') {
+        return [];
+    }
+    const errors = [];
+    const ancestors = new WeakSet();
+    const checkParameter = (parameter, path) => {
+        if (!isObject(parameter) || 'content' in parameter || typeof parameter.name !== 'string') {
+            return;
+        }
+        const message = getCookieSerializationError({
+            name: parameter.name,
+            in: String(parameter.in),
+            style: typeof parameter.style === 'string' ? parameter.style : undefined,
+            explode: typeof parameter.explode === 'boolean' ? parameter.explode : undefined,
+            schema: parameter.schema,
+        });
+        if (message) {
+            errors.push({ path: [...path, 'explode'], message });
+        }
+    };
+    const checkParameters = (parameters, path) => {
+        if (Array.isArray(parameters)) {
+            parameters.forEach((parameter, index) => checkParameter(parameter, [...path, String(index)]));
+        }
+    };
+    const visitCallback = (callback, path) => {
+        if (!isObject(callback) || ancestors.has(callback)) {
+            return;
+        }
+        ancestors.add(callback);
+        for (const [expression, pathItem] of Object.entries(callback)) {
+            if (!expression.startsWith('x-') && expression !== '$ref') {
+                visitPathItem(pathItem, [...path, expression]);
+            }
+        }
+        ancestors.delete(callback);
+    };
+    const visitOperation = (operation, path) => {
+        if (!isObject(operation)) {
+            return;
+        }
+        checkParameters(operation.parameters, [...path, 'parameters']);
+        if (isObject(operation.callbacks)) {
+            for (const [name, callback] of Object.entries(operation.callbacks)) {
+                visitCallback(callback, [...path, 'callbacks', name]);
+            }
+        }
+    };
+    const visitPathItem = (pathItem, path) => {
+        if (!isObject(pathItem) || ancestors.has(pathItem)) {
+            return;
+        }
+        ancestors.add(pathItem);
+        checkParameters(pathItem.parameters, [...path, 'parameters']);
+        for (const [method, operation] of Object.entries(pathItem)) {
+            if (isHttpMethod(method)) {
+                visitOperation(operation, [...path, method]);
+            }
+        }
+        if (isObject(pathItem.additionalOperations)) {
+            for (const [method, operation] of Object.entries(pathItem.additionalOperations)) {
+                visitOperation(operation, [...path, 'additionalOperations', method]);
+            }
+        }
+        ancestors.delete(pathItem);
+    };
+    for (const key of ['paths', 'webhooks']) {
+        const items = specification[key];
+        if (isObject(items)) {
+            for (const [name, pathItem] of Object.entries(items)) {
+                if (!name.startsWith('x-')) {
+                    visitPathItem(pathItem, [key, name]);
+                }
+            }
+        }
+    }
+    const components = specification.components;
+    if (isObject(components)) {
+        for (const [key, visit] of [
+            ['parameters', checkParameter],
+            ['pathItems', visitPathItem],
+            ['callbacks', visitCallback],
+        ]) {
+            const items = components[key];
+            if (isObject(items)) {
+                for (const [name, item] of Object.entries(items)) {
+                    visit(item, ['components', key, name]);
+                }
+            }
+        }
+    }
+    return errors;
+};

package/dist/validate-path-parameters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-path-parameters.d.ts","sourceRoot":"","sources":["../src/validate-path-parameters.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAmB1C;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,SAAS,GAAG,WAAW,EAAE,CAoE9E"}
+{"version":3,"file":"validate-path-parameters.d.ts","sourceRoot":"","sources":["../src/validate-path-parameters.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAmB1C;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,SAAS,GAAG,WAAW,EAAE,CAyE9E"}

package/dist/validate-path-parameters.js

@@ -1,3 +1,4 @@
+import { HTTP_METHODS } from '@scalar/helpers/http/http-methods';
 import { isObjectLike } from '@scalar/helpers/object/is-object';
 import { deduplicateErrors } from '@scalar/json-schema-validator';
 /**
@@ -8,7 +9,7 @@ import { deduplicateErrors } from '@scalar/json-schema-validator';
  * hand-constructed document rather than validating them.
  */
 const isRecord = (value) => isObjectLike(value) && !Array.isArray(value);
-const OPERATION_KEYS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+const OPERATION_KEYS = new Set(HTTP_METHODS);
 const PATH_PARAMETER_PATTERN = /{([^}]+)}/g;
 /**
  * Validates path-template semantics that are not enforced by the JSON schema.
@@ -23,7 +24,15 @@ export function validatePathParameters(specification) {
         if (!isRecord(pathItem)) {
             continue;
         }
-        const operations = Object.entries(pathItem).filter(([key, value]) => OPERATION_KEYS.has(key) && isRecord(value));
+        const operations = Object.entries(pathItem).flatMap(([key, value]) => {
+            if (OPERATION_KEYS.has(key) && isRecord(value)) {
+                return [{ operation: value, path: ['paths', pathName, key] }];
+            }
+            if (key === 'additionalOperations' && isRecord(value)) {
+                return Object.entries(value).flatMap(([method, operation]) => isRecord(operation) ? [{ operation, path: ['paths', pathName, 'additionalOperations', method] }] : []);
+            }
+            return [];
+        });
         // Preserve the repo's current behaviour for empty path items.
         if (operations.length === 0) {
             continue;
@@ -38,13 +47,8 @@ export function validatePathParameters(specification) {
                 });
             }
         }
-        for (const [operationKey, operation] of operations) {
-            const operationParameters = getPathParameters(operation.parameters, [
-                'paths',
-                pathName,
-                operationKey,
-                'parameters',
-            ]);
+        for (const { operation, path } of operations) {
+            const operationParameters = getPathParameters(operation.parameters, [...path, 'parameters']);
             for (const parameter of operationParameters) {
                 if (!templateParameters.has(parameter.name)) {
                     errors.push({
@@ -57,7 +61,7 @@ export function validatePathParameters(specification) {
             for (const templateParameter of templateParameters) {
                 if (!effectiveParameters.has(templateParameter)) {
                     errors.push({
-                        path: ['paths', pathName, operationKey],
+                        path,
                         message: `Declared path parameter "${templateParameter}" needs to be defined as a path parameter at either the path or operation level`,
                     });
                 }

package/dist/validate.d.ts

@@ -15,12 +15,18 @@ export type ValidateOptions = ThrowOnErrorOption & {
      * @default false
      */
     checkPathParameters?: boolean;
+    /**
+     * Check OpenAPI 3.2 cookie serialization declarations.
+     * Resolve references first for complete coverage.
+     * @default true
+     */
+    checkCookieParameters?: boolean;
 };
 /**
  * Validates a single OpenAPI document against the OpenAPI Specification.
  *
  * Schema validation is delegated to `@scalar/json-schema-validator`; version
- * detection and the path-parameter semantic checks are OpenAPI-specific.
+ * detection and parameter semantic checks are OpenAPI-specific.
  *
  * This validator is strict about the specification: every required field,
  * including `info.version`, must be present. Callers that want to be lenient

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAMpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAGpE,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG;IACjD;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B,CAAA;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CAEnG"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAMpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAIpE,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG;IACjD;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC,CAAA;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CAEnG"}

package/dist/validate.js

@@ -3,6 +3,7 @@ import { detectVersion } from './detect-version.js';
 import { ERRORS } from './errors.js';
 import { explainComponentReferences } from './explain-component-references.js';
 import { OpenApiSpecifications } from './specifications.js';
+import { validateCookieParameters } from './validate-cookie-parameters.js';
 import { validatePathParameters } from './validate-path-parameters.js';
 const validateDocument = createSpecificationValidator({
     schemas: OpenApiSpecifications,
@@ -11,16 +12,18 @@ const validateDocument = createSpecificationValidator({
     formats: (version) => (version === '3.1' || version === '3.2' ? { 'media-range': true } : undefined),
     errors: { emptyOrInvalid: ERRORS.EMPTY_OR_INVALID, versionNotSupported: ERRORS.OPENAPI_VERSION_NOT_SUPPORTED },
     transformErrors: explainComponentReferences,
-    // Path-template semantics that the JSON schema cannot express. These need a
-    // fully resolved document (a path parameter can be declared via `$ref`), so
-    // they are opt-in: callers that resolve references first can enable them.
-    postValidate: (specification, _version, options) => options?.checkPathParameters ? validatePathParameters(specification) : [],
+    // Cookie declarations can be checked without resolving references. Path-template
+    // checks require a resolved document to avoid reporting referenced parameters as missing.
+    postValidate: (specification, _version, options) => [
+        ...(options?.checkPathParameters ? validatePathParameters(specification) : []),
+        ...(options?.checkCookieParameters === false ? [] : validateCookieParameters(specification)),
+    ],
 });
 /**
  * Validates a single OpenAPI document against the OpenAPI Specification.
  *
  * Schema validation is delegated to `@scalar/json-schema-validator`; version
- * detection and the path-parameter semantic checks are OpenAPI-specific.
+ * detection and parameter semantic checks are OpenAPI-specific.
  *
  * This validator is strict about the specification: every required field,
  * including `info.version`, must be present. Callers that want to be lenient

package/package.json

@@ -17,7 +17,7 @@
     "validator",
     "typescript"
   ],
-  "version": "0.1.10",
+  "version": "0.1.11",
   "engines": {
     "node": ">=22"
   },
@@ -38,13 +38,13 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@scalar/helpers": "0.16.1",
-    "@scalar/json-schema-validator": "0.1.10",
-    "@scalar/types": "0.23.0",
+    "@scalar/helpers": "0.16.2",
+    "@scalar/json-schema-validator": "0.1.11",
+    "@scalar/types": "0.23.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@scalar/themes": "0.18.1",
+    "@scalar/themes": "0.19.0",
     "@scalar/use-codemirror": "0.14.15",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^24.1.0",