@scalar/openapi-parser 0.28.16 → 0.29.0

package/dist/utils/validate.d.ts

@@ -1,7 +1,12 @@
 import type { Filesystem, ThrowOnErrorOption, UnknownObject, ValidateResult } from '../types/index.js';
 export type ValidateOptions = ThrowOnErrorOption;
 /**
- * Validates an OpenAPI document
+ * Validates an OpenAPI document.
+ *
+ * Schema and semantic validation are delegated to `@scalar/openapi-validator`.
+ * Reference resolution stays in the parser: references are resolved here and any
+ * resolution errors are merged into the result, so the behaviour matches the
+ * previous, self-contained validator.
  */
 export declare function validate(value: string | UnknownObject | Filesystem, options?: ValidateOptions): Promise<ValidateResult>;
 //# sourceMappingURL=validate.d.ts.map

package/dist/utils/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EAEV,kBAAkB,EAClB,aAAa,EACb,cAAc,EACf,MAAM,eAAe,CAAA;AAItB,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAA;AAqBhD;;GAEG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,UAAU,EAC1C,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CA6CzB"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,UAAU,EAEV,kBAAkB,EAClB,aAAa,EACb,cAAc,EACf,MAAM,eAAe,CAAA;AAMtB,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAA;AAqBhD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,UAAU,EAC1C,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC,CAyFzB"}

package/dist/utils/validate.js

@@ -1,5 +1,9 @@
-import { Validator } from '../lib/Validator/Validator.js';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { validate as validateDocument, validatePathParameters } from '@scalar/openapi-validator';
+import { ERRORS } from '../configuration/index.js';
+import { getEntrypoint } from './get-entrypoint.js';
 import { makeFilesystem } from './make-filesystem.js';
+import { resolveReferences } from './resolve-references.js';
 const withStrictSpecification = (specification, version) => {
     if (!specification || typeof specification !== 'object') {
         return undefined;
@@ -13,44 +17,86 @@ const withStrictSpecification = (specification, version) => {
     return undefined;
 };
 /**
- * Validates an OpenAPI document
+ * Validates an OpenAPI document.
+ *
+ * Schema and semantic validation are delegated to `@scalar/openapi-validator`.
+ * Reference resolution stays in the parser: references are resolved here and any
+ * resolution errors are merged into the result, so the behaviour matches the
+ * previous, self-contained validator.
  */
 export function validate(value, options) {
     try {
         const filesystem = makeFilesystem(value);
-        const validator = new Validator();
-        const result = validator.validate(filesystem, options);
-        /**
-         * Currently contains no asynchronous logic, but returns a Promise
-         * to preserve API compatibility and allow async logic in the future.
-         */
-        if (result.valid) {
-            const specification = withStrictSpecification(validator.specification, validator.version);
-            if (!specification) {
-                return Promise.resolve({
-                    valid: false,
-                    errors: [
-                        {
-                            message: `Validated OpenAPI ${validator.version} document is missing required top-level version field.`,
-                        },
-                    ],
-                    schema: result.schema,
-                    specification: validator.specification,
-                    version: validator.version,
-                });
+        const entrypoint = getEntrypoint(filesystem);
+        // A filesystem without an entrypoint (for example a top-level array) has no
+        // document to validate.
+        if (!entrypoint || entrypoint.specification === undefined || entrypoint.specification === null) {
+            if (options?.throwOnError) {
+                throw new Error(ERRORS.EMPTY_OR_INVALID);
             }
+            return Promise.resolve({ valid: false, errors: [{ message: ERRORS.EMPTY_OR_INVALID }] });
+        }
+        const specification = entrypoint.specification;
+        // Be lenient about a missing `info.version`: default it before validation so
+        // documents that omit this required field still validate. The standalone
+        // `@scalar/openapi-validator` is strict and would otherwise reject them.
+        //
+        // Semver recommends `0.1.0` as the starting version for initial development,
+        // which makes it the right stand-in for a document that never declared one.
+        // (This used to be `0.0.1`, which semver does not suggest anywhere.)
+        if (isObject(specification) && isObject(specification.info) && typeof specification.info.version !== 'string') {
+            specification.info.version = '0.1.0';
+        }
+        // Schema and version validation only (no reference resolution). Runs first so
+        // empty/invalid input reports the same error, in the same order, including
+        // when `throwOnError` is set. Path-parameter semantics are left off here (the
+        // validator's default) and run below on the resolved document, so parameters
+        // declared via `$ref` are seen (validating the unresolved document would
+        // report them as missing).
+        const outcome = validateDocument(specification, options);
+        // Resolve references whenever the document passed schema validation.
+        // `outcome.schema` is only set once schema and version validation succeeded.
+        const passedSchemaValidation = outcome.schema !== undefined;
+        const resolved = passedSchemaValidation ? resolveReferences(filesystem, options) : undefined;
+        const referenceErrors = resolved?.errors ?? [];
+        const schema = (resolved?.schema ?? outcome.schema);
+        // Path-template semantics run on the resolved document (schema validation
+        // stays on the unresolved one to avoid following circular references). This
+        // matches the previous validator, which merged reference and semantic errors.
+        const semanticErrors = passedSchemaValidation
+            ? validatePathParameters((schema ?? specification))
+            : [];
+        const errors = [...(outcome.errors ?? []), ...referenceErrors, ...semanticErrors];
+        const valid = outcome.valid && referenceErrors.length === 0 && semanticErrors.length === 0;
+        if (!valid) {
+            return Promise.resolve({
+                valid: false,
+                errors,
+                schema,
+                specification,
+                version: outcome.version,
+            });
+        }
+        const strictSpecification = withStrictSpecification(specification, outcome.version);
+        if (!strictSpecification) {
             return Promise.resolve({
-                ...result,
+                valid: false,
+                errors: [
+                    {
+                        message: `Validated OpenAPI ${outcome.version} document is missing required top-level version field.`,
+                    },
+                ],
+                schema,
                 specification,
-                version: validator.version,
+                version: outcome.version,
             });
         }
         return Promise.resolve({
-            valid: false,
-            errors: result.errors,
-            schema: result.schema,
-            specification: validator.specification,
-            version: validator.version,
+            valid: true,
+            errors,
+            schema: schema,
+            specification: strictSpecification,
+            version: outcome.version,
         });
     }
     catch (err) {

package/package.json

@@ -17,7 +17,7 @@
     "parser",
     "typescript"
   ],
-  "version": "0.28.16",
+  "version": "0.29.0",
   "engines": {
     "node": ">=22"
   },
@@ -48,23 +48,19 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "ajv": "^8.17.1",
-    "ajv-draft-04": "^1.0.0",
-    "ajv-formats": "^3.0.1",
-    "jsonpointer": "^5.0.1",
-    "leven": "^4.0.0",
     "yaml": "^2.9.0",
-    "@scalar/helpers": "0.11.1",
+    "@scalar/helpers": "0.11.2",
+    "@scalar/json-magic": "0.13.3",
+    "@scalar/openapi-upgrader": "0.2.15",
+    "@scalar/openapi-validator": "0.1.0",
     "@scalar/openapi-types": "0.9.5",
-    "@scalar/json-magic": "0.13.2",
-    "@scalar/openapi-upgrader": "0.2.15"
+    "@scalar/types": "0.18.3"
   },
   "devDependencies": {
     "@apidevtools/swagger-parser": "10.1.0",
     "@types/node": "^24.1.0",
     "just-diff": "^6.0.2",
-    "vite": "8.1.5",
-    "@scalar/types": "0.18.2"
+    "vite": "8.1.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",

package/dist/lib/Validator/Validator.d.ts

@@ -1,22 +0,0 @@
-import { type ValidateFunction } from 'ajv';
-import { type OpenApiVersion } from '../../configuration/index.js';
-import type { Filesystem, ThrowOnErrorOption, UnknownObject, ValidationOutcome } from '../../types/index.js';
-export declare class Validator {
-    version: OpenApiVersion;
-    static supportedVersions: ("2.0" | "3.0" | "3.1" | "3.2")[];
-    protected ajvValidators: Record<string, ValidateFunction>;
-    protected errors: string;
-    protected specificationVersion: string;
-    protected specificationType: string;
-    specification: UnknownObject;
-    private isMutableRecord;
-    /**
-     * Checks whether a specification is valid and all references can be resolved.
-     */
-    validate(filesystem: Filesystem, options?: ThrowOnErrorOption): ValidationOutcome;
-    /**
-     * Ajv JSON schema validator
-     */
-    getAjvValidator(version: OpenApiVersion): ValidateFunction;
-}
-//# sourceMappingURL=Validator.d.ts.map

package/dist/lib/Validator/Validator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Validator.d.ts","sourceRoot":"","sources":["../../../src/lib/Validator/Validator.ts"],"names":[],"mappings":"AAAA,OAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAKhD,OAAO,EAAiC,KAAK,cAAc,EAAmB,MAAM,iBAAiB,CAAA;AACrG,OAAO,KAAK,EAAE,UAAU,EAAmB,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAetH,qBAAa,SAAS;IACb,OAAO,EAAE,cAAc,CAAA;IAE9B,OAAc,iBAAiB,oCAAkB;IAGjD,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAK;IAE9D,SAAS,CAAC,MAAM,EAAE,MAAM,CAAA;IAExB,SAAS,CAAC,oBAAoB,EAAE,MAAM,CAAA;IAEtC,SAAS,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAE5B,aAAa,EAAE,aAAa,CAAA;IAEnC,OAAO,CAAC,eAAe;IAIvB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,iBAAiB;IAmGjF;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,gBAAgB;CAkC3D"}

package/dist/lib/Validator/Validator.js

@@ -1,146 +0,0 @@
-import Ajv, {} from 'ajv';
-import Ajv2020 from 'ajv/dist/2020.js';
-import Ajv04 from 'ajv-draft-04';
-import addFormats from 'ajv-formats';
-import { ERRORS, OpenApiSpecifications, OpenApiVersions } from '../../configuration/index.js';
-import { details as getOpenApiVersion } from '../../utils/details.js';
-import { resolveReferences } from '../../utils/resolve-references.js';
-import { transformErrors } from '../../utils/transform-errors.js';
-import { validatePathParameters } from '../../utils/validate-path-parameters.js';
-/**
- * Configure available JSON Schema versions
- */
-const jsonSchemaVersions = {
-    'http://json-schema.org/draft-04/schema#': Ajv04,
-    'http://json-schema.org/draft-07/schema#': Ajv,
-    'https://json-schema.org/draft/2020-12/schema': Ajv2020,
-};
-export class Validator {
-    version;
-    static supportedVersions = OpenApiVersions;
-    // Object with function *or* object { errors: string }
-    ajvValidators = {};
-    errors;
-    specificationVersion;
-    specificationType;
-    specification;
-    isMutableRecord(value) {
-        return typeof value === 'object' && value !== null && !Array.isArray(value);
-    }
-    /**
-     * Checks whether a specification is valid and all references can be resolved.
-     */
-    validate(filesystem, options) {
-        const entrypoint = filesystem.find((file) => file.isEntrypoint);
-        const specification = entrypoint?.specification;
-        // TODO: How does this work with a filesystem?
-        this.specification = specification;
-        // TODO: defaulting info.version to keep parser compatible with the previous one
-        // we should bubble this error up and not throw on it
-        if (this.isMutableRecord(this.specification) &&
-            this.isMutableRecord(this.specification.info) &&
-            typeof this.specification.info.version !== 'string') {
-            this.specification.info.version = '0.0.1';
-        }
-        try {
-            // AnyObject is empty or invalid
-            if (specification === undefined || specification === null) {
-                if (options?.throwOnError) {
-                    throw new Error(ERRORS.EMPTY_OR_INVALID);
-                }
-                return {
-                    valid: false,
-                    errors: transformErrors(specification, ERRORS.EMPTY_OR_INVALID),
-                };
-            }
-            // Meta data about the specification
-            const { version, specificationType, specificationVersion } = getOpenApiVersion(specification);
-            this.version = version;
-            this.specificationVersion = specificationVersion;
-            this.specificationType = specificationType;
-            // AnyObject is not supported
-            if (!version) {
-                if (options?.throwOnError) {
-                    throw new Error(ERRORS.OPENAPI_VERSION_NOT_SUPPORTED);
-                }
-                return {
-                    valid: false,
-                    errors: transformErrors(specification, ERRORS.OPENAPI_VERSION_NOT_SUPPORTED),
-                };
-            }
-            // Get the correct OpenAPI validator
-            const validateSchema = this.getAjvValidator(version);
-            const schemaResult = validateSchema(specification);
-            // Error handling
-            if (validateSchema.errors) {
-                if (validateSchema.errors.length > 0) {
-                    if (options?.throwOnError) {
-                        throw new Error(validateSchema.errors[0].message);
-                    }
-                    return {
-                        valid: false,
-                        errors: transformErrors(specification, validateSchema.errors),
-                    };
-                }
-            }
-            // Check if the references are valid
-            const resolvedReferences = resolveReferences(filesystem, options);
-            const semanticErrors = validatePathParameters(resolvedReferences.schema);
-            const errors = [...resolvedReferences.errors, ...semanticErrors];
-            const valid = schemaResult && resolvedReferences.valid && semanticErrors.length === 0;
-            if (!valid) {
-                return {
-                    valid: false,
-                    errors,
-                    schema: resolvedReferences.schema,
-                };
-            }
-            return {
-                valid: true,
-                errors,
-                schema: resolvedReferences.schema,
-            };
-        }
-        catch (error) {
-            // Something went horribly wrong!
-            if (options?.throwOnError) {
-                throw error;
-            }
-            return {
-                valid: false,
-                errors: transformErrors(specification, error.message ?? error),
-            };
-        }
-    }
-    /**
-     * Ajv JSON schema validator
-     */
-    getAjvValidator(version) {
-        // Schema loaded already
-        if (this.ajvValidators[version]) {
-            return this.ajvValidators[version];
-        }
-        // Load OpenAPI Schema
-        const schema = OpenApiSpecifications[version];
-        // Load JSON Schema
-        const AjvClass = jsonSchemaVersions[schema.$schema];
-        // Get the correct Ajv validator
-        const ajv = new AjvClass({
-            // Ajv is a bit too strict in its strict validation of OpenAPI schemas.
-            // Switch strict mode off.
-            strict: false,
-            // Enable discriminator support for better oneOf error messages
-            discriminator: true,
-            // Show all errors, not just the first one
-            allErrors: true,
-        });
-        // Register formats
-        // https://ajv.js.org/packages/ajv-formats.html#formats
-        addFormats(ajv);
-        // OpenAPI 3.1 and 3.2 uses media-range format
-        if (version === '3.1' || version === '3.2') {
-            ajv.addFormat('media-range', true);
-        }
-        return (this.ajvValidators[version] = ajv.compile(schema));
-    }
-}