argsbarg 6.1.7 → 6.1.8

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.8] - 2026-07-27
+
+### Changed
+
+- **JSON Schema validation** — `inputSchema` and `program.appConfig` validation uses `@cfworker/json-schema`; draft is resolved from each schema’s `$schema` (default Draft-07). Hand-written schemas may opt into 2019-09 or 2020-12 (`$defs` supported). Docs updated for multi-draft and Zod interop.
+
 ## [6.1.7] - 2026-07-24
 
 ### Changed
@@ -859,7 +865,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.7...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.8...HEAD
+[6.1.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.8
 [6.1.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.7
 [6.1.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.6
 [6.1.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.5

package/docs/README.md

@@ -8,7 +8,7 @@ Start here to pick the right guide.
 | **Authoring a `CliProgram`** (humans or agents) | [cli-program.md](cli-program.md) — schema, formats, headless, `read*Flags` |
 | **JSON stdout / `outputSchema`** | [output-schema.md](output-schema.md) — codegen pipeline, JSDoc, narrowing |
 | **App config / `program.appConfig`** | [config-schema.md](config-schema.md) — flat JSON file, `ctx.appConfig`, codegen |
-| **JSON Schema subset (validation)** | [json-schema-subset.md](json-schema-subset.md) — supported keywords for config and `inputSchema` |
+| **JSON Schema validation** | [json-schema-subset.md](json-schema-subset.md) — Draft-07 / 2019-09 / 2020-12 (`$schema` on each schema; default Draft-07) |
 | **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `configure --sync` |
 | **HTTP tool server** | [http-server.md](http-server.md) — `myapp http`, endpoints, curl examples |
 | **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure --sync` |

package/docs/cli-program.md

@@ -111,7 +111,7 @@ Descriptions and schemas are copied into MCP tools, HTTP OpenAPI, and generated
 - For shape discovery: HTTP agents load **`docs openapi`** or `GET /openapi.json`; MCP agents use **`docs cli-schema`**; load full **`docs cli`** only when prose is needed.
 - Skill **`reference.md`** uses a compact CLI guide (no inline `outputSchema` JSON) — see [bundled-docs.md](bundled-docs.md#agent-artifact-contract).
 
-Validation keywords: [json-schema-subset.md](json-schema-subset.md).
+Validation: [json-schema-subset.md](json-schema-subset.md) (Draft-07 default; 2019-09 / 2020-12 when `$schema` is set — including Zod-generated schemas).
 
 ## Well-known option names
 
@@ -293,7 +293,7 @@ For nested tool bodies (e.g. invoice template data), declare a matching property
 
 **Precedence:** if `--invoice` is set, the flag value wins and stdin is not read.
 
-Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>()`** — all synchronous. Argsbarg reads piped stdin before calling the handler when a `pipable` Json flag is omitted. When `leaf.inputSchema` is set, argsbarg validates merged inputs **before the handler runs** (same JSON Schema subset as `program.appConfig`); `ctx.inputs` returns the cached result.
+Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>()`** — all synchronous. Argsbarg reads piped stdin before calling the handler when a `pipable` Json flag is omitted. When `leaf.inputSchema` is set, argsbarg validates merged inputs **before the handler runs** (same engine as `program.appConfig`; draft from `$schema` on the schema object); `ctx.inputs` returns the cached result.
 
 At most one `pipable` Json option per leaf. Json option names must appear in `inputSchema.properties` when a custom `inputSchema` is set.
 
@@ -321,7 +321,7 @@ When the entire tool body is JSON (no CLI flags), set **`kind: "json"`** on the
 
 Example CLI: `jq '{format:"pdf", invoice:.}' data.json | myapp render-invoice`
 
-See [output-schema.md](output-schema.md) for schemagen `inputType`, [http-server.md](http-server.md) for HTTP tool bodies, and [json-schema-subset.md](json-schema-subset.md) for supported schema keywords.
+See [output-schema.md](output-schema.md) for schemagen `inputType`, [http-server.md](http-server.md) for HTTP tool bodies, and [json-schema-subset.md](json-schema-subset.md) for validation drafts, Zod interop, and keyword notes.
 
 `CliLeafInputs` is intentionally untyped at the framework level. Narrow in your app (`read*Flags(ctx)` returning a typed struct) rather than expecting inference from `satisfies CliLeaf`.
 

package/docs/config-schema.md

@@ -48,7 +48,7 @@ await cli.run();
 
 **`_bindings`** — reserved top-level metadata: `{ "_bindings": { "apiToken": "env" } }`. Set via wizard (Enter to use env), `configure set --from-env`, or `ctx.appConfig.set` (marks `file`). Optional keys can be bound to `skip`.
 
-**Validation at runtime** — argsbarg validates the config file and `configure set` / `ctx.appConfig.set` against the effective JSON Schema ([supported subset](json-schema-subset.md)). Partial writes (bindings only, single-key updates) skip required-property checks.
+**Validation at runtime** — argsbarg validates the config file and `configure set` / `ctx.appConfig.set` against the effective JSON Schema ([validation](json-schema-subset.md)). Draft is chosen from `jsonSchema.$schema` (default Draft-07). Partial writes (bindings only, single-key updates) skip required-property checks.
 
 See [cli-program.md — Configuration](cli-program.md#configuration-programappconfig) for resolution order, bootstrap timing, and `configure get`/`set`.
 
@@ -67,7 +67,7 @@ export interface CliAppConfigEntry {
 
 export interface CliAppConfig {
   commands?: boolean | { enabled?: boolean; mcpSet?: boolean };
-  jsonSchema?: Record<string, unknown>;  // draft-07 block schema
+  jsonSchema?: Record<string, unknown>;  // JSON Schema block; include $schema to opt into 2019-09 / 2020-12
   entries: Record<string, CliAppConfigEntry>;
 }
 ```
@@ -155,7 +155,7 @@ flowchart LR
   end
   subgraph runtime [Runtime]
     Program["program.appConfig.jsonSchema"]
-    Validate["argsbarg runtime subset validator"]
+    Validate["@cfworker/json-schema (draft from $schema)"]
   end
   src --> Script --> Gen --> Json
   Gen --> Index --> Program --> Validate
@@ -180,16 +180,19 @@ export interface AppConfig {
 
 Wire on the program root: `import { AppConfigSchema } from "./config/__generated__"`.
 
-### Supported AppConfig shapes (argsbarg runtime validator)
+### Supported AppConfig shapes (runtime validation)
 
-| Supported (v1) | Deferred |
+Validation is [@cfworker/json-schema](https://www.npmjs.com/package/@cfworker/json-schema) with draft from `$schema` (default Draft-07). See [json-schema-subset.md](json-schema-subset.md) for drafts, Zod interop, and limits.
+
+| Commonly used | Notes |
 | --- | --- |
-| `type`, `properties`, `required`, `additionalProperties` | remote `$ref` |
-| `enum`, `const`, `default` | complex `if`/`then`/`else` |
-| local `#/definitions` + `$ref` | full draft-2020-12 |
-| `anyOf` / `oneOf` (basic) | |
+| `type`, `properties`, `required`, `additionalProperties` | |
+| `enum`, `const` | `default` is not applied at validation time |
+| local `#/definitions` + `$ref` (Draft-07) or `#/$defs` + `$ref` (2020-12) | remote `$ref` not supported |
+| `anyOf` / `oneOf` / `allOf` | |
 | `items`, `minItems`, `maxItems` | |
 | `minimum`, `maximum`, `minLength`, `maxLength`, `pattern` | |
+| `format` | includes argsbarg `comma-list` |
 
 ## Minimal example (no schemagen)
 

package/docs/decisions.md

@@ -33,7 +33,7 @@ Zod may actually cause more complexity and little/no gain for consumers.
 Yes Zod implements some features we do custom for JSON-SCHEMA, but is opinionated, less flexible, and would actually explode complexity in some situations. Zod could be a win for consumers if they require substantial, complex validation -- but then that may not convert well to json-schema anyways and json-schema generation is a big win.
 
 1. Argsbarg does a lot of schema patching/manipulation to create different schemas per target (cli-schema.json, MCP contract, openapi.json). This would be harder with Zod
-2. Consumers can already use zod if they want by using Zod's to-json-schema features to convert when passing to Argsbarg. So we aren't actually alienating / thwarting consumers from using Zod anyways.
+2. Consumers can use Zod by converting to JSON Schema (`zod-to-json-schema`, `z.toJSONSchema()`) and passing the result to `inputSchema` / `appConfig.jsonSchema`. Argsbarg resolves the validator draft from each schema’s `$schema` (Draft-07 default; 2019-09 / 2020-12 when set).
 3. For uses like API pass-through, proxy, dynamic schemas, Zod may actually explode complexity for consumers.
 4. Our TS->json-schema approach is actually easier and better in many cases
   - Just write plain typescript, done.

package/docs/json-schema-subset.md

@@ -1,39 +1,65 @@
-# JSON Schema subset
+# JSON Schema validation
 
-Argsbarg validates `program.appConfig`, leaf `inputSchema`, and related documents with a **custom Draft-07 subset** in [`src/config/validate.ts`](../src/config/validate.ts). There is no runtime dependency on a full JSON Schema validator.
+Argsbarg validates `program.appConfig`, leaf `inputSchema`, and related documents with [**@cfworker/json-schema**](https://www.npmjs.com/package/@cfworker/json-schema). The validator draft is chosen from each schema’s `$schema` URI (default **Draft-07** when omitted). Use this page when authoring schemas for config files, `inputSchema` on leaves, or `@sg` schemagen output.
 
-Use this page when authoring schemas for config files, `inputSchema` on leaves, or `@sg` schemagen output.
+## Schema draft
+
+| `$schema` (examples) | Validator draft |
+| --- | --- |
+| *(omitted)* | Draft-07 (schemagen default) |
+| `http://json-schema.org/draft-07/schema#` | Draft-07 |
+| `https://json-schema.org/draft/2019-09/schema` | 2019-09 |
+| `https://json-schema.org/draft/2020-12/schema` | 2020-12 |
+
+Hand-written schemas may use **2020-12** with `$defs` and `#/$defs/...` `$ref`s. Schemagen (`ts-json-schema-generator`) still emits Draft-07 with `definitions`.
+
+## From Zod (or other generators)
+
+You can pass JSON Schema from **`zod-to-json-schema`**, Zod v4 **`z.toJSONSchema()`**, or any tool that emits a root schema with `$schema`:
+
+| Source | Typical `$schema` | Works with argsbarg |
+| --- | --- | --- |
+| `zod-to-json-schema` (default) | Draft-07 | Yes — matches default when `$schema` omitted |
+| `z.toJSONSchema()` (default) | 2020-12 | Yes — draft resolved from `$schema` |
+| argsbarg schemagen | Draft-07 | Yes |
+
+Set the result on `leaf.inputSchema` or `program.appConfig.jsonSchema`. Validation uses the schema object and its `$schema` URI; not every Zod feature survives JSON Schema conversion (refinements, transforms, etc.).
 
 ## Supported constructs
 
+Validation uses [@cfworker/json-schema](https://www.npmjs.com/package/@cfworker/json-schema) for the draft declared by `$schema`. Schemas from schemagen and typical Zod exports commonly use:
+
 | Feature | Notes |
 | --- | --- |
 | `type` | `object`, `array`, `string`, `integer`, `number`, `boolean`, `null` |
 | `properties` / `required` | Object keys; `additionalProperties: false` enforced when set |
 | `items` | Homogeneous arrays; comma-separated CLI strings coerced when `items` is a primitive |
 | `enum` / `const` | Exact value checks |
-| `anyOf` / `oneOf` | First matching branch wins; errors surface when none match |
-| `$ref` | **Local only** — `#/definitions/Name` resolved within the same root document |
-| `definitions` | Companion to local `$ref` |
-| `format` | `date`, `date-time`, `duration`, `comma-list` (and related string coercions) |
+| `anyOf` / `oneOf` / `allOf` | Combinators (validator-native) |
+| `$ref` | **Local only** — `#/definitions/Name` (Draft-07) or `#/$defs/Name` (2019-09 / 2020-12) |
+| `definitions` / `$defs` | Companion to local `$ref` (draft-dependent) |
+| `format` | Built-ins include `date`, `date-time`, `duration`; argsbarg registers `comma-list` |
 | `minimum` / `maximum` | Numbers and integers |
 | `minLength` / `maxLength` | Strings |
 | `pattern` | String regex (ECMAScript) |
 
 ## Partial validation
 
-`validateConfigDocumentPartial` validates **present keys only** — root `required` is skipped. Used for `configure set` partial writes and bootstrap flows.
+`validateConfigDocumentPartial` validates **present keys only** — all `required` arrays are stripped before validation. Used for `configure set` partial writes and bootstrap flows.
 
 Leaf `inputSchema` validation uses full validation (including `required`) before the handler runs.
 
-## Not supported (today)
+## Argsbarg-specific behavior
+
+- Framework keys (`_bindings`, etc.) are omitted before config validation when `additionalProperties: false`.
+- CLI `configure set` still coerces comma-separated primitives, booleans, and numbers before validation (`parseConfigSetValue`).
+
+## Not guaranteed
 
 - Remote `$ref` (`http://…`, other files)
-- `allOf`, conditional (`if`/`then`/`else`), `not`
-- Unevaluated / dynamic references
 - `default` application at validation time (defaults come from CLI option `default` or config bindings)
 
-If schemagen emits an unsupported keyword, simplify the TypeScript type or post-process the generated JSON Schema.
+If schemagen emits keywords the validator rejects, simplify the TypeScript type or post-process the generated JSON Schema.
 
 ## Where validation runs
 

package/docs/output-schema.md

@@ -29,7 +29,7 @@ export const status = {
 
 **Set on the leaf only** — not under `mcpTool`.
 
-**Draft version** — argsbarg accepts any JSON Schema object (`type`, `properties`, `definitions`, etc.). Generators may emit draft-07 or draft 2020-12; docgen embeds the object as-is.
+**Draft version** — for **`inputSchema`** and **`appConfig.jsonSchema`**, argsbarg validates using the draft declared in `$schema` (default Draft-07 when omitted). Schemas from schemagen, `zod-to-json-schema`, or `z.toJSONSchema()` may use Draft-07 or 2020-12. **`outputSchema`** is embedded in docs/MCP/OpenAPI as-is and is not runtime-validated.
 
 See [cli-program.md — Structured stdout](cli-program.md#structured-stdout) for when to use `outputSchema` vs `notes`, and [mcp.md](mcp.md) for how MCP returns parsed JSON as `structuredContent`.
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "argsbarg",
-  "version": "6.1.7",
+  "version": "6.1.8",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {
+    "@cfworker/json-schema": "^4",
     "ts-json-schema-generator": "^2.3.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.0",
+    "@biomejs/biome": "^2.5.5",
     "@types/bun": "^1.3.12",
     "dts-bundle-generator": "^9.5.1",
     "typescript": "^5.9.3"

package/src/config/validate.test.ts

@@ -3,7 +3,7 @@ Tests for config/validate module behavior.
 */
 
 import { describe, expect, test } from "bun:test";
-import { parseConfigSetValue, validateConfigDocument } from "./validate.ts";
+import { parseConfigSetValue, resolveSchemaDraft, validateConfigDocument } from "./validate.ts";
 
 const rootSchema = {
   type: "object",
@@ -98,4 +98,48 @@ describe("config/validate", () => {
     expect(() => parseConfigSetValue("a,b", schema, rootSchema, false)).toThrow(/--json/);
     expect(parseConfigSetValue('[{"ttl":1}]', schema, rootSchema, false)).toEqual([{ ttl: 1 }]);
   });
+
+  test("resolveSchemaDraft maps $schema URIs", () => {
+    expect(resolveSchemaDraft({ $schema: "http://json-schema.org/draft-07/schema#" })).toBe("7");
+    expect(resolveSchemaDraft({ $schema: "https://json-schema.org/draft/2020-12/schema" })).toBe("2020-12");
+    expect(resolveSchemaDraft({ $schema: "https://json-schema.org/draft/2019-09/schema" })).toBe("2019-09");
+    expect(resolveSchemaDraft({})).toBe("7");
+  });
+
+  test("validates draft 2020-12 schemas when $schema is set", () => {
+    const schema = {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      additionalProperties: false,
+      required: ["name"],
+      properties: {
+        name: { type: "string", minLength: 1 },
+      },
+    };
+    expect(validateConfigDocument({ name: "ok" }, schema).valid).toBe(true);
+    expect(validateConfigDocument({ name: "" }, schema).valid).toBe(false);
+    expect(validateConfigDocument({}, schema).valid).toBe(false);
+  });
+
+  test("validates draft 2020-12 $defs refs", () => {
+    const schema = {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      additionalProperties: false,
+      required: ["item"],
+      properties: {
+        item: { $ref: "#/$defs/Item" },
+      },
+      $defs: {
+        Item: {
+          type: "object",
+          additionalProperties: false,
+          required: ["id"],
+          properties: { id: { type: "string" } },
+        },
+      },
+    };
+    expect(validateConfigDocument({ item: { id: "a" } }, schema).valid).toBe(true);
+    expect(validateConfigDocument({ item: { id: 1 } }, schema).valid).toBe(false);
+  });
 });

package/src/config/validate.ts

@@ -1,9 +1,10 @@
 /*
-Draft-07 JSON Schema subset validator for program.appConfig files.
-Aligned with common ts-json-schema-generator output (local $ref, objects, scalars).
+JSON Schema validation for program.appConfig and leaf inputSchema (@cfworker/json-schema).
+CLI value coercion for configure set remains here (comma-separated arrays, booleans, etc.).
 */
 
-import { parseCommaList, parseDate, parseDateTime } from "../core/formats.ts";
+import { format as jsonSchemaFormats, type Schema, type SchemaDraft, Validator } from "@cfworker/json-schema";
+import { parseCommaList, parseDate, parseDateTime, validateCommaList } from "../core/formats.ts";
 import { isFrameworkConfigKey } from "./bindings.ts";
 
 type JsonSchema = Record<string, unknown>;
@@ -19,248 +20,183 @@ export interface ValidateResult {
   errors: string[];
 }
 
-/** Validate `data` against a JSON Schema root. Returns human-readable error messages. */
-export function validateConfigDocument(data: unknown, rootSchema: JsonSchema): ValidateResult {
-  const errors: string[] = [];
-  validateValue(data, rootSchema, rootSchema, "$", errors, false);
-  return { valid: errors.length === 0, errors };
-}
-
-/** Validate present keys only — skips root `required` checks (partial writes / bootstrap). */
-export function validateConfigDocumentPartial(data: unknown, rootSchema: JsonSchema): ValidateResult {
-  const errors: string[] = [];
-  validateValue(data, rootSchema, rootSchema, "$", errors, true);
-  return { valid: errors.length === 0, errors };
-}
-
-function validateValue(
-  value: unknown,
-  schema: JsonSchema,
-  root: JsonSchema,
-  path: string,
-  errors: string[],
-  partial: boolean,
-): void {
-  const resolved = resolveSchema(schema, root);
-  if (!resolved) {
-    return;
-  }
-
-  if ("const" in resolved) {
-    if (value !== resolved.const) {
-      errors.push(`${path}: must be ${JSON.stringify(resolved.const)}`);
+if (!jsonSchemaFormats["comma-list"]) {
+  jsonSchemaFormats["comma-list"] = (value: string) => {
+    try {
+      validateCommaList(value);
+      return true;
+    } catch {
+      return false;
     }
-    return;
-  }
+  };
+}
 
-  if (Array.isArray(resolved.enum)) {
-    if (!resolved.enum.some((item) => item === value)) {
-      errors.push(`${path}: must be one of ${JSON.stringify(resolved.enum)}`);
-    }
-    return;
+function dataForSchemaValidation(data: unknown): unknown {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return data;
   }
-
-  const anyOf = resolved.anyOf ?? resolved.oneOf;
-  if (Array.isArray(anyOf)) {
-    const branchErrors: string[][] = [];
-    for (const branch of anyOf) {
-      if (typeof branch !== "object" || branch === null || Array.isArray(branch)) {
-        continue;
-      }
-      const branchErrs: string[] = [];
-      validateValue(value, branch as JsonSchema, root, path, branchErrs, partial);
-      if (branchErrs.length === 0) {
-        return;
-      }
-      branchErrors.push(branchErrs);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (isFrameworkConfigKey(key)) {
+      continue;
     }
-    errors.push(`${path}: must match one of the allowed types`);
-    if (branchErrors.length === 1 && branchErrors[0]?.[0]) {
-      errors.push(branchErrors[0][0]);
-    }
-    return;
-  }
-
-  const types = normalizeTypes(resolved.type);
-  if (types.length > 0 && !matchesAnyType(value, types)) {
-    errors.push(`${path}: must be ${types.join(" or ")}`);
-    return;
+    out[key] = value;
   }
+  return out;
+}
 
-  if (types.includes("string") || (types.length === 0 && typeof value === "string")) {
-    validateString(value, resolved, path, errors);
+function schemaWithoutRequired(schema: unknown): JsonSchema {
+  if (typeof schema !== "object" || schema === null) {
+    return schema as JsonSchema;
   }
-  if (types.includes("number") || types.includes("integer")) {
-    validateNumber(value, resolved, path, errors, types.includes("integer"));
+  if (Array.isArray(schema)) {
+    return schema.map(schemaWithoutRequired) as unknown as JsonSchema;
   }
-  if (types.includes("boolean")) {
-    if (typeof value !== "boolean") {
-      errors.push(`${path}: must be boolean`);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === "required") {
+      continue;
     }
+    out[key] = schemaWithoutRequired(value);
   }
-  if (types.includes("null") && value !== null) {
-    errors.push(`${path}: must be null`);
-  }
-  if (types.includes("object") || (types.length === 0 && isPlainObject(value))) {
-    validateObject(value, resolved, root, path, errors, partial);
-  }
-  if (types.includes("array") || (types.length === 0 && Array.isArray(value))) {
-    validateArray(value, resolved, root, path, errors, partial);
-  }
+  return out as JsonSchema;
 }
 
-function resolveSchema(schema: JsonSchema, root: JsonSchema): JsonSchema | undefined {
-  const ref = schema.$ref;
-  if (typeof ref === "string" && ref.startsWith("#/definitions/")) {
-    const name = decodeURIComponent(ref.slice("#/definitions/".length));
-    const definitions = root.definitions;
-    if (typeof definitions !== "object" || definitions === null || Array.isArray(definitions)) {
-      return schema;
-    }
-    const target = (definitions as Record<string, unknown>)[name];
-    if (typeof target === "object" && target !== null && !Array.isArray(target)) {
-      return target as JsonSchema;
-    }
+function formatInstancePath(instanceLocation: string): string {
+  if (instanceLocation.length === 0 || instanceLocation === "#") {
+    return "$";
   }
-  return schema;
-}
-
-function normalizeTypes(type: unknown): string[] {
-  if (typeof type === "string") {
-    return [type];
+  if (instanceLocation.startsWith("#/")) {
+    return instanceLocation.slice(2).replace(/\//g, ".");
   }
-  if (Array.isArray(type)) {
-    return type.filter((t): t is string => typeof t === "string");
-  }
-  return [];
+  return instanceLocation;
 }
 
-function matchesAnyType(value: unknown, types: string[]): boolean {
-  for (const t of types) {
-    if (t === "null" && value === null) return true;
-    if (t === "array" && Array.isArray(value)) return true;
-    if (t === "object" && isPlainObject(value)) return true;
-    if (t === "integer" && typeof value === "number" && Number.isInteger(value)) return true;
-    if (t === "number" && typeof value === "number") return true;
-    if (t === "boolean" && typeof value === "boolean") return true;
-    if (t === "string" && typeof value === "string") return true;
-  }
-  return types.length === 0;
+function formatValidationErrors(errors: { instanceLocation: string; error: string }[]): string[] {
+  return errors.map(({ instanceLocation, error }) => {
+    const path = formatInstancePath(instanceLocation);
+    return `${path}: ${error}`;
+  });
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
 }
 
-function validateString(value: unknown, schema: JsonSchema, path: string, errors: string[]): void {
-  if (typeof value !== "string") {
-    errors.push(`${path}: must be string`);
-    return;
+/** Map a schema `$schema` URI to the @cfworker/json-schema draft (defaults to Draft-07). */
+export function resolveSchemaDraft(schema: JsonSchema): SchemaDraft {
+  const $schema = schema.$schema;
+  if (typeof $schema !== "string") {
+    return "7";
   }
-  if (typeof schema.minLength === "number" && value.length < schema.minLength) {
-    errors.push(`${path}: string shorter than minLength ${schema.minLength}`);
+  const normalized = $schema.toLowerCase();
+  if (normalized.includes("2020-12")) {
+    return "2020-12";
   }
-  if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
-    errors.push(`${path}: string longer than maxLength ${schema.maxLength}`);
+  if (normalized.includes("2019-09")) {
+    return "2019-09";
   }
-  if (typeof schema.pattern === "string") {
-    try {
-      if (!new RegExp(schema.pattern).test(value)) {
-        errors.push(`${path}: does not match pattern`);
-      }
-    } catch {
-      /* invalid pattern in schema — skip */
+  if (normalized.includes("draft-04") || normalized.includes("draft/4")) {
+    return "4";
+  }
+  if (normalized.includes("draft-07") || normalized.includes("draft/7")) {
+    return "7";
+  }
+  return "7";
+}
+
+function resolveJsonPointer(root: JsonSchema, ref: string): unknown {
+  if (!ref.startsWith("#/")) {
+    return undefined;
+  }
+  const segments = ref
+    .slice(2)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (typeof current !== "object" || current === null || Array.isArray(current)) {
+      return undefined;
     }
+    current = (current as Record<string, unknown>)[segment];
   }
+  return current;
 }
 
-function validateNumber(value: unknown, schema: JsonSchema, path: string, errors: string[], integer: boolean): void {
-  if (typeof value !== "number" || Number.isNaN(value)) {
-    errors.push(`${path}: must be number`);
+function attachRootCompanionSchemas(validator: Validator, root: JsonSchema, active: JsonSchema): void {
+  if (active === root) {
     return;
   }
-  if (integer && !Number.isInteger(value)) {
-    errors.push(`${path}: must be integer`);
+  const companion: Schema = {};
+  if (typeof root.definitions === "object" && root.definitions !== null && !Array.isArray(root.definitions)) {
+    companion.definitions = root.definitions;
   }
-  if (typeof schema.minimum === "number" && value < schema.minimum) {
-    errors.push(`${path}: below minimum ${schema.minimum}`);
+  if (typeof root.$defs === "object" && root.$defs !== null && !Array.isArray(root.$defs)) {
+    companion.$defs = root.$defs;
   }
-  if (typeof schema.maximum === "number" && value > schema.maximum) {
-    errors.push(`${path}: above maximum ${schema.maximum}`);
+  if (Object.keys(companion).length > 0) {
+    validator.addSchema(companion);
   }
 }
 
-function validateObject(
-  value: unknown,
+function validatorForSchema(schema: JsonSchema, root: JsonSchema, partial: boolean): Validator {
+  const active = partial ? schemaWithoutRequired(schema) : schema;
+  const validator = new Validator(active as Schema, resolveSchemaDraft(root), false);
+  attachRootCompanionSchemas(validator, root, active);
+  return validator;
+}
+
+function validateInstance(
+  data: unknown,
   schema: JsonSchema,
   root: JsonSchema,
-  path: string,
-  errors: string[],
   partial: boolean,
-): void {
-  if (!isPlainObject(value)) {
-    errors.push(`${path}: must be object`);
-    return;
-  }
-  const properties = schema.properties;
-  const propMap =
-    typeof properties === "object" && properties !== null && !Array.isArray(properties)
-      ? (properties as Record<string, JsonSchema>)
-      : undefined;
+  stripFrameworkKeys: boolean,
+): ValidateResult {
+  const validator = validatorForSchema(schema, root, partial);
+  const payload = stripFrameworkKeys ? dataForSchemaValidation(data) : data;
+  const result = validator.validate(payload);
+  if (result.valid) {
+    return { valid: true, errors: [] };
+  }
+  return { valid: false, errors: formatValidationErrors(result.errors) };
+}
 
-  if (propMap) {
-    for (const [key, propSchema] of Object.entries(propMap)) {
-      if (key in value) {
-        validateValue(value[key], propSchema, root, `${path}.${key}`, errors, partial);
-      }
-    }
-  }
+function validateAgainstSchema(data: unknown, rootSchema: JsonSchema, partial: boolean): ValidateResult {
+  return validateInstance(data, rootSchema, rootSchema, partial, true);
+}
 
-  if (!partial) {
-    const required = schema.required;
-    if (Array.isArray(required)) {
-      for (const key of required) {
-        if (typeof key === "string" && !(key in value)) {
-          errors.push(`${path}: missing required property '${key}'`);
-        }
-      }
-    }
-  }
+/** Validate `data` against a JSON Schema root. Returns human-readable error messages. */
+export function validateConfigDocument(data: unknown, rootSchema: JsonSchema): ValidateResult {
+  return validateAgainstSchema(data, rootSchema, false);
+}
 
-  if (schema.additionalProperties === false && propMap) {
-    for (const key of Object.keys(value)) {
-      if (isFrameworkConfigKey(key)) continue;
-      if (!(key in propMap)) {
-        errors.push(`${path}: unknown property '${key}'`);
-      }
-    }
-  }
+/** Validate present keys only — skips `required` checks (partial writes / bootstrap). */
+export function validateConfigDocumentPartial(data: unknown, rootSchema: JsonSchema): ValidateResult {
+  return validateAgainstSchema(data, rootSchema, true);
 }
 
-function validateArray(
-  value: unknown,
-  schema: JsonSchema,
-  root: JsonSchema,
-  path: string,
-  errors: string[],
-  partial: boolean,
-): void {
-  if (!Array.isArray(value)) {
-    errors.push(`${path}: must be array`);
-    return;
+function resolveSchema(schema: JsonSchema, root: JsonSchema): JsonSchema | undefined {
+  const ref = schema.$ref;
+  if (typeof ref !== "string" || !ref.startsWith("#/")) {
+    return schema;
   }
-  if (typeof schema.minItems === "number" && value.length < schema.minItems) {
-    errors.push(`${path}: fewer than minItems ${schema.minItems}`);
+  const target = resolveJsonPointer(root, ref);
+  if (typeof target === "object" && target !== null && !Array.isArray(target)) {
+    return target as JsonSchema;
   }
-  if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
-    errors.push(`${path}: more than maxItems ${schema.maxItems}`);
+  return schema;
+}
+
+function normalizeTypes(type: unknown): string[] {
+  if (typeof type === "string") {
+    return [type];
   }
-  const items = schema.items;
-  if (typeof items === "object" && items !== null && !Array.isArray(items)) {
-    for (let i = 0; i < value.length; i++) {
-      validateValue(value[i], items as JsonSchema, root, `${path}[${i}]`, errors, partial);
-    }
+  if (Array.isArray(type)) {
+    return type.filter((t): t is string => typeof t === "string");
   }
+  return [];
 }
 
 export function validateParsedConfigValue(
@@ -271,10 +207,9 @@ export function validateParsedConfigValue(
   if (!propertySchema) {
     return parsed;
   }
-  const errors: string[] = [];
-  validateValue(parsed, propertySchema, rootSchema, "$", errors, false);
-  if (errors.length > 0) {
-    throw new Error(errors[0] ?? "Invalid config value");
+  const result = validateInstance(parsed, propertySchema, rootSchema, false, false);
+  if (!result.valid) {
+    throw new Error(result.errors[0] ?? "Invalid config value");
   }
   return parsed;
 }