@scalar/openapi-parser 0.25.7 → 0.25.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalar/openapi-parser
 
+## 0.25.8
+
+### Patch Changes
+
+- [#8579](https://github.com/scalar/scalar/pull/8579): feat(openapi-parser): improve format validation error messages for $ref with non-ASCII characters
+
 ## 0.25.7
 
 ## 0.25.6

package/dist/utils/betterAjvErrors/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/betterAjvErrors/helpers.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,mBAAmB,EAIpB,MAAM,qBAAqB,CAAA;AA8J5B,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,SAAS,KAAA,EAAE,OAAO,KAAA,yBAKlD"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/betterAjvErrors/helpers.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,mBAAmB,EAKpB,MAAM,qBAAqB,CAAA;AAgK5B,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,SAAS,KAAA,EAAE,OAAO,KAAA,yBAKlD"}

package/dist/utils/betterAjvErrors/helpers.js

@@ -1,6 +1,6 @@
 import { concatAll, getChildren, getErrors, getSiblings, isAdditionalPropertiesError, isAnyOfError, isEnumError, isIfError, isOneOfError, isRequiredError, isUnevaluatedPropertiesError, notUndefined, } from './utils.js';
-import { AdditionalPropValidationError, DefaultValidationError, EnumValidationError, PatternValidationError, RequiredValidationError, UnevaluatedPropValidationError, } from './validation-errors/index.js';
-const JSON_POINTERS_REGEX = /\/[\w_-]+(\/\d+)?/g;
+import { AdditionalPropValidationError, DefaultValidationError, EnumValidationError, FormatValidationError, PatternValidationError, RequiredValidationError, UnevaluatedPropValidationError, } from './validation-errors/index.js';
+const JSON_POINTERS_REGEX = /\/[\w$_-]+(\/\d+)?/g;
 // Make a tree of errors from ajv errors array
 function makeTree(ajvErrors = []) {
     const root = { children: {} };
@@ -134,6 +134,8 @@ function createErrorInstances(root, options) {
                 return ret.concat(new AdditionalPropValidationError(error, options));
             case 'pattern':
                 return ret.concat(new PatternValidationError(error, options));
+            case 'format':
+                return ret.concat(new FormatValidationError(error, options));
             case 'required':
                 return ret.concat(new RequiredValidationError(error, options));
             case 'unevaluatedProperties':

package/dist/utils/betterAjvErrors/validation-errors/format.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Enhanced error messages for `format` keyword validation failures.
+ *
+ * Currently provides context for:
+ * - `uri-reference` format on `$ref` paths (non-ASCII characters, etc.)
+ *
+ * To add a new format enhancer, add a case to the switch in `getError()`.
+ */
+export default class FormatValidationError extends BaseValidationError {
+    constructor(...args: any[]);
+    name: string;
+    getError(): {
+        message: string;
+        path: string;
+    };
+    /**
+     * Builds a contextual error message for uri-reference format failures on $ref values.
+     */
+    _getUriReferenceMessage(): string;
+    /**
+     * Attempts to extract the actual $ref value from the specification
+     * by walking the instancePath through the spec object.
+     */
+    _extractRefValue(): string;
+}
+import BaseValidationError from './base.js';
+//# sourceMappingURL=format.d.ts.map

package/dist/utils/betterAjvErrors/validation-errors/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../../src/utils/betterAjvErrors/validation-errors/format.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH;IACE,4BAIC;IAFC,aAAmC;IAIrC;;;MAkBC;IAED;;OAEG;IACH,kCAYC;IAED;;;OAGG;IACH,2BA0BC;CACF;gCArF+B,QAAQ"}

package/dist/utils/betterAjvErrors/validation-errors/format.js

@@ -0,0 +1,73 @@
+import BaseValidationError from './base.js';
+/**
+ * Enhanced error messages for `format` keyword validation failures.
+ *
+ * Currently provides context for:
+ * - `uri-reference` format on `$ref` paths (non-ASCII characters, etc.)
+ *
+ * To add a new format enhancer, add a case to the switch in `getError()`.
+ */
+export default class FormatValidationError extends BaseValidationError {
+    constructor(...args) {
+        super(...args);
+        this.name = 'FormatValidationError';
+        this.options.isSkipEndLocation = true;
+    }
+    getError() {
+        const { keyword, message, params, instancePath: errorPath } = this.options;
+        const path = this.instancePath;
+        const format = params?.format;
+        // uri-reference format on $ref paths
+        if (format === 'uri-reference' && path?.endsWith('/$ref')) {
+            return {
+                message: this._getUriReferenceMessage(),
+                path,
+            };
+        }
+        // Default: fall back to the same format as DefaultValidationError
+        return {
+            message: `${keyword} ${message}`,
+            path,
+        };
+    }
+    /**
+     * Builds a contextual error message for uri-reference format failures on $ref values.
+     */
+    _getUriReferenceMessage() {
+        const refValue = this._extractRefValue();
+        if (refValue && /[^\x00-\x7F]/.test(refValue)) {
+            return `$ref "${refValue}" contains non-ASCII characters`;
+        }
+        if (refValue) {
+            return `$ref "${refValue}" is not a valid URI reference`;
+        }
+        return '$ref is not a valid URI reference';
+    }
+    /**
+     * Attempts to extract the actual $ref value from the specification
+     * by walking the instancePath through the spec object.
+     */
+    _extractRefValue() {
+        const spec = this.schema;
+        if (!spec || typeof spec !== 'object') {
+            return null;
+        }
+        const path = this.instancePath;
+        if (!path) {
+            return null;
+        }
+        // Parse JSON Pointer segments, decoding ~1 (/) and ~0 (~)
+        const segments = path
+            .split('/')
+            .filter(Boolean)
+            .map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+        let current = spec;
+        for (const segment of segments) {
+            if (current === null || current === undefined || typeof current !== 'object') {
+                return null;
+            }
+            current = current[segment];
+        }
+        return typeof current === 'string' ? current : null;
+    }
+}

package/dist/utils/betterAjvErrors/validation-errors/index.d.ts

@@ -1,6 +1,7 @@
 export { default as AdditionalPropValidationError } from "./additional-prop.js";
 export { default as DefaultValidationError } from "./default.js";
 export { default as EnumValidationError } from "./enum.js";
+export { default as FormatValidationError } from "./format.js";
 export { default as PatternValidationError } from "./pattern.js";
 export { default as RequiredValidationError } from "./required.js";
 export { default as UnevaluatedPropValidationError } from "./unevaluated-prop.js";

package/dist/utils/betterAjvErrors/validation-errors/index.js

@@ -1,6 +1,7 @@
 export { default as AdditionalPropValidationError } from './additional-prop.js';
 export { default as DefaultValidationError } from './default.js';
 export { default as EnumValidationError } from './enum.js';
+export { default as FormatValidationError } from './format.js';
 export { default as PatternValidationError } from './pattern.js';
 export { default as RequiredValidationError } from './required.js';
 export { default as UnevaluatedPropValidationError } from './unevaluated-prop.js';

package/package.json

@@ -17,7 +17,7 @@
     "parser",
     "typescript"
   ],
-  "version": "0.25.7",
+  "version": "0.25.8",
   "engines": {
     "node": ">=22"
   },
@@ -54,17 +54,17 @@
     "jsonpointer": "^5.0.1",
     "leven": "^4.0.0",
     "yaml": "^2.8.0",
-    "@scalar/helpers": "0.4.2",
-    "@scalar/json-magic": "0.12.4",
-    "@scalar/openapi-upgrader": "0.2.3",
-    "@scalar/openapi-types": "0.6.1"
+    "@scalar/helpers": "0.4.3",
+    "@scalar/openapi-types": "0.7.0",
+    "@scalar/openapi-upgrader": "0.2.4",
+    "@scalar/json-magic": "0.12.5"
   },
   "devDependencies": {
     "@apidevtools/swagger-parser": "10.1.0",
     "@types/node": "^24.1.0",
     "just-diff": "^6.0.2",
     "vite": "8.0.0",
-    "@scalar/types": "0.7.5"
+    "@scalar/types": "0.7.6"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",