oatschema 0.0.1 → 0.1.0

package/dist/validation.js

@@ -0,0 +1,328 @@
+// SPDX-FileCopyrightText: 2026 The OATS Authors
+// SPDX-License-Identifier: Apache-2.0
+import { describe, missingFromVersion, shorten, UnknownSchemaError, unbundledVersion } from "./errors.js";
+import { withFormats } from "./formats.js";
+import { isSchemaVersion, SCHEMA_VERSION } from "./names.js";
+const PATH_PART_LIMIT = 100;
+const MESSAGE_LIMIT = 1000;
+const VALUE = "…";
+const ARRAY_KEYWORDS = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+const DROPPED_KEYWORDS = new Set(["if", "propertyNames"]);
+/**
+ * A record that does not conform to its schema.
+ *
+ * `path` locates the failing value within the record, `schemaPath` the schema location that rejected it,
+ * and `keyword` the JSON Schema keyword at the end of `schemaPath` (`"maxLength"`, `"required"`, …).
+ *
+ * `reason` shows each value from the record as `…`, quoting only property names, and is at most 1,000 characters.
+ * `message` adds the schema and the location, as in `classification 0.8.0 at /labels/0/score: … is greater than the
+ * maximum of 1`. Each string in `path` is at most 100 characters, and the location in `message` at most 1,000.
+ * The underlying validator's error is not kept.
+ */
+export class ValidationError extends Error {
+    /** Why the value was rejected, without the schema or the location. */
+    reason;
+    /** The schema's name. */
+    schemaName;
+    /** The exact schema version. */
+    schemaVersion;
+    /** The location of the failing value within the record. Array indices are numbers. */
+    path;
+    /** The location within the schema of the keyword that rejected the value. */
+    schemaPath;
+    /** The JSON Schema keyword that rejected the value. */
+    keyword;
+    constructor(reason, details) {
+        const bounded = shorten(String(reason), MESSAGE_LIMIT);
+        const path = Object.freeze(boundPath(details.path ?? []));
+        const schemaPath = Object.freeze(boundPath(details.schemaPath ?? []));
+        const name = shorten(String(details.schemaName), PATH_PART_LIMIT);
+        const version = shorten(String(details.schemaVersion), PATH_PART_LIMIT);
+        const location = shorten(path.join("/"), MESSAGE_LIMIT);
+        super(`${name} ${version} at /${location}: ${bounded}`);
+        this.reason = bounded;
+        this.schemaName = name;
+        this.schemaVersion = version;
+        this.path = path;
+        this.schemaPath = schemaPath;
+        this.keyword = shorten(String(details.keyword ?? lastKeyword(schemaPath)), PATH_PART_LIMIT);
+    }
+}
+Object.defineProperty(ValidationError.prototype, "name", {
+    value: "ValidationError",
+    writable: true,
+    configurable: true,
+    enumerable: false,
+});
+function boundPath(path) {
+    return [...path].map((part) => (typeof part === "number" ? part : shorten(String(part), PATH_PART_LIMIT)));
+}
+function lastKeyword(schemaPath) {
+    for (let index = schemaPath.length - 1; index >= 0; index--) {
+        const part = schemaPath[index];
+        if (typeof part === "string") {
+            return part;
+        }
+    }
+    return "";
+}
+function unescapePointer(part) {
+    return part.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function recordPath(pointer, record) {
+    if (pointer === "") {
+        return [];
+    }
+    const path = [];
+    let node = record;
+    for (const encoded of pointer.slice(1).split("/")) {
+        const part = unescapePointer(encoded);
+        if (Array.isArray(node) && /^(?:0|[1-9][0-9]*)$/.test(part)) {
+            const index = Number(part);
+            path.push(index);
+            node = node[index];
+        }
+        else {
+            path.push(shorten(part, PATH_PART_LIMIT));
+            node =
+                node !== null && typeof node === "object" && Object.hasOwn(node, part)
+                    ? node[part]
+                    : undefined;
+        }
+    }
+    return path;
+}
+function schemaLocation(pointer) {
+    const parts = pointer.replace(/^#/, "").split("/").slice(1).map(unescapePointer);
+    return parts.map((part, index) => index > 0 && ARRAY_KEYWORDS.has(parts[index - 1] ?? "") && /^(?:0|[1-9][0-9]*)$/.test(part) ? Number(part) : part);
+}
+function plural(count, singular, many) {
+    return `${String(count)} ${count === 1 ? singular : many}`;
+}
+function json(value) {
+    const text = JSON.stringify(value);
+    return text === undefined ? String(value) : text;
+}
+function quoteName(name) {
+    return JSON.stringify(shorten(String(name), PATH_PART_LIMIT));
+}
+function candidates(values) {
+    const list = Array.isArray(values) ? values.map(json) : [json(values)];
+    if (list.length <= 1) {
+        return list.join("");
+    }
+    if (list.length <= 3) {
+        return `${list.slice(0, -1).join(", ")} or ${list.at(-1)}`;
+    }
+    return `${list.slice(0, 2).join(", ")} or ${list.length - 2} other candidates`;
+}
+function reason({ raw, names }) {
+    const { keyword, params } = raw;
+    const value = raw.propertyName === undefined ? VALUE : quoteName(raw.propertyName);
+    switch (keyword) {
+        case "type": {
+            const types = String(params.type).split(",");
+            return types.length === 1
+                ? `${value} is not of type "${types[0]}"`
+                : `${value} is not of types ${types
+                    .sort()
+                    .map((type) => `"${type}"`)
+                    .join(", ")}`;
+        }
+        case "required":
+        case "dependentRequired":
+            return `${quoteName(params.missingProperty)} is a required property`;
+        case "additionalProperties":
+        case "unevaluatedProperties": {
+            const list = (names ?? []).map((name) => `'${shorten(String(name), PATH_PART_LIMIT)}'`);
+            const kind = keyword === "additionalProperties" ? "Additional" : "Unevaluated";
+            return `${kind} properties are not allowed (${list.join(", ")} ${list.length === 1 ? "was" : "were"} unexpected)`;
+        }
+        case "maxLength":
+            return `${value} is longer than ${plural(params.limit, "character", "characters")}`;
+        case "minLength":
+            return `${value} is shorter than ${plural(params.limit, "character", "characters")}`;
+        case "maxItems":
+        case "items":
+        case "unevaluatedItems":
+            return `${value} has more than ${plural(params.limit, "item", "items")}`;
+        case "minItems":
+            return `${value} has less than ${plural(params.limit, "item", "items")}`;
+        case "maxProperties":
+            return `${value} has more than ${plural(params.limit, "property", "properties")}`;
+        case "minProperties":
+            return `${value} has less than ${plural(params.limit, "property", "properties")}`;
+        case "minimum":
+            return `${value} is less than the minimum of ${String(params.limit)}`;
+        case "maximum":
+            return `${value} is greater than the maximum of ${String(params.limit)}`;
+        case "exclusiveMinimum":
+            return `${value} is less than or equal to the minimum of ${String(params.limit)}`;
+        case "exclusiveMaximum":
+            return `${value} is greater than or equal to the maximum of ${String(params.limit)}`;
+        case "multipleOf":
+            return `${value} is not a multiple of ${String(params.multipleOf)}`;
+        case "enum":
+            return `${value} is not one of ${candidates(params.allowedValues)}`;
+        case "const":
+            return `${json(params.allowedValue)} was expected`;
+        case "pattern":
+            return `${value} does not match ${json(params.pattern)}`;
+        case "format":
+            return `${value} is not a ${json(params.format)}`;
+        case "uniqueItems":
+            return `${value} has non-unique elements`;
+        case "anyOf":
+            return `${value} is not valid under any of the schemas listed in the 'anyOf' keyword`;
+        case "oneOf":
+            return Array.isArray(params.passingSchemas)
+                ? `${value} is valid under more than one of the schemas listed in the 'oneOf' keyword`
+                : `${value} is not valid under any of the schemas listed in the 'oneOf' keyword`;
+        case "contains":
+            return `None of ${value} are valid under the given schema`;
+        case "not":
+            return `${value} is not allowed by the 'not' keyword`;
+        case "false schema":
+            return `False schema does not allow ${value}`;
+        default:
+            return `${value} is not valid under the ${json(keyword)} keyword`;
+    }
+}
+function asRawErrors(errors) {
+    return Array.isArray(errors) ? errors : [];
+}
+function fold(errors) {
+    const kept = [];
+    errors.forEach((raw, index) => {
+        const branches = raw.params.branchErrors;
+        if (typeof branches === "number" && branches > 0) {
+            while ((kept.at(-1)?.index ?? -1) >= index - branches) {
+                kept.pop();
+            }
+        }
+        if (!DROPPED_KEYWORDS.has(raw.keyword)) {
+            kept.push({ index, raw });
+        }
+    });
+    const folded = [];
+    for (const { raw } of kept) {
+        if (raw.keyword === "additionalProperties" || raw.keyword === "unevaluatedProperties") {
+            const name = raw.params.additionalProperty ?? raw.params.unevaluatedProperty;
+            const previous = folded.at(-1);
+            if (previous?.names !== undefined &&
+                previous.raw.keyword === raw.keyword &&
+                previous.raw.instancePath === raw.instancePath &&
+                previous.raw.schemaPath === raw.schemaPath) {
+                if (previous.names.length < MESSAGE_LIMIT) {
+                    previous.names.push(name);
+                }
+                continue;
+            }
+            folded.push({ raw, names: [name] });
+            continue;
+        }
+        folded.push({ raw });
+    }
+    if (folded.length === 0) {
+        const last = errors.at(-1);
+        if (last !== undefined) {
+            folded.push({ raw: last });
+        }
+    }
+    return folded;
+}
+class CompiledSchemaValidator {
+    schemaName;
+    schemaVersion;
+    checkFormats;
+    #compiled;
+    constructor(name, version, checkFormats, compiled) {
+        this.schemaName = name;
+        this.schemaVersion = version;
+        this.checkFormats = checkFormats;
+        this.#compiled = compiled;
+        Object.freeze(this);
+    }
+    isValid(record) {
+        return withFormats(this.checkFormats, () => this.#compiled(record));
+    }
+    validate(record) {
+        const errors = this.#run(record);
+        const first = errors[0];
+        if (first !== undefined) {
+            throw this.#convert(first, record);
+        }
+    }
+    *iterErrors(record) {
+        for (const error of this.#run(record)) {
+            yield this.#convert(error, record);
+        }
+    }
+    #run(record) {
+        const compiled = this.#compiled;
+        return withFormats(this.checkFormats, () => (compiled(record) ? [] : fold(asRawErrors(compiled.errors))));
+    }
+    #convert(error, record) {
+        const schemaPath = schemaLocation(error.raw.schemaPath);
+        return new ValidationError(reason(error), {
+            schemaName: this.schemaName,
+            schemaVersion: this.schemaVersion,
+            path: recordPath(error.raw.instancePath, record),
+            schemaPath,
+            keyword: lastKeyword(schemaPath),
+        });
+    }
+    get [Symbol.toStringTag]() {
+        return `Validator ${this.schemaName} ${this.schemaVersion}${this.checkFormats ? "" : " checkFormats=false"}`;
+    }
+}
+const CACHE = new Map();
+function checkFormatsOption(options) {
+    if (options === undefined) {
+        return true;
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError(`options must be an object, not ${describe(options)}`);
+    }
+    for (const key of Object.keys(options)) {
+        if (key !== "checkFormats") {
+            throw new TypeError(`unknown option ${describe(key)}; the only option is "checkFormats"`);
+        }
+    }
+    const check = options.checkFormats;
+    if (check === undefined) {
+        return true;
+    }
+    if (typeof check !== "boolean") {
+        throw new TypeError(`checkFormats must be true or false, not ${describe(check)}`);
+    }
+    return check;
+}
+/** @internal */
+export function versionValidator(name, versions, version, options) {
+    const check = checkFormatsOption(options);
+    const resolved = version === undefined ? SCHEMA_VERSION : version;
+    if (!isSchemaVersion(resolved)) {
+        throw unbundledVersion(name, resolved);
+    }
+    const compiled = versions.get(resolved);
+    if (compiled === undefined) {
+        throw missingFromVersion(name, resolved);
+    }
+    const key = `${name} ${resolved} ${check}`;
+    let validator = CACHE.get(key);
+    if (validator === undefined) {
+        validator = new CompiledSchemaValidator(name, resolved, check, compiled);
+        CACHE.set(key, validator);
+    }
+    return validator;
+}
+/** @internal */
+export function tableValidator(table, name, version, options) {
+    const versions = typeof name === "string" ? table.get(name) : undefined;
+    if (versions === undefined) {
+        checkFormatsOption(options);
+        throw new UnknownSchemaError(name);
+    }
+    return versionValidator(name, versions, version, options);
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "oatschema",
-  "version": "0.0.1",
-  "description": "OATS (Open Annotation Task Schemas) JSON schemas, bundled for JavaScript and TypeScript.",
+  "version": "0.1.0",
+  "description": "OATS (Open Annotation Task Schemas) JSON schemas and precompiled validators for JavaScript and TypeScript.",
   "keywords": [
     "oats",
     "json-schema",
     "annotation",
     "schema",
+    "validation",
     "machine-learning"
   ],
   "homepage": "https://oatschema.org",
@@ -26,31 +27,48 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./validate": {
+      "types": "./dist/validate.d.ts",
+      "default": "./dist/validate.js"
+    },
+    "./validate/*": {
+      "types": "./dist/validate/*.d.ts",
+      "default": "./dist/validate/*.js"
+    },
+    "./ajv": {
+      "types": "./dist/ajv.d.ts",
+      "default": "./dist/ajv.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
   "files": [
     "dist/",
-    "CHANGELOG.md"
+    "AUTHORS",
+    "CHANGELOG.md",
+    "THIRD-PARTY-NOTICES"
   ],
   "sideEffects": false,
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
-    "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc --noEmit",
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node --disable-warning=ExperimentalWarning scripts/build-validators.ts",
+    "typecheck": "npm run build && tsc --noEmit",
     "lint": "biome check .",
     "format": "biome check --write .",
     "test": "npm run build && node --disable-warning=ExperimentalWarning --test 'test/**/*.test.ts'",
     "check": "npm run lint && npm run typecheck && npm test",
     "sync": "node --disable-warning=ExperimentalWarning scripts/sync-schemas.ts",
     "generate": "node --disable-warning=ExperimentalWarning scripts/generate.ts",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "corpus": "node --disable-warning=ExperimentalWarning scripts/corpus.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
     "@types/node": "^22.20.5",
+    "ajv": "8.20.0",
+    "esbuild": "0.28.2",
     "typescript": "^7.0.2"
   }
 }