@crewhaus/tool-schema 0.7.0

package/dist/lib/formats.js

@@ -0,0 +1,395 @@
+/**
+ * String format checks, written out rather than borrowed.
+ *
+ * Every one of these is a *stated subset*, not a full grammar. The rule this
+ * file follows: reject what is definitely wrong, accept what is definitely
+ * right, and say in the doc comment which grey areas fall which way — so a
+ * harness gating on `ValidateFormat` knows exactly what it bought. A format
+ * check that quietly disagrees with the reader downstream is worse than no
+ * check at all.
+ */
+/** Every format name {@link checkFormat} understands. */
+export const FORMAT_NAMES = [
+    "email",
+    "uri",
+    "uri-reference",
+    "hostname",
+    "ipv4",
+    "ipv6",
+    "uuid",
+    "date",
+    "time",
+    "date-time",
+    "json-pointer",
+    "regex",
+];
+const OK = { valid: true, reason: null };
+const bad = (reason) => ({ valid: false, reason });
+/** True when `name` is one this module implements. */
+export function isFormatName(name) {
+    return FORMAT_NAMES.includes(name);
+}
+/**
+ * A DNS hostname: dot-separated labels, each 1-63 characters of letters,
+ * digits and hyphens, not starting or ending with a hyphen; 253 characters
+ * total at most.
+ *
+ * Deliberate choices: a trailing dot (the DNS root) is rejected, underscores
+ * are rejected (legal in some DNS records, not in a hostname), and no
+ * internationalized form is decoded — a Unicode domain must arrive already
+ * punycoded.
+ */
+export function isHostname(value) {
+    if (value === "")
+        return bad("empty hostname");
+    if (value.length > 253)
+        return bad(`${value.length} characters, over the 253 limit`);
+    for (const label of value.split(".")) {
+        if (label === "")
+            return bad("empty label (a leading, doubled or trailing dot)");
+        if (label.length > 63)
+            return bad(`label "${label}" is over 63 characters`);
+        if (!/^[A-Za-z0-9-]+$/.test(label)) {
+            return bad(`label "${label}" has a character outside A-Z a-z 0-9 -`);
+        }
+        if (label.startsWith("-") || label.endsWith("-")) {
+            return bad(`label "${label}" starts or ends with a hyphen`);
+        }
+    }
+    return OK;
+}
+/**
+ * Dotted-quad IPv4. Four decimal octets 0-255, no leading zeros — `01.2.3.4`
+ * is rejected, because a leading zero means octal to some parsers and
+ * decimal to others, and that ambiguity has been a source of SSRF bugs.
+ */
+export function isIpv4(value) {
+    const parts = value.split(".");
+    if (parts.length !== 4)
+        return bad(`expected 4 dot-separated octets, found ${parts.length}`);
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return bad(`octet "${part}" is not 1-3 digits`);
+        if (part.length > 1 && part.startsWith("0"))
+            return bad(`octet "${part}" has a leading zero`);
+        if (Number(part) > 255)
+            return bad(`octet "${part}" is over 255`);
+    }
+    return OK;
+}
+/**
+ * IPv6, including `::` compression and a dotted-quad IPv4 tail
+ * (`::ffff:192.0.2.1`). A zone identifier (`fe80::1%eth0`) is rejected: it
+ * addresses an interface, not a host, and is not part of the `ipv6` format.
+ */
+export function isIpv6(value) {
+    if (value === "")
+        return bad("empty address");
+    if (value.includes("%"))
+        return bad("zone identifiers are not part of the ipv6 format");
+    const doubleColons = value.split("::").length - 1;
+    if (doubleColons > 1)
+        return bad('"::" may appear at most once');
+    /**
+     * Count the groups in one run of colon-separated text. An empty run is
+     * zero groups, which is what each side of a leading or trailing `::` is;
+     * an empty *group* is a stray colon and is rejected, which is what keeps
+     * `:::`, `1:::2` and a trailing `1:2:...:8:` out. A dotted quad is only
+     * accepted as the final group of the run, and stands for two groups.
+     */
+    const countGroups = (text, allowQuad) => {
+        if (text === "")
+            return { groups: 0 };
+        const parts = text.split(":");
+        let groups = 0;
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (allowQuad && i === parts.length - 1 && part.includes(".")) {
+                const v4 = isIpv4(part);
+                if (!v4.valid)
+                    return { error: `embedded IPv4 "${part}": ${v4.reason}` };
+                groups += 2;
+                continue;
+            }
+            if (!/^[0-9A-Fa-f]{1,4}$/.test(part)) {
+                return { error: `group "${part}" is not 1-4 hex digits` };
+            }
+            groups += 1;
+        }
+        return { groups };
+    };
+    if (doubleColons === 1) {
+        // The quad may only appear after the compression, so the left side never
+        // carries one; a dot there is a malformed group and is rejected as such.
+        const [rawLeft = "", rawRight = ""] = value.split("::");
+        const left = countGroups(rawLeft, false);
+        if ("error" in left)
+            return bad(left.error);
+        const right = countGroups(rawRight, true);
+        if ("error" in right)
+            return bad(right.error);
+        const total = left.groups + right.groups;
+        if (total > 7) {
+            return bad(`"::" must stand for at least one group, but ${total} are written out`);
+        }
+        return OK;
+    }
+    const written = countGroups(value, true);
+    if ("error" in written)
+        return bad(written.error);
+    if (written.groups !== 8)
+        return bad(`expected 8 groups, found ${written.groups}`);
+    return OK;
+}
+/**
+ * A UUID in the 8-4-4-4-12 hex form, any case.
+ *
+ * Any version and variant is accepted, including the nil UUID — this checks
+ * the shape, not that the value came from a v4 generator. Braces and a
+ * `urn:uuid:` prefix are rejected.
+ */
+export function isUuid(value) {
+    if (!/^[0-9A-Fa-f]{8}(-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}$/.test(value)) {
+        return bad("expected 8-4-4-4-12 hexadecimal digits");
+    }
+    return OK;
+}
+/** Days in a month, honouring the Gregorian leap-year rule. */
+export function daysInMonth(year, month) {
+    if (month === 2) {
+        const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+        return leap ? 29 : 28;
+    }
+    return [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0;
+}
+/**
+ * RFC 3339 `full-date`: `YYYY-MM-DD`, calendar-checked, so `2023-02-30` and
+ * `2023-13-01` are rejected and `2024-02-29` is accepted. No other layout is
+ * accepted; `2023-1-1` fails.
+ */
+export function isDate(value) {
+    const match = value.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (match === null)
+        return bad("expected YYYY-MM-DD");
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    if (month < 1 || month > 12)
+        return bad(`month ${month} is not 1-12`);
+    const max = daysInMonth(year, month);
+    if (day < 1 || day > max)
+        return bad(`day ${day} is outside 1-${max} for that month`);
+    return OK;
+}
+/**
+ * RFC 3339 `full-time`: `HH:MM:SS`, an optional fractional part, and a
+ * mandatory offset of `Z`, `z`, or `+HH:MM` / `-HH:MM`.
+ *
+ * A seconds value of 60 is accepted, because RFC 3339 allows it for leap
+ * seconds. An offset with minutes over 59 is rejected.
+ */
+export function isTime(value) {
+    const match = value.match(/^(\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/);
+    if (match === null)
+        return bad("expected HH:MM:SS with an offset of Z or +HH:MM");
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    const second = Number(match[3]);
+    if (hour > 23)
+        return bad(`hour ${hour} is over 23`);
+    if (minute > 59)
+        return bad(`minute ${minute} is over 59`);
+    if (second > 60)
+        return bad(`second ${second} is over 60`);
+    const offset = match[5] ?? "";
+    if (offset !== "Z" && offset !== "z") {
+        const offsetHour = Number(offset.slice(1, 3));
+        const offsetMinute = Number(offset.slice(4, 6));
+        if (offsetHour > 23)
+            return bad(`offset hour ${offsetHour} is over 23`);
+        if (offsetMinute > 59)
+            return bad(`offset minute ${offsetMinute} is over 59`);
+    }
+    return OK;
+}
+/**
+ * RFC 3339 `date-time`: a date, a `T` (or lowercase `t`) separator, and a
+ * time with an offset. A space separator, as SQL writes it, is rejected —
+ * this is the strict interchange form.
+ */
+export function isDateTime(value) {
+    const split = value.match(/^(.+?)[Tt](.+)$/);
+    if (split === null)
+        return bad('expected a "T" between the date and the time');
+    const date = isDate(split[1] ?? "");
+    if (!date.valid)
+        return bad(`date part: ${date.reason}`);
+    const time = isTime(split[2] ?? "");
+    if (!time.valid)
+        return bad(`time part: ${time.reason}`);
+    return OK;
+}
+/**
+ * An email address, in the form services actually accept: a dot-separated
+ * local part of unquoted ASCII characters and a hostname domain.
+ *
+ * Deliberately narrower than RFC 5322: quoted local parts, comments,
+ * IP-literal domains (`a@[192.0.2.1]`) and non-ASCII are all rejected. A
+ * domain with no dot (`a@localhost`) is rejected too, since a bare host is
+ * never a deliverable address in practice.
+ */
+export function isEmail(value) {
+    const at = value.lastIndexOf("@");
+    if (at < 0)
+        return bad('no "@"');
+    const local = value.slice(0, at);
+    const domain = value.slice(at + 1);
+    if (local === "")
+        return bad("empty local part");
+    if (local.length > 64)
+        return bad(`local part is ${local.length} characters, over the 64 limit`);
+    if (!/^[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+$/.test(local)) {
+        return bad("local part has a character outside the unquoted set");
+    }
+    if (local.startsWith(".") || local.endsWith(".")) {
+        return bad("local part starts or ends with a dot");
+    }
+    if (local.includes(".."))
+        return bad("local part has two consecutive dots");
+    const host = isHostname(domain);
+    if (!host.valid)
+        return bad(`domain: ${host.reason}`);
+    if (!domain.includes("."))
+        return bad("domain has no dot");
+    return OK;
+}
+/**
+ * True when the string holds a character no URI may contain: any whitespace,
+ * any C0 control character, or DEL. The codes are compared numerically rather
+ * than through a character class so no control character appears in source.
+ */
+function hasIllegalUriChar(value) {
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code <= 0x20 || code === 0x7f || /\s/.test(char))
+            return true;
+    }
+    return false;
+}
+/**
+ * An absolute URI: a scheme (`[A-Za-z][A-Za-z0-9+.-]*`), a colon, and a
+ * non-empty remainder with no whitespace or control characters.
+ *
+ * This is the absolute-URI shape check, not the full RFC 3986 grammar: the
+ * authority, path, query and fragment are not parsed. `/path` and
+ * `page.html` are rejected — use `uri-reference` for those.
+ */
+export function isUri(value) {
+    if (hasIllegalUriChar(value))
+        return bad("contains whitespace or a control character");
+    if (!/^[A-Za-z][A-Za-z0-9+.-]*:.+$/.test(value)) {
+        return bad("no scheme — an absolute URI needs one, e.g. https:");
+    }
+    return OK;
+}
+/**
+ * A URI reference: either an absolute URI or a relative one. Only whitespace,
+ * control characters and a second `#` are rejected; anything else a browser
+ * would resolve is accepted.
+ */
+export function isUriReference(value) {
+    if (hasIllegalUriChar(value))
+        return bad("contains whitespace or a control character");
+    if (value.split("#").length > 2)
+        return bad('more than one "#"');
+    return OK;
+}
+/** RFC 6901 JSON Pointer: empty, or `/`-led tokens where `~` is followed by 0 or 1. */
+export function isJsonPointer(value) {
+    if (value === "")
+        return OK;
+    if (!value.startsWith("/"))
+        return bad('a non-empty pointer must start with "/"');
+    if (/~(?![01])/.test(value))
+        return bad('"~" must be followed by 0 or 1');
+    return OK;
+}
+/** A string that compiles as a JavaScript regular expression. */
+export function isRegex(value) {
+    try {
+        new RegExp(value);
+        return OK;
+    }
+    catch (err) {
+        return bad(err.message);
+    }
+}
+/**
+ * Check one string against one format name. An unknown format name is a
+ * caller error and throws; every implemented format returns a result.
+ */
+export function checkFormat(value, format) {
+    switch (format) {
+        case "email":
+            return isEmail(value);
+        case "uri":
+            return isUri(value);
+        case "uri-reference":
+            return isUriReference(value);
+        case "hostname":
+            return isHostname(value);
+        case "ipv4":
+            return isIpv4(value);
+        case "ipv6":
+            return isIpv6(value);
+        case "uuid":
+            return isUuid(value);
+        case "date":
+            return isDate(value);
+        case "time":
+            return isTime(value);
+        case "date-time":
+            return isDateTime(value);
+        case "json-pointer":
+            return isJsonPointer(value);
+        case "regex":
+            return isRegex(value);
+        default:
+            throw new Error(`unknown format "${String(format)}"`);
+    }
+}
+/**
+ * The formats, narrowest first.
+ *
+ * These grammars overlap, and the overlap is not symmetric: every dotted
+ * quad, every UUID and every `YYYY-MM-DD` date is also a syntactically valid
+ * hostname, since a hostname label is just letters, digits and hyphens. A
+ * caller asking "what does this value look like" wants `uuid` before
+ * `hostname`, so the answer is ordered by how much each format rules out
+ * rather than by declaration order.
+ *
+ * `regex` and `uri-reference` are absent because they match nearly every
+ * string; reporting them would be noise rather than a finding.
+ */
+const FORMAT_SPECIFICITY = [
+    "uuid",
+    "ipv4",
+    "ipv6",
+    "date-time",
+    "date",
+    "time",
+    "email",
+    "json-pointer",
+    "uri",
+    "hostname",
+];
+/**
+ * The formats a value matches, narrowest first — see
+ * {@link FORMAT_SPECIFICITY}. Used by `ValidateFormat` to tell a caller what
+ * their value *does* look like when it fails the format they asked for, and
+ * by schema inference, which narrows the list further before labelling a
+ * field.
+ */
+export function matchingFormats(value) {
+    return FORMAT_SPECIFICITY.filter((name) => checkFormat(value, name).valid);
+}

package/dist/lib/infer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Inferring a JSON Schema from example values.
+ *
+ * What this produces is a *description of the samples*, which is the honest
+ * thing to produce: it states types, structure and (optionally) formats and
+ * small enumerations, and deliberately infers no numeric bounds, no string
+ * lengths and no patterns, because three samples never justify a range. The
+ * output is a starting point an operator tightens by hand, not a contract
+ * discovered from data.
+ *
+ * Property order follows first appearance across the samples, so the same
+ * samples always produce byte-identical output.
+ */
+import { type FormatName } from "./formats";
+export type InferOptions = {
+    /** Mark a property required when every object sample at that node had it. */
+    requireAll: boolean;
+    /** Label a string field with a format when every sample matches one. */
+    detectFormats: boolean;
+    /** Turn a small, closed set of string values into an `enum`. */
+    detectEnums: boolean;
+    /** At most this many distinct values may become an enum. */
+    enumThreshold: number;
+    /** Emit `additionalProperties: false` on every inferred object. */
+    closed: boolean;
+    /** Stop descending past this depth and emit an unconstrained schema. */
+    maxDepth: number;
+};
+export declare const DEFAULT_INFER_OPTIONS: InferOptions;
+/**
+ * The most specific format every sample matches, or `null`. "Most specific"
+ * is the order {@link matchingFormats} returns, narrowest first, so a UUID or
+ * a date is labelled as such rather than as the `hostname` it also satisfies.
+ * {@link inferableFormats} first drops the grammars too loose to assert from
+ * samples.
+ */
+export declare function commonFormat(samples: string[]): FormatName | null;
+/**
+ * Infer one schema covering every sample. At least one sample is required;
+ * more samples make the result narrower in the parts that are genuinely
+ * shared and wider in the parts that are not (a property missing from one
+ * sample stops being required, a field that is sometimes null gains `null`
+ * in its type).
+ */
+export declare function inferSchema(samples: unknown[], options?: Partial<InferOptions>): Record<string, unknown>;
+/**
+ * How well an existing schema already covers a set of samples, counted by
+ * distinct canonical value — the number a caller wants before deciding to
+ * replace a schema with an inferred one.
+ */
+export declare function distinctCount(samples: unknown[]): number;

package/dist/lib/infer.js

@@ -0,0 +1,201 @@
+/**
+ * Inferring a JSON Schema from example values.
+ *
+ * What this produces is a *description of the samples*, which is the honest
+ * thing to produce: it states types, structure and (optionally) formats and
+ * small enumerations, and deliberately infers no numeric bounds, no string
+ * lengths and no patterns, because three samples never justify a range. The
+ * output is a starting point an operator tightens by hand, not a contract
+ * discovered from data.
+ *
+ * Property order follows first appearance across the samples, so the same
+ * samples always produce byte-identical output.
+ */
+import { matchingFormats } from "./formats";
+import { canonicalize, isPlainObject, typeOf } from "./value";
+export const DEFAULT_INFER_OPTIONS = {
+    requireAll: true,
+    detectFormats: true,
+    detectEnums: false,
+    enumThreshold: 12,
+    closed: false,
+    maxDepth: 12,
+};
+/** How many distinct string values a node remembers before giving up on enums. */
+const MAX_TRACKED_STRINGS = 200;
+function emptyNode() {
+    return {
+        count: 0,
+        types: new Set(),
+        props: new Map(),
+        propCounts: new Map(),
+        objectCount: 0,
+        items: null,
+        stringCount: 0,
+        distinctStrings: new Set(),
+        stringsOverflowed: false,
+    };
+}
+function observe(node, value, depth, maxDepth) {
+    node.count += 1;
+    const type = typeOf(value);
+    node.types.add(type);
+    if (type === "string") {
+        node.stringCount += 1;
+        if (node.distinctStrings.size < MAX_TRACKED_STRINGS)
+            node.distinctStrings.add(value);
+        else if (!node.distinctStrings.has(value))
+            node.stringsOverflowed = true;
+        return;
+    }
+    if (depth >= maxDepth)
+        return;
+    if (Array.isArray(value)) {
+        if (value.length > 0 && node.items === null)
+            node.items = emptyNode();
+        for (const item of value)
+            observe(node.items, item, depth + 1, maxDepth);
+        return;
+    }
+    if (isPlainObject(value)) {
+        node.objectCount += 1;
+        for (const key of Object.keys(value)) {
+            let child = node.props.get(key);
+            if (child === undefined) {
+                child = emptyNode();
+                node.props.set(key, child);
+            }
+            node.propCounts.set(key, (node.propCounts.get(key) ?? 0) + 1);
+            observe(child, value[key], depth + 1, maxDepth);
+        }
+    }
+}
+/** The order types are written in, so output is stable. */
+const TYPE_ORDER = [
+    "null",
+    "boolean",
+    "integer",
+    "number",
+    "string",
+    "array",
+    "object",
+];
+function renderTypes(types) {
+    const widened = new Set(types);
+    // A node that saw both 3 and 3.5 is a number, not "integer or number".
+    if (widened.has("number"))
+        widened.delete("integer");
+    return TYPE_ORDER.filter((t) => widened.has(t));
+}
+function render(node, opts, depth) {
+    if (depth > opts.maxDepth || node.types.size === 0)
+        return {};
+    const schema = {};
+    const types = renderTypes(node.types);
+    schema["type"] = types.length === 1 ? types[0] : types;
+    if (node.types.has("object")) {
+        const properties = {};
+        const required = [];
+        for (const [key, child] of node.props) {
+            properties[key] = render(child, opts, depth + 1);
+            if (opts.requireAll && node.propCounts.get(key) === node.objectCount)
+                required.push(key);
+        }
+        schema["properties"] = properties;
+        if (required.length > 0)
+            schema["required"] = required;
+        if (opts.closed)
+            schema["additionalProperties"] = false;
+    }
+    if (node.types.has("array")) {
+        // An array position that only ever held empty arrays says nothing about
+        // its items, so no `items` is emitted rather than a false `{}` claim.
+        if (node.items !== null)
+            schema["items"] = render(node.items, opts, depth + 1);
+    }
+    if (node.types.has("string") && node.stringCount > 0) {
+        if (opts.detectEnums &&
+            !node.stringsOverflowed &&
+            node.distinctStrings.size <= opts.enumThreshold) {
+            schema["enum"] = [...node.distinctStrings].sort();
+        }
+        else if (opts.detectFormats && !node.stringsOverflowed) {
+            // Past MAX_TRACKED_STRINGS the node stopped remembering values, so a
+            // format agreed on by the ones it kept says nothing about the ones it
+            // dropped. No label is the honest answer.
+            const format = commonFormat([...node.distinctStrings]);
+            if (format !== null)
+                schema["format"] = format;
+        }
+    }
+    return schema;
+}
+/**
+ * Formats too weak to infer from samples alone, and what it takes to earn
+ * them. Inference writes a *claim* about every future value of a field, so a
+ * grammar that almost everything satisfies is worse than no label at all:
+ *
+ * - **hostname** accepts any bare word, so `"active"` and `"pending"` are
+ *   both valid hostnames. It is only inferred when every sample has a dot,
+ *   which is the shape a real host name has.
+ * - **json-pointer** accepts the empty string and anything starting with
+ *   `/`, so every Unix path qualifies. It is never inferred.
+ *
+ * Validation is unaffected — `ValidateFormat` and `assertFormat` still check
+ * these in full. This narrows only what inference is willing to assert.
+ */
+function inferableFormats(sample) {
+    return matchingFormats(sample).filter((format) => {
+        if (format === "json-pointer")
+            return false;
+        if (format === "hostname")
+            return sample.includes(".");
+        return true;
+    });
+}
+/**
+ * The most specific format every sample matches, or `null`. "Most specific"
+ * is the order {@link matchingFormats} returns, narrowest first, so a UUID or
+ * a date is labelled as such rather than as the `hostname` it also satisfies.
+ * {@link inferableFormats} first drops the grammars too loose to assert from
+ * samples.
+ */
+export function commonFormat(samples) {
+    if (samples.length === 0)
+        return null;
+    let shared = null;
+    for (const sample of samples) {
+        const formats = inferableFormats(sample);
+        if (formats.length === 0)
+            return null;
+        shared = shared === null ? formats : shared.filter((f) => formats.includes(f));
+        if (shared.length === 0)
+            return null;
+    }
+    return shared?.[0] ?? null;
+}
+/**
+ * Infer one schema covering every sample. At least one sample is required;
+ * more samples make the result narrower in the parts that are genuinely
+ * shared and wider in the parts that are not (a property missing from one
+ * sample stops being required, a field that is sometimes null gains `null`
+ * in its type).
+ */
+export function inferSchema(samples, options = {}) {
+    const opts = { ...DEFAULT_INFER_OPTIONS, ...options };
+    if (samples.length === 0)
+        throw new Error("inferSchema needs at least one sample");
+    const root = emptyNode();
+    for (const sample of samples)
+        observe(root, sample, 0, opts.maxDepth);
+    const schema = render(root, opts, 0);
+    return { $schema: "http://json-schema.org/draft-07/schema#", ...schema };
+}
+/**
+ * How well an existing schema already covers a set of samples, counted by
+ * distinct canonical value — the number a caller wants before deciding to
+ * replace a schema with an inferred one.
+ */
+export function distinctCount(samples) {
+    return new Set(samples.map(canonicalize)).size;
+}

package/dist/lib/jsonschema.d.ts

@@ -0,0 +1,50 @@
+/** A schema is an object of keywords, or a boolean that accepts/rejects all. */
+export type Schema = boolean | Record<string, unknown>;
+/** One failure, addressed by a JSON Pointer into the value. */
+export type ValidationError = {
+    /** JSON Pointer to the offending value; `""` is the whole document. */
+    path: string;
+    /** The keyword that rejected it. */
+    keyword: string;
+    /** A message written for a person reading a failed gate. */
+    message: string;
+    /** JSON Pointer to the keyword inside the schema. */
+    schemaPath: string;
+};
+export type ValidateOptions = {
+    /** Enforce `format` instead of treating it as an annotation. */
+    assertFormat: boolean;
+    /** Stop collecting after this many errors. */
+    maxErrors: number;
+};
+export type ValidationResult = {
+    valid: boolean;
+    errors: ValidationError[];
+    /** True when `maxErrors` cut the list short. */
+    truncated: boolean;
+    /**
+     * Constraint keywords this validator does not enforce, from the subschemas
+     * it actually walked for this value — not a static scan of the whole
+     * document. Sorted, so the result is stable.
+     */
+    unsupportedKeywords: string[];
+};
+/**
+ * Validate `value` against `schema`, returning every failure with a JSON
+ * Pointer path. See the module comment for the exact supported subset; the
+ * result's `unsupportedKeywords` names anything in the schema that this
+ * validator did not enforce, so a pass can be read honestly.
+ */
+export declare function validateValue(value: unknown, schema: Schema, options?: Partial<ValidateOptions>): ValidationResult;
+/**
+ * A structural sanity check on the schema itself, run before validation so a
+ * typo like `{"type": "sting"}` is reported as a bad schema rather than as
+ * every value being wrong. Returns the problems found; an empty array means
+ * the schema is well formed as far as this validator is concerned.
+ *
+ * Every position where the spec expects a subschema is descended into,
+ * including `$defs` and `definitions` — a typo in a definition is invisible
+ * at the top level and rejects every value that reaches it through a `$ref`,
+ * which is exactly the failure this check exists to catch.
+ */
+export declare function checkSchemaShape(schema: unknown, path?: string, depth?: number): string[];