open-classify 0.2.0 → 0.5.0

package/dist/src/stock-validation.js

@@ -1,251 +1,226 @@
-import { DOWNSTREAM_MODEL_TIER_VALUES, MODEL_SPECIALIZATION_VALUES, } from "./enums.js";
+// Manifest and classifier-output validation.
+//
+// The runtime composes every classifier's effective output schema by merging:
+//
+//   - required `reason` / `certainty` metadata
+//   - canonical sub-schemas for each declared reserved field (optional)
+//   - the manifest's own `output_schema.properties` for custom fields
+//
+// That composed schema is what runs against actual classifier outputs, so the
+// LLM cannot emit an invalid enum value for a reserved field even if the
+// manifest author forgot to constrain it themselves.
 import { Ajv } from "ajv/dist/ajv.js";
-import { CERTAINTY_VALUES, STOCK_CLASSIFIER_NAMES } from "./stock.js";
-import { ensureNoDuplicates, isRecord, requireEnum, requireNonEmptyStringMaxLength, requireNonNegativeSafeInteger, requireString, requireStringArray, throwInvalid, } from "./validation.js";
-export const STOCK_REASON_MAX_CHARS = 120;
-export const STOCK_REPLY_MAX_CHARS = 200;
-export const STOCK_TOOL_ID_MAX_CHARS = 64;
-export const STOCK_TOOL_DESCRIPTION_MAX_CHARS = 240;
-export const STOCK_MANIFEST_NAME_MAX_CHARS = 80;
-export const STOCK_MANIFEST_VERSION_MAX_CHARS = 40;
-export const STOCK_MANIFEST_PURPOSE_MAX_CHARS = 400;
-const STOCK_PROMPT_INJECTION_RISK_LEVEL_VALUES = [
-    "normal",
-    "suspicious",
-    "high_risk",
-    "unknown",
-];
-const MANIFEST_KIND_VALUES = ["stock", "custom"];
-const ajv = new Ajv({ allErrors: true, strict: false });
-const COMMON_MANIFEST_KEYS = [
-    "kind",
+import { APPLIES_TO_VALUES, CERTAINTY_VALUES } from "./stock.js";
+import { RESERVED_FIELD_EXCLUSIONS, RESERVED_FIELD_NAMES, RESERVED_FIELDS, isReservedFieldName, normalizeToolId, } from "./reserved-fields.js";
+import { isRecord, requireNonEmptyStringMaxLength, requireNonNegativeSafeInteger, requireString, throwInvalid, } from "./validation.js";
+export const REASON_MAX_CHARS = 120;
+export const TOOL_ID_MAX_CHARS = 64;
+export const TOOL_DESCRIPTION_MAX_CHARS = 240;
+export const MANIFEST_NAME_MAX_CHARS = 80;
+export const MANIFEST_VERSION_MAX_CHARS = 40;
+export const MANIFEST_PURPOSE_MAX_CHARS = 400;
+const MANIFEST_KEYS = [
     "name",
     "version",
     "purpose",
-    "order",
+    "dispatch_order",
+    "applies_to",
+    "reserved_fields",
+    "allowed_tools",
+    "output_schema",
     "fallback",
     "backend",
 ];
-const STOCK_MANIFEST_KEYS = [
-    ...COMMON_MANIFEST_KEYS,
-    "tools",
-];
-const CUSTOM_MANIFEST_KEYS = [
-    ...COMMON_MANIFEST_KEYS,
-    "output_schema",
-];
+const ajv = new Ajv({ allErrors: true, strict: false });
 export function validateJsonClassifierManifest(value, model = "manifest") {
     if (!isRecord(value)) {
         throwInvalid("manifest", model, "manifest must be a JSON object");
     }
-    const kind = requireEnum(value.kind, MANIFEST_KIND_VALUES, "manifest", model, "kind");
-    return kind === "stock"
-        ? validateStockManifest(value, model)
-        : validateCustomManifest(value, model);
-}
-function validateStockManifest(value, model) {
-    ensureAllowedObjectKeys(value, STOCK_MANIFEST_KEYS, "manifest", model, "manifest");
-    const name = requireEnum(value.name, STOCK_CLASSIFIER_NAMES, "manifest", model, "name");
-    const base = validateManifestCommon(value, model);
-    const tools = value.tools === undefined
+    ensureAllowedObjectKeys(value, MANIFEST_KEYS, "manifest", model, "manifest");
+    const name = requireNonEmptyStringMaxLength(value.name, "manifest", model, "name", MANIFEST_NAME_MAX_CHARS);
+    const version = requireNonEmptyStringMaxLength(value.version, "manifest", model, "version", MANIFEST_VERSION_MAX_CHARS);
+    const purpose = requireNonEmptyStringMaxLength(value.purpose, "manifest", model, "purpose", MANIFEST_PURPOSE_MAX_CHARS);
+    const dispatchOrder = value.dispatch_order === undefined
         ? undefined
-        : validateTools(value.tools, model);
-    if (name !== "tools" && tools !== undefined) {
-        throwInvalid("manifest", model, "tools is only supported on the tools classifier");
-    }
-    const fallback = validateStockOutputForName(name, value.fallback, model, tools);
-    return {
-        kind: "stock",
-        name,
-        ...base,
-        fallback,
-        ...(tools === undefined ? {} : { tools }),
-    };
-}
-function validateCustomManifest(value, model) {
-    ensureAllowedObjectKeys(value, CUSTOM_MANIFEST_KEYS, "manifest", model, "manifest");
-    const name = requireNonEmptyStringMaxLength(value.name, "manifest", model, "name", STOCK_MANIFEST_NAME_MAX_CHARS);
-    if (STOCK_CLASSIFIER_NAMES.includes(name)) {
-        throwInvalid("manifest", model, `custom classifier name "${name}" collides with a stock classifier`);
+        : requireNonNegativeSafeInteger(value.dispatch_order, "manifest", model, "dispatch_order");
+    const appliesTo = validateAppliesTo(value.applies_to, model);
+    const reservedFields = validateReservedFields(value.reserved_fields, model);
+    const allowedTools = value.allowed_tools === undefined
+        ? undefined
+        : validateAllowedTools(value.allowed_tools, model);
+    if (allowedTools !== undefined && !reservedFields.includes("tools")) {
+        throwInvalid("manifest", model, "allowed_tools is only supported when reserved_fields includes \"tools\"");
     }
-    const base = validateManifestCommon(value, model);
-    if (value.output_schema === undefined) {
-        throwInvalid("manifest", model, "output_schema is required for custom classifiers");
+    if (reservedFields.includes("tools") && allowedTools === undefined) {
+        throwInvalid("manifest", model, "allowed_tools is required when reserved_fields includes \"tools\"");
     }
-    const outputSchema = value.output_schema;
-    compileOutputSchema(outputSchema, "manifest", model);
-    const fallback = validateCustomOutput(value.fallback, name, model, outputSchema);
-    return {
-        kind: "custom",
+    const outputSchema = validateOutputSchemaShape(value.output_schema, reservedFields, model);
+    const composedOutputSchema = composeOutputSchema(reservedFields, allowedTools, outputSchema);
+    compileSchema(composedOutputSchema, "manifest", model, "composed output_schema");
+    validateExamples(outputSchema, composedOutputSchema, model);
+    const fallback = validateFallback(value.fallback, composedOutputSchema, name, model);
+    const backend = value.backend === undefined ? undefined : validateBackend(value.backend, model);
+    const manifest = {
         name,
-        ...base,
+        version,
+        purpose,
+        ...(dispatchOrder === undefined ? {} : { dispatch_order: dispatchOrder }),
+        ...(value.applies_to === undefined ? {} : { applies_to: appliesTo }),
+        ...(reservedFields.length === 0 ? {} : { reserved_fields: reservedFields }),
+        ...(allowedTools === undefined ? {} : { allowed_tools: allowedTools }),
+        ...(outputSchema === undefined ? {} : { output_schema: outputSchema }),
         fallback,
-        output_schema: outputSchema,
+        ...(backend === undefined ? {} : { backend }),
     };
-}
-function validateManifestCommon(value, model) {
-    const version = requireNonEmptyStringMaxLength(value.version, "manifest", model, "version", STOCK_MANIFEST_VERSION_MAX_CHARS);
-    const purpose = requireNonEmptyStringMaxLength(value.purpose, "manifest", model, "purpose", STOCK_MANIFEST_PURPOSE_MAX_CHARS);
-    const order = requireNonNegativeSafeInteger(value.order, "manifest", model, "order");
     return {
-        version,
-        purpose,
-        order,
-        ...(value.backend === undefined ? {} : { backend: validateBackend(value.backend, model) }),
+        manifest,
+        reservedFields,
+        composedOutputSchema,
+        appliesTo,
     };
 }
-export function validateOutputForManifest(manifest, value, context) {
-    if (manifest.kind === "stock") {
-        return validateStockOutputForName(manifest.name, value, context.model, manifest.tools);
+function validateAppliesTo(raw, model) {
+    if (raw === undefined)
+        return "user";
+    if (typeof raw !== "string" || !APPLIES_TO_VALUES.includes(raw)) {
+        throwInvalid("manifest", model, `applies_to must be one of ${APPLIES_TO_VALUES.join(", ")}`);
     }
-    return validateCustomOutput(value, context.classifier, context.model, manifest.output_schema);
+    return raw;
 }
-function validateStockOutputForName(name, value, model, tools) {
-    if (!isRecord(value)) {
-        throwInvalid(name, model, "output must be a JSON object");
+function validateReservedFields(raw, model) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throwInvalid("manifest", model, "reserved_fields must be an array of strings");
     }
-    switch (name) {
-        case "preflight":
-            return validatePreflightOutput(value, model);
-        case "routing":
-            return validateTierRoutingOutput(value, model);
-        case "model_specialization":
-            return validateModelSpecializationOutput(value, model);
-        case "tools":
-            return validateToolsOutput(value, model, tools?.map((tool) => tool.id));
-        case "prompt_injection":
-            return validatePromptInjectionOutput(value, model);
-        default: {
-            const _exhaustive = name;
-            void _exhaustive;
-            throwInvalid("manifest", model, `unknown stock classifier name`);
+    const seen = new Set();
+    const result = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (typeof item !== "string") {
+            throwInvalid("manifest", model, `reserved_fields[${i}] must be a string`);
         }
+        if (!isReservedFieldName(item)) {
+            throwInvalid("manifest", model, `reserved_fields[${i}] "${item}" is not a known reserved field. Allowed: ${RESERVED_FIELD_NAMES.join(", ")}`);
+        }
+        if (seen.has(item)) {
+            throwInvalid("manifest", model, `reserved_fields[${i}] duplicates "${item}"`);
+        }
+        seen.add(item);
+        result.push(item);
     }
+    return result;
 }
-function validateMetadata(value, classifier, model) {
-    if (value.reason === undefined) {
-        throwInvalid(classifier, model, "reason is required");
-    }
-    if (value.certainty === undefined) {
-        throwInvalid(classifier, model, "certainty is required");
+function validateAllowedTools(value, model) {
+    if (!Array.isArray(value)) {
+        throwInvalid("manifest", model, "allowed_tools must be an array");
     }
-    return {
-        reason: truncateText(requireString(value.reason, classifier, model, "reason"), STOCK_REASON_MAX_CHARS),
-        certainty: requireEnum(value.certainty, CERTAINTY_VALUES, classifier, model, "certainty"),
-    };
-}
-function validatePreflightOutput(value, model) {
-    ensureAllowedObjectKeys(value, ["reason", "certainty", "final_reply", "ack_reply"], "preflight", model, "output");
-    if (value.final_reply !== undefined && value.ack_reply !== undefined) {
-        throwInvalid("preflight", model, "final_reply and ack_reply are mutually exclusive");
+    const ids = new Set();
+    const out = [];
+    for (let i = 0; i < value.length; i++) {
+        const item = value[i];
+        if (!isRecord(item)) {
+            throwInvalid("manifest", model, `allowed_tools[${i}] must be an object`);
+        }
+        ensureAllowedObjectKeys(item, ["id", "description"], "manifest", model, `allowed_tools[${i}]`);
+        const id = requireNonEmptyStringMaxLength(item.id, "manifest", model, `allowed_tools[${i}].id`, TOOL_ID_MAX_CHARS);
+        const description = requireNonEmptyStringMaxLength(item.description, "manifest", model, `allowed_tools[${i}].description`, TOOL_DESCRIPTION_MAX_CHARS);
+        if (ids.has(id)) {
+            throwInvalid("manifest", model, `allowed_tools[${i}].id "${id}" is duplicated`);
+        }
+        ids.add(id);
+        out.push({ id, description });
     }
-    const meta = validateMetadata(value, "preflight", model);
-    return {
-        ...meta,
-        ...(value.final_reply === undefined
-            ? {}
-            : { final_reply: validateReplySignal(value.final_reply, "preflight", model, "final_reply") }),
-        ...(value.ack_reply === undefined
-            ? {}
-            : { ack_reply: validateReplySignal(value.ack_reply, "preflight", model, "ack_reply") }),
-    };
+    return out;
 }
-function validateReplySignal(value, classifier, model, field) {
-    if (!isRecord(value)) {
-        throwInvalid(classifier, model, `${field} must be an object`);
+function validateOutputSchemaShape(raw, reservedFields, model) {
+    if (raw === undefined)
+        return undefined;
+    if (!isRecord(raw)) {
+        throwInvalid("manifest", model, "output_schema must be a JSON object");
     }
-    ensureAllowedObjectKeys(value, ["reply"], classifier, model, field);
-    const reply = requireString(value.reply, classifier, model, `${field}.reply`);
-    if (reply.trim().length === 0) {
-        throwInvalid(classifier, model, `${field}.reply must not be empty`);
+    // We don't fully validate JSON Schema shape — Ajv does that when we compile
+    // the composed schema. But we do enforce the no-reserved-keys rule, since
+    // mixing reserved fields into properties is always a manifest error.
+    const properties = raw.properties;
+    if (properties !== undefined) {
+        if (!isRecord(properties)) {
+            throwInvalid("manifest", model, "output_schema.properties must be a JSON object");
+        }
+        for (const key of Object.keys(properties)) {
+            if (isReservedFieldName(key)) {
+                throwInvalid("manifest", model, `output_schema.properties.${key} collides with a reserved field. Declare it in reserved_fields instead.`);
+            }
+            if (key === "reason" || key === "certainty") {
+                throwInvalid("manifest", model, `output_schema.properties.${key} is reserved. Do not declare it.`);
+            }
+        }
     }
-    if (reply.length > STOCK_REPLY_MAX_CHARS) {
-        throwInvalid(classifier, model, `${field}.reply must be ${STOCK_REPLY_MAX_CHARS} characters or fewer`);
+    // Examples must be an array if present. Per-example validation happens
+    // after the composed schema is built so we can validate against it.
+    if (raw.examples !== undefined && !Array.isArray(raw.examples)) {
+        throwInvalid("manifest", model, "output_schema.examples must be an array");
     }
-    return { reply };
+    void reservedFields;
+    return raw;
 }
-function validateTierRoutingOutput(value, model) {
-    ensureAllowedObjectKeys(value, ["reason", "certainty", "model_tier"], "routing", model, "output");
-    const meta = validateMetadata(value, "routing", model);
-    const modelTier = normalizeOptionalEnumValue(value.model_tier);
-    return {
-        ...meta,
-        ...(modelTier === undefined
-            ? {}
-            : { model_tier: requireEnum(modelTier, DOWNSTREAM_MODEL_TIER_VALUES, "routing", model, "model_tier") }),
-    };
-}
-function validateModelSpecializationOutput(value, model) {
-    ensureAllowedObjectKeys(value, ["reason", "certainty", "specialization"], "model_specialization", model, "output");
-    const meta = validateMetadata(value, "model_specialization", model);
-    const specialization = normalizeOptionalEnumValue(value.specialization);
-    return {
-        ...meta,
-        ...(specialization === undefined
-            ? {}
-            : { specialization: requireEnum(specialization, MODEL_SPECIALIZATION_VALUES, "model_specialization", model, "specialization") }),
+function composeOutputSchema(reservedFields, allowedTools, outputSchema) {
+    const context = { allowed_tools: allowedTools };
+    const properties = {
+        reason: { type: "string", minLength: 1, maxLength: REASON_MAX_CHARS },
+        certainty: { type: "string", enum: [...CERTAINTY_VALUES] },
     };
-}
-function normalizeOptionalEnumValue(value) {
-    if (value === undefined || value === null) {
-        return undefined;
-    }
-    if (typeof value === "string" && value.trim().length === 0) {
-        return undefined;
+    for (const field of reservedFields) {
+        properties[field] = RESERVED_FIELDS[field].subSchema(context);
     }
-    return value;
-}
-function validateToolsOutput(value, model, configuredTools) {
-    ensureAllowedObjectKeys(value, ["reason", "certainty", "tools"], "tools", model, "output");
-    const meta = validateMetadata(value, "tools", model);
-    const tools = requireStringArray(value.tools, "tools", model, "tools").map(normalizeTool);
-    ensureNoDuplicates(tools, "tools", model, "tools");
-    if (configuredTools) {
-        const allowed = new Set(configuredTools);
-        for (const tool of tools) {
-            if (!allowed.has(tool)) {
-                throwInvalid("tools", model, `tools includes unsupported tool ${tool}`);
-            }
-        }
+    const customProperties = isRecord(outputSchema?.properties)
+        ? outputSchema.properties
+        : {};
+    for (const [key, schema] of Object.entries(customProperties)) {
+        properties[key] = schema;
     }
-    return { ...meta, tools };
-}
-function validatePromptInjectionOutput(value, model) {
-    ensureAllowedObjectKeys(value, ["reason", "certainty", "risk_level"], "prompt_injection", model, "output");
-    const meta = validateMetadata(value, "prompt_injection", model);
-    const riskLevel = requireEnum(value.risk_level, STOCK_PROMPT_INJECTION_RISK_LEVEL_VALUES, "prompt_injection", model, "risk_level");
+    const customRequired = Array.isArray(outputSchema?.required)
+        ? outputSchema.required.filter((key) => typeof key === "string")
+        : [];
+    const required = Array.from(new Set(["reason", "certainty", ...customRequired]));
     return {
-        ...meta,
-        risk_level: riskLevel,
+        type: "object",
+        additionalProperties: false,
+        required,
+        properties,
     };
 }
-function validateCustomOutput(value, classifier, model, schema) {
-    if (!isRecord(value)) {
-        throwInvalid(classifier, model, "output must be a JSON object");
-    }
-    ensureAllowedObjectKeys(value, ["reason", "certainty", "output"], classifier, model, "output");
-    if (value.output === undefined) {
-        throwInvalid(classifier, model, "output is required for custom classifiers");
+function validateExamples(outputSchema, composedSchema, model) {
+    if (outputSchema === undefined)
+        return;
+    const examples = outputSchema.examples;
+    if (!Array.isArray(examples))
+        return;
+    const validate = ajv.compile(composedSchema);
+    for (let i = 0; i < examples.length; i++) {
+        const example = examples[i];
+        if (!validate(example)) {
+            const message = formatSchemaErrors(validate.errors, `examples[${i}]`);
+            throwInvalid("manifest", model, `output_schema.examples[${i}] is invalid: ${message}`);
+        }
+        if (isRecord(example)) {
+            enforceMutualExclusions(example, "manifest", model, `output_schema.examples[${i}]`);
+        }
     }
-    const meta = validateMetadata(value, classifier, model);
-    validateWithSchema(value.output, schema, classifier, model, "output");
-    return { ...meta, output: value.output };
 }
-function validateTools(value, model) {
-    if (!Array.isArray(value)) {
-        throwInvalid("manifest", model, "tools must be an array");
+function validateFallback(raw, composedSchema, classifier, model) {
+    if (!isRecord(raw)) {
+        throwInvalid(classifier, model, "fallback must be a JSON object");
     }
-    const out = value.map((item, index) => {
-        if (!isRecord(item)) {
-            throwInvalid("manifest", model, `tools[${index}] must be an object`);
-        }
-        return {
-            id: requireNonEmptyStringMaxLength(item.id, "manifest", model, `tools[${index}].id`, STOCK_TOOL_ID_MAX_CHARS),
-            description: requireNonEmptyStringMaxLength(item.description, "manifest", model, `tools[${index}].description`, STOCK_TOOL_DESCRIPTION_MAX_CHARS),
-        };
-    });
-    ensureNoDuplicates(out.map((item) => item.id), "manifest", model, "tools[].id");
-    return out;
+    // Fallback represents the "I have no signal" state, so reserved fields are
+    // optional. The composed schema already marks them optional except for
+    // reason/certainty.
+    const validate = ajv.compile(composedSchema);
+    if (!validate(raw)) {
+        const message = formatSchemaErrors(validate.errors, "fallback");
+        throwInvalid(classifier, model, `fallback is invalid: ${message}`);
+    }
+    return raw;
 }
 function validateBackend(value, model) {
     if (!isRecord(value))
@@ -265,6 +240,56 @@ function validateBackend(value, model) {
         },
     };
 }
+export function validateOutputForManifest(manifest, value, context) {
+    if (!isRecord(value)) {
+        throwInvalid(context.classifier, context.model, "output must be a JSON object");
+    }
+    const normalized = normalizeOutput(value, manifest);
+    const validate = ajv.compile(manifest.composedOutputSchema);
+    if (!validate(normalized)) {
+        const message = formatSchemaErrors(validate.errors, "output");
+        throwInvalid(context.classifier, context.model, message);
+    }
+    enforceMutualExclusions(normalized, context.classifier, context.model, "output");
+    return truncateReason(normalized);
+}
+// Apply small, well-known cleanups that consistently improve LLM compliance:
+//   - blank / null routing-style enums → omitted entirely
+//   - tools aliases (browser → web, etc.)
+function normalizeOutput(value, manifest) {
+    const out = { ...value };
+    for (const field of manifest.reservedFields) {
+        if (field === "model_tier" || field === "model_specialization") {
+            const raw = out[field];
+            if (raw === null || (typeof raw === "string" && raw.trim().length === 0)) {
+                delete out[field];
+            }
+        }
+        if (field === "tools") {
+            const raw = out[field];
+            if (Array.isArray(raw)) {
+                out[field] = raw.map((item) => typeof item === "string" ? normalizeToolId(item) : item);
+            }
+        }
+    }
+    return out;
+}
+function truncateReason(value) {
+    if (typeof value.reason !== "string")
+        return value;
+    if (value.reason.length <= REASON_MAX_CHARS)
+        return value;
+    return { ...value, reason: value.reason.slice(0, REASON_MAX_CHARS).trimEnd() };
+}
+function enforceMutualExclusions(output, classifier, model, path) {
+    for (const group of RESERVED_FIELD_EXCLUSIONS) {
+        const present = group.filter((field) => output[field] !== undefined);
+        if (present.length > 1) {
+            throwInvalid(classifier, model, `${path}: reserved fields are mutually exclusive: ${present.join(", ")}`);
+        }
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
 function ensureAllowedObjectKeys(value, allowedKeys, classifier, model, path) {
     const allowed = new Set(allowedKeys);
     for (const key of Object.keys(value)) {
@@ -273,40 +298,42 @@ function ensureAllowedObjectKeys(value, allowedKeys, classifier, model, path) {
         }
     }
 }
-function compileOutputSchema(schema, classifier, model) {
+function compileSchema(schema, classifier, model, label) {
     try {
         ajv.compile(schema);
     }
     catch (error) {
-        throwInvalid(classifier, model, `output_schema is invalid JSON Schema: ${errorMessage(error)}`);
-    }
-}
-export function validateWithSchema(value, schema, classifier, model, path) {
-    const validate = ajv.compile(schema);
-    if (!validate(value)) {
-        const message = ajv.errorsText(validate.errors, { dataVar: path });
-        throwInvalid(classifier, model, message);
+        throwInvalid(classifier, model, `${label} is invalid JSON Schema: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-function normalizeTool(tool) {
-    const aliases = {
-        browser: "web",
-        browsing: "web",
-        internet: "web",
-        web_browsing: "web",
-        web_search: "web",
-    };
-    return aliases[tool] ?? tool;
-}
-function truncateText(text, maxChars) {
-    return text.length <= maxChars ? text : text.slice(0, maxChars).trimEnd();
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-export function validateClassifierOutputWithManifest(value, options) {
-    return validateOutputForManifest(options.manifest, value, {
-        classifier: options.classifier,
-        model: options.model,
-    });
+// Format Ajv errors with the offending property name surfaced inline. Ajv's
+// default errorsText says "must NOT have additional properties" without
+// naming the property, which is unhelpful to debug.
+function formatSchemaErrors(errors, dataVar) {
+    if (!errors || errors.length === 0)
+        return `${dataVar} is invalid`;
+    return errors
+        .map((err) => {
+        const path = `${dataVar}${err.instancePath ?? ""}`;
+        if (err.keyword === "additionalProperties") {
+            const extra = err.params?.additionalProperty;
+            if (extra) {
+                return `${path}.${extra} is not a supported field`;
+            }
+        }
+        if (err.keyword === "required") {
+            const missing = err.params?.missingProperty;
+            if (missing) {
+                return `${path}.${missing} is required`;
+            }
+        }
+        if (err.keyword === "enum") {
+            const allowed = err.params?.allowedValues;
+            if (allowed) {
+                return `${path} has an unsupported value (allowed: ${allowed.join(", ")})`;
+            }
+        }
+        return `${path} ${err.message ?? "is invalid"}`;
+    })
+        .join("; ");
 }