@kindgi/schema 0.1.1 → 0.1.3

package/README.md

@@ -15,6 +15,8 @@ Turn the JSON Schemas that live in `@kindgi/specs/*.schema.json` into runtime-us
   - `getSchema(id)` — retrieve the raw parsed schema JSON.
   - `ids()` — list every registered `$id`.
 - **`compileInlineSchema(schema)`** — compile one anonymous JSON Schema (no `$id`, no cross-schema `$ref`) into a `CompiledInlineSchema` whose `validate<T>(data)` returns `Result<T, ValidationErrorLike>`.
+- **`compileJsonSchema(schema, options?)`** — compile one JSON Schema into an Ajv `ValidateFunction`, in the dialect it declares in `$schema` (draft-06, draft-07, 2019-09 or 2020-12; 2020-12 when it declares none), with formats checked. `dialects` limits the ones it may declare. `strict` (default `true`) is Ajv's strict mode, a lint for the schemas you write; turn it off for a schema from elsewhere, such as an MCP server's. `useDefaults` fills in each property's `default`. Throws for another dialect, or a schema that doesn't compile.
+- **`jsonSchemaDialect(schema, allowed?)`** — the dialect a schema declares, as `'draft-06' | 'draft-07' | '2019-09' | '2020-12'`; throws, naming it, for one Kindgi doesn't validate (or one not in `allowed`).
 - **`versionOf(schema)`** — extract `{ major, semver }` from a schema's `$id` and `$comment`.
 - **Zod authoring helpers** — `AnySchema` (a JSON Schema object or a Zod v4 schema), `isZodSchema`, `isJsonSchemaObject`, `schemaKindOf`, and `toJSONSchema` / `toJSONSchemaSync` (with `loadZodConverter` / `loadZodConverterSync`), which convert Zod to JSON Schema through Zod's native `z.toJSONSchema()`. `zod` is an optional peer dependency: it is imported only when a Zod schema is passed, and a missing or failed conversion is an `invalid-zod-conversion` error, not a throw.
 - **`canonicalize(value)`** — deterministic JSON serialization (sorted keys, `undefined` omitted, no whitespace), a subset of RFC 8785 used for signing.
@@ -50,4 +52,4 @@ if (validated.kind === 'ok') {
 - **No Zod on the wire, and no JSON Schema → Zod conversion.** Zod is an authoring convenience: schemas are converted one way, Zod → JSON Schema, and every schema that is registered or exchanged is JSON Schema.
 - **No schema migration helpers.** Every schema is at its first major version, so there is nothing to migrate between.
 - **No TypeScript type generation.** Callers define TypeScript types that match schema shapes by hand, or author with Zod and derive them with `z.infer`.
-- **No custom Ajv extensions.** Uses stock Ajv Draft 2020-12 + `ajv-formats`, with no custom keywords.
+- **No custom Ajv extensions.** Uses stock Ajv + `ajv-formats`, with no custom keywords. Kindgi's own schemas are Draft 2020-12; `compileJsonSchema` compiles a schema from elsewhere with Ajv's class for its declared dialect.

package/SPEC.md

@@ -107,7 +107,7 @@ With Zod v4 as the workspace-wide version, `@kindgi/schema` exposes three helper
 
 - **No wire-level Zod.** Every artifact on the wire is a JSON Schema. Language-agnostic MCP + OpenAPI + Python/Go/Rust consumers must never see Zod.
 - **No TS type generation from JSON Schemas.** Callers maintain matching TS types by hand, or author with Zod and derive them via `z.infer<...>`.
-- **No custom Ajv keywords or extensions.** Stock Ajv Draft 2020-12 + `ajv-formats` only.
+- **No custom Ajv keywords or extensions.** Stock Ajv + `ajv-formats` only: Draft 2020-12 for Kindgi's own schemas, and `compileJsonSchema` compiles a schema from elsewhere (an MCP server's) with Ajv's class for the dialect it declares.
 - **No schema migration between majors.** Not needed until any schema has a v2.
 - **No caching of loaded registries across calls.** Callers manage their own registry lifecycle.
 

package/dist/dialect.d.ts

@@ -0,0 +1,24 @@
+import type { ValidateFunction } from 'ajv';
+/** The JSON Schema dialects a schema may declare. */
+export type JsonSchemaDialect = 'draft-06' | 'draft-07' | '2019-09' | '2020-12';
+/**
+ * The dialect `schema` declares in `$schema` (2020-12 when it declares
+ * none). Throws for a dialect that isn't one of `allowed` (by default,
+ * every one Kindgi validates), naming it and them.
+ */
+export declare function jsonSchemaDialect(schema: Readonly<Record<string, unknown>>, allowed?: readonly JsonSchemaDialect[]): JsonSchemaDialect;
+export interface CompileJsonSchemaOptions {
+    /** The dialects the schema may declare. Default: every one Kindgi validates. */
+    readonly dialects?: readonly JsonSchemaDialect[];
+    /** Ajv's strict mode. Default `true`; `false` for a schema from elsewhere (see above). */
+    readonly strict?: boolean;
+    /** Fill in each property's `default` in the data validated (Ajv's `useDefaults`). */
+    readonly useDefaults?: boolean;
+}
+/**
+ * A validator for `schema`, compiled in its declared dialect. Throws when
+ * the dialect isn't supported (or allowed) or the schema doesn't compile,
+ * as `ajv.compile` does.
+ */
+export declare function compileJsonSchema(schema: Readonly<Record<string, unknown>>, options?: CompileJsonSchemaOptions): ValidateFunction;
+//# sourceMappingURL=dialect.d.ts.map

package/dist/dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../src/dialect.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC;AAe5C,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAWhF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,GAAE,SAAS,iBAAiB,EAAiB,GACnD,iBAAiB,CAenB;AAOD,MAAM,WAAW,wBAAwB;IACvC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,GAAE,wBAA6B,GACrC,gBAAgB,CAmBlB"}

package/dist/dialect.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Compile a JSON Schema in the dialect it declares (`$schema`). Kindgi's
+ * own schemas are Draft 2020-12, the default when a schema declares none.
+ * A schema from elsewhere (an MCP server: the TypeScript MCP SDK emits
+ * draft-07) means its keywords as its dialect defines them: draft-07's
+ * array-form `items` is a tuple, 2020-12's is not. So each dialect gets
+ * Ajv's class for it, not 2020-12's with another meta-schema added.
+ *
+ * `strict` is Ajv's strict mode, an authoring lint (unknown keywords and
+ * formats, loose tuples, union types): right for the schemas a pack's
+ * author writes, wrong for a schema someone else's server sends, which is
+ * valid JSON Schema without being written to that standard.
+ */
+import { createRequire } from 'node:module';
+import { Ajv } from 'ajv';
+import * as addFormatsModule from 'ajv-formats';
+import { Ajv2019 } from 'ajv/dist/2019.js';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+const addFormatsRaw = addFormatsModule;
+const addFormats = typeof addFormatsRaw === 'function'
+    ? addFormatsRaw
+    : addFormatsRaw.default;
+const require = createRequire(import.meta.url);
+const DIALECTS = new Map([
+    ['http://json-schema.org/draft-06/schema', 'draft-06'],
+    ['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'],
+]);
+const ALL_DIALECTS = [...DIALECTS.values()];
+/**
+ * The dialect `schema` declares in `$schema` (2020-12 when it declares
+ * none). Throws for a dialect that isn't one of `allowed` (by default,
+ * every one Kindgi validates), naming it and them.
+ */
+export function jsonSchemaDialect(schema, allowed = ALL_DIALECTS) {
+    const declared = schema.$schema;
+    const dialect = declared === undefined
+        ? '2020-12'
+        : typeof declared === 'string'
+            ? DIALECTS.get(declared.replace(/#$/, ''))
+            : undefined;
+    if (dialect === undefined || !allowed.includes(dialect)) {
+        const where = allowed.length < ALL_DIALECTS.length ? ' here' : '';
+        throw new Error(`The schema's $schema ${JSON.stringify(declared)} isn't a JSON Schema dialect Kindgi validates${where}: ${listOf(allowed)}.`);
+    }
+    return dialect;
+}
+/** `a`, `a or b`, `a, b or c`. */
+function listOf(items) {
+    return items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} or ${items.at(-1)}`;
+}
+/**
+ * A validator for `schema`, compiled in its declared dialect. Throws when
+ * the dialect isn't supported (or allowed) or the schema doesn't compile,
+ * as `ajv.compile` does.
+ */
+export function compileJsonSchema(schema, options = {}) {
+    const dialect = jsonSchemaDialect(schema, options.dialects);
+    const ajvOptions = {
+        strict: options.strict ?? true,
+        allErrors: true,
+        allowUnionTypes: false,
+        ...(options.useDefaults === true && { useDefaults: true }),
+    };
+    let ajv;
+    if (dialect === '2020-12')
+        ajv = new Ajv2020(ajvOptions);
+    else if (dialect === '2019-09')
+        ajv = new Ajv2019(ajvOptions);
+    else {
+        ajv = new Ajv(ajvOptions);
+        if (dialect === 'draft-06') {
+            ajv.addMetaSchema(require('ajv/dist/refs/json-schema-draft-06.json'));
+        }
+    }
+    addFormats(ajv);
+    return ajv.compile(schema);
+}
+//# sourceMappingURL=dialect.js.map

package/dist/dialect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.js","sourceRoot":"","sources":["../src/dialect.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { canonicalize } from './canonical.js';
 export type { InvalidZodConversionError, SchemaCompileError, SchemaError, SchemaLoadError, SchemaNotFoundError, SchemaParseError, ValidationError, } from './errors.js';
 export { compileInlineSchema, createSpecRegistry, loadSpecRegistry } from './registry.js';
+export { compileJsonSchema, jsonSchemaDialect } from './dialect.js';
+export type { CompileJsonSchemaOptions, JsonSchemaDialect } from './dialect.js';
 export type { CompiledInlineSchema, SpecRegistry, ValidationErrorLike } from './registry.js';
 export { versionOf } from './version.js';
 export type { SchemaVersion } from './version.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACV,yBAAyB,EACzB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1F,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACV,yBAAyB,EACzB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACpE,YAAY,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 export { canonicalize } from './canonical.js';
 export { compileInlineSchema, createSpecRegistry, loadSpecRegistry } from './registry.js';
+export { compileJsonSchema, jsonSchemaDialect } from './dialect.js';
 export { versionOf } from './version.js';
 export { isJsonSchemaObject, isZodSchema, loadZodConverter, loadZodConverterSync, parseWithSchema, schemaKindOf, toJSONSchema, toJSONSchemaSync, } from './zod.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAU9C,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE1F,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,gBAAgB,GACjB,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAU9C,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,gBAAgB,GACjB,MAAM,UAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/schema",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "JSON Schema utilities for Kindgi. Loads specs, provides Ajv-based validation, extracts schema versions. Consumers validate incoming data against the wire contracts in @kindgi/specs.",
   "license": "Apache-2.0",
   "repository": {
@@ -18,7 +18,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -29,7 +30,7 @@
     "type-manifest.json"
   ],
   "dependencies": {
-    "@kindgi/types": "0.1.1",
+    "@kindgi/types": "0.1.3",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1"
   },
@@ -42,14 +43,14 @@
     }
   },
   "devDependencies": {
-    "@kindgi/specs": "0.1.1",
+    "@kindgi/specs": "0.1.3",
     "@types/node": "^22.10.5",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8",
     "zod": "^4.6.5"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

package/src/dialect.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Compile a JSON Schema in the dialect it declares (`$schema`). Kindgi's
+ * own schemas are Draft 2020-12, the default when a schema declares none.
+ * A schema from elsewhere (an MCP server: the TypeScript MCP SDK emits
+ * draft-07) means its keywords as its dialect defines them: draft-07's
+ * array-form `items` is a tuple, 2020-12's is not. So each dialect gets
+ * Ajv's class for it, not 2020-12's with another meta-schema added.
+ *
+ * `strict` is Ajv's strict mode, an authoring lint (unknown keywords and
+ * formats, loose tuples, union types): right for the schemas a pack's
+ * author writes, wrong for a schema someone else's server sends, which is
+ * valid JSON Schema without being written to that standard.
+ */
+
+import { createRequire } from 'node:module';
+
+import { Ajv } from 'ajv';
+import type { ValidateFunction } from 'ajv';
+import * as addFormatsModule from 'ajv-formats';
+import { Ajv2019 } from 'ajv/dist/2019.js';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+
+type AnyAjv = Ajv | Ajv2019 | Ajv2020;
+type AddFormatsFn = (ajv: AnyAjv, opts?: unknown) => unknown;
+const addFormatsRaw = addFormatsModule as unknown;
+const addFormats: AddFormatsFn =
+  typeof addFormatsRaw === 'function'
+    ? (addFormatsRaw as AddFormatsFn)
+    : (addFormatsRaw as { default: AddFormatsFn }).default;
+
+const require = createRequire(import.meta.url);
+
+/** The JSON Schema dialects a schema may declare. */
+export type JsonSchemaDialect = 'draft-06' | 'draft-07' | '2019-09' | '2020-12';
+
+const DIALECTS: ReadonlyMap<string, JsonSchemaDialect> = new Map<string, JsonSchemaDialect>([
+  ['http://json-schema.org/draft-06/schema', 'draft-06'],
+  ['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'],
+]);
+
+const ALL_DIALECTS: readonly JsonSchemaDialect[] = [...DIALECTS.values()];
+
+/**
+ * The dialect `schema` declares in `$schema` (2020-12 when it declares
+ * none). Throws for a dialect that isn't one of `allowed` (by default,
+ * every one Kindgi validates), naming it and them.
+ */
+export function jsonSchemaDialect(
+  schema: Readonly<Record<string, unknown>>,
+  allowed: readonly JsonSchemaDialect[] = ALL_DIALECTS,
+): JsonSchemaDialect {
+  const declared = schema.$schema;
+  const dialect =
+    declared === undefined
+      ? '2020-12'
+      : typeof declared === 'string'
+        ? DIALECTS.get(declared.replace(/#$/, ''))
+        : undefined;
+  if (dialect === undefined || !allowed.includes(dialect)) {
+    const where = allowed.length < ALL_DIALECTS.length ? ' here' : '';
+    throw new Error(
+      `The schema's $schema ${JSON.stringify(declared)} isn't a JSON Schema dialect Kindgi validates${where}: ${listOf(allowed)}.`,
+    );
+  }
+  return dialect;
+}
+
+/** `a`, `a or b`, `a, b or c`. */
+function listOf(items: readonly string[]): string {
+  return items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} or ${items.at(-1)}`;
+}
+
+export interface CompileJsonSchemaOptions {
+  /** The dialects the schema may declare. Default: every one Kindgi validates. */
+  readonly dialects?: readonly JsonSchemaDialect[];
+  /** Ajv's strict mode. Default `true`; `false` for a schema from elsewhere (see above). */
+  readonly strict?: boolean;
+  /** Fill in each property's `default` in the data validated (Ajv's `useDefaults`). */
+  readonly useDefaults?: boolean;
+}
+
+/**
+ * A validator for `schema`, compiled in its declared dialect. Throws when
+ * the dialect isn't supported (or allowed) or the schema doesn't compile,
+ * as `ajv.compile` does.
+ */
+export function compileJsonSchema(
+  schema: Readonly<Record<string, unknown>>,
+  options: CompileJsonSchemaOptions = {},
+): ValidateFunction {
+  const dialect = jsonSchemaDialect(schema, options.dialects);
+  const ajvOptions = {
+    strict: options.strict ?? true,
+    allErrors: true,
+    allowUnionTypes: false,
+    ...(options.useDefaults === true && { useDefaults: true }),
+  };
+  let ajv: AnyAjv;
+  if (dialect === '2020-12') ajv = new Ajv2020(ajvOptions);
+  else if (dialect === '2019-09') ajv = new Ajv2019(ajvOptions);
+  else {
+    ajv = new Ajv(ajvOptions);
+    if (dialect === 'draft-06') {
+      ajv.addMetaSchema(require('ajv/dist/refs/json-schema-draft-06.json'));
+    }
+  }
+  addFormats(ajv);
+  return ajv.compile(schema as object);
+}

package/src/index.ts

@@ -12,6 +12,8 @@ export type {
   ValidationError,
 } from './errors.js';
 export { compileInlineSchema, createSpecRegistry, loadSpecRegistry } from './registry.js';
+export { compileJsonSchema, jsonSchemaDialect } from './dialect.js';
+export type { CompileJsonSchemaOptions, JsonSchemaDialect } from './dialect.js';
 export type { CompiledInlineSchema, SpecRegistry, ValidationErrorLike } from './registry.js';
 export { versionOf } from './version.js';
 export type { SchemaVersion } from './version.js';