effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/JsonSchema.js

@@ -2,9 +2,9 @@
  * Helpers for normalizing and converting JSON Schema and OpenAPI schema
  * documents. Supported inputs include JSON Schema Draft-07, Draft 2020-12,
  * OpenAPI 3.0, and OpenAPI 3.1; conversions normalize through
- * `Document<"draft-2020-12">` before emitting another dialect. The module also
- * defines document types, meta-schema constants, OpenAPI component-key helpers,
- * and `$ref` resolution utilities.
+ * `Document<"draft-2020-12">` before emitting another dialect, including
+ * JSON Schema Draft-04. The module also defines document types, meta-schema
+ * constants, OpenAPI component-key helpers, and `$ref` resolution utilities.
  *
  * @since 4.0.0
  */
@@ -13,6 +13,19 @@ import * as InternalRecord from "./internal/record.js";
 import { unescapeToken } from "./JsonPointer.js";
 import * as Predicate from "./Predicate.js";
 import * as Rec from "./Record.js";
+/**
+ * Represents the `$schema` meta-schema URI for JSON Schema Draft-04.
+ *
+ * **When to use**
+ *
+ * Use when constructing a Draft-04 JSON Schema document and you need a stable
+ * value for the root `$schema` field.
+ *
+ * @see {@link META_SCHEMA_URI_DRAFT_07} for the Draft-07 `$schema` URI
+ * @category constants
+ * @since 4.0.0
+ */
+export const META_SCHEMA_URI_DRAFT_04 = "http://json-schema.org/draft-04/schema#";
 /**
  * Represents the `$schema` meta-schema URI for JSON Schema Draft-07.
  *
@@ -24,14 +37,15 @@ import * as Rec from "./Record.js";
  * **Details**
  *
  * The exported value is the literal string
- * `http://json-schema.org/draft-07/schema`.
+ * `http://json-schema.org/draft-07/schema#`.
  *
+ * @see {@link META_SCHEMA_URI_DRAFT_04} for the Draft-04 `$schema` URI
  * @see {@link META_SCHEMA_URI_DRAFT_2020_12} for the Draft 2020-12 `$schema` URI
  *
  * @category constants
  * @since 4.0.0
  */
-export const META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema";
+export const META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema#";
 /**
  * Represents the `$schema` meta-schema URI for JSON Schema Draft 2020-12.
  *
@@ -54,6 +68,15 @@ export const META_SCHEMA_URI_DRAFT_2020_12 = "https://json-schema.org/draft/2020
 const RE_DEFINITIONS = /^#\/definitions(?=\/|$)/;
 const RE_DEFS = /^#\/\$defs(?=\/|$)/;
 const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/;
+const DRAFT_04_COPY_KEYWORDS = /*#__PURE__*/new Set(["$ref", "type", "required", "enum", "title", "description", "default", "format", "pattern", "minLength", "maxLength", "minItems", "maxItems", "minProperties", "maxProperties", "multipleOf", "uniqueItems"]);
+const DRAFT_07_COPY_KEYWORDS = /*#__PURE__*/new Set([...DRAFT_04_COPY_KEYWORDS, "const", "examples", "readOnly", "writeOnly", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"]);
+const DRAFT_04_SINGLE_SUBSCHEMA_KEYWORDS = /*#__PURE__*/new Set(["not"]);
+const DRAFT_07_SINGLE_SUBSCHEMA_KEYWORDS = /*#__PURE__*/new Set(["not", "additionalProperties", "propertyNames"]);
+const MAP_SUBSCHEMA_KEYWORDS = /*#__PURE__*/new Set(["properties", "patternProperties"]);
+const ARRAY_SUBSCHEMA_KEYWORDS = /*#__PURE__*/new Set(["allOf", "anyOf", "oneOf"]);
+const DRAFT_2020_12_MAP_SUBSCHEMA_KEYWORDS = /*#__PURE__*/new Set(["$defs", ...MAP_SUBSCHEMA_KEYWORDS, "dependentSchemas"]);
+const DRAFT_2020_12_ARRAY_SUBSCHEMA_KEYWORDS = /*#__PURE__*/new Set([...ARRAY_SUBSCHEMA_KEYWORDS, "prefixItems"]);
+const DRAFT_2020_12_SINGLE_SUBSCHEMA_KEYWORDS = /*#__PURE__*/new Set([...DRAFT_07_SINGLE_SUBSCHEMA_KEYWORDS, "unevaluatedProperties", "items", "contains", "unevaluatedItems", "if", "then", "else", "contentSchema"]);
 /**
  * Parses a raw Draft-07 JSON Schema into a `Document<"draft-2020-12">`.
  *
@@ -75,7 +98,7 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/;
  *
  * **Example** (Parsing a Draft-07 schema)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { JsonSchema } from "effect"
  *
  * const raw: JsonSchema.JsonSchema = {
@@ -89,8 +112,8 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/;
  * }
  *
  * const doc = JsonSchema.fromSchemaDraft07(raw)
- * console.log(doc.dialect) // "draft-2020-12"
- * console.log(doc.schema.properties) // { tags: { type: "array", items: { type: "string" } } }
+ * doc.dialect // => "draft-2020-12"
+ * doc.schema.properties // => { tags: { type: "array", items: { type: "string" } } }
  * ```
  *
  * @see {@link fromSchemaDraft2020_12}
@@ -108,20 +131,26 @@ export function fromSchemaDraft07(js) {
     definitions: definitions ?? {}
   };
   function walk(node, isRoot) {
-    if (Array.isArray(node)) return node.map(v => walk(v, false));
+    if (Array.isArray(node)) return node.map(walkNested);
     if (!Predicate.isObject(node)) return node;
     const out = {};
     let prefixItems = undefined;
     let additionalItems = undefined;
     for (const k of Object.keys(node)) {
       const v = node[k];
+      if (k === "$ref") {
+        out.$ref = typeof v === "string" ? v.replace(RE_DEFINITIONS, "#/$defs") : v;
+        continue;
+      }
+      if (DRAFT_07_COPY_KEYWORDS.has(k)) {
+        out[k] = v;
+        continue;
+      }
+      if (rewriteSubschemaKeyword(out, k, v, walkNested, DRAFT_07_SINGLE_SUBSCHEMA_KEYWORDS)) continue;
       switch (k) {
-        case "$ref":
-          out.$ref = typeof v === "string" ? v.replace(RE_DEFINITIONS, "#/$defs") : v;
-          break;
         case "definitions":
           {
-            const mapped = walk_object(v, walk);
+            const mapped = mapObject(v, walkNested);
             if (isRoot) {
               definitions = mapped;
             } else {
@@ -135,48 +164,6 @@ export function fromSchemaDraft07(js) {
         case "additionalItems":
           additionalItems = v;
           break;
-        case "properties":
-        case "patternProperties":
-          {
-            const mapped = walk_object(v, walk);
-            out[k] = mapped ?? v;
-            break;
-          }
-        case "additionalProperties":
-        case "propertyNames":
-          out[k] = walk(v, false);
-          break;
-        case "allOf":
-        case "anyOf":
-        case "oneOf":
-          out[k] = Array.isArray(v) ? v.map(x => walk(x, false)) : v;
-          break;
-        case "type":
-        case "required":
-        case "enum":
-        case "const":
-        case "title":
-        case "description":
-        case "default":
-        case "examples":
-        case "format":
-        case "readOnly":
-        case "writeOnly":
-        case "pattern":
-        case "minimum":
-        case "maximum":
-        case "exclusiveMinimum":
-        case "exclusiveMaximum":
-        case "minLength":
-        case "maxLength":
-        case "minItems":
-        case "maxItems":
-        case "minProperties":
-        case "maxProperties":
-        case "multipleOf":
-        case "uniqueItems":
-          out[k] = v;
-          break;
         default:
           break;
       }
@@ -184,14 +171,17 @@ export function fromSchemaDraft07(js) {
     // Draft-07 tuples -> 2020-12 tuples
     if (prefixItems !== undefined) {
       if (Array.isArray(prefixItems)) {
-        out.prefixItems = prefixItems.map(x => walk(x, false));
-        if (additionalItems !== undefined) out.items = walk(additionalItems, false);
+        out.prefixItems = prefixItems.map(walkNested);
+        if (additionalItems !== undefined) out.items = walkNested(additionalItems);
       } else {
-        out.items = walk(prefixItems, false);
+        out.items = walkNested(prefixItems);
       }
     }
     return out;
   }
+  function walkNested(node) {
+    return walk(node, false);
+  }
 }
 /**
  * Parses a raw Draft-2020-12 JSON Schema into a `Document<"draft-2020-12">`.
@@ -207,7 +197,7 @@ export function fromSchemaDraft07(js) {
  *
  * **Example** (Parsing a Draft-2020-12 schema)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { JsonSchema } from "effect"
  *
  * const raw: JsonSchema.JsonSchema = {
@@ -217,8 +207,8 @@ export function fromSchemaDraft07(js) {
  * }
  *
  * const doc = JsonSchema.fromSchemaDraft2020_12(raw)
- * console.log(doc.schema)      // { type: "number", minimum: 0 }
- * console.log(doc.definitions) // { PositiveInt: { type: "integer", minimum: 1 } }
+ * doc.schema // => { type: "number", minimum: 0 }
+ * doc.definitions // => { PositiveInt: { type: "integer", minimum: 1 } }
  * ```
  *
  * @see {@link fromSchemaDraft07}
@@ -252,7 +242,7 @@ export function fromSchemaDraft2020_12(js) {
  *
  * **Example** (Parsing an OpenAPI 3.1 schema)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { JsonSchema } from "effect"
  *
  * const raw: JsonSchema.JsonSchema = {
@@ -263,8 +253,7 @@ export function fromSchemaDraft2020_12(js) {
  * }
  *
  * const doc = JsonSchema.fromSchemaOpenApi3_1(raw)
- * // $ref is rewritten to Draft-2020-12 form
- * console.log(doc.schema.properties) // { user: { $ref: "#/$defs/User" } }
+ * doc.schema.properties // => { user: { $ref: "#/$defs/User" } }
  * ```
  *
  * @see {@link fromSchemaOpenApi3_0}
@@ -273,7 +262,7 @@ export function fromSchemaDraft2020_12(js) {
  * @since 4.0.0
  */
 export function fromSchemaOpenApi3_1(js) {
-  const schema = rewrite_refs(js, ref => ref.replace(RE_COMPONENTS_SCHEMAS, "#/$defs"));
+  const schema = transformSchema(js, schema => rewriteSchemaRef(schema, ref => ref.replace(RE_COMPONENTS_SCHEMAS, "#/$defs")));
   return fromSchemaDraft2020_12(schema);
 }
 /**
@@ -293,7 +282,7 @@ export function fromSchemaOpenApi3_1(js) {
  *
  * **Example** (Parsing an OpenAPI 3.0 nullable schema)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { JsonSchema } from "effect"
  *
  * const raw: JsonSchema.JsonSchema = {
@@ -302,8 +291,7 @@ export function fromSchemaOpenApi3_1(js) {
  * }
  *
  * const doc = JsonSchema.fromSchemaOpenApi3_0(raw)
- * // nullable is expanded into a type array
- * console.log(doc.schema.type) // ["string", "null"]
+ * doc.schema.type // => ["string", "null"]
  * ```
  *
  * @see {@link fromSchemaOpenApi3_1}
@@ -312,7 +300,7 @@ export function fromSchemaOpenApi3_1(js) {
  * @since 4.0.0
  */
 export function fromSchemaOpenApi3_0(schema) {
-  const normalized = normalize_OpenApi3_0_to_Draft07(schema);
+  const normalized = normalizeOpenApi3_0ToDraft07(schema);
   return fromSchemaDraft07(normalized);
 }
 /**
@@ -336,7 +324,7 @@ export function fromSchemaOpenApi3_0(schema) {
  *
  * **Example** (Converting to Draft-07)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { JsonSchema } from "effect"
  *
  * const doc = JsonSchema.fromSchemaDraft2020_12({
@@ -346,12 +334,13 @@ export function fromSchemaOpenApi3_0(schema) {
  * })
  *
  * const draft07 = JsonSchema.toDocumentDraft07(doc)
- * console.log(draft07.dialect)                // "draft-07"
- * console.log(draft07.schema.items)           // [{ type: "string" }, { type: "number" }]
- * console.log(draft07.schema.additionalItems) // { type: "boolean" }
+ * draft07.dialect // => "draft-07"
+ * draft07.schema.items // => [{ type: "string" }, { type: "number" }]
+ * draft07.schema.additionalItems // => { type: "boolean" }
  * ```
  *
  * @see {@link fromSchemaDraft07}
+ * @see {@link toDocumentDraft04} for converting to Draft-04
  * @see {@link toMultiDocumentOpenApi3_1}
  * @category encoding
  * @since 4.0.0
@@ -363,66 +352,138 @@ export function toDocumentDraft07(document) {
     definitions: Rec.map(document.definitions, toSchemaDraft07)
   };
 }
-function toSchemaDraft07(schema) {
-  return rewrite(schema);
-  function rewrite(node) {
-    return walk(rewrite_refs(node, ref => ref.replace(RE_DEFS, "#/definitions")), true);
-  }
-  function walk(node, _isRoot) {
-    if (Array.isArray(node)) return node.map(v => walk(v, false));
+/**
+ * Converts a `Document<"draft-2020-12">` to a `Document<"draft-04">`.
+ *
+ * **When to use**
+ *
+ * Use when you need to output a canonical JSON Schema document in Draft-04
+ * format.
+ *
+ * **Details**
+ *
+ * This rewrites `#/$defs/...` refs to `#/definitions/...`, converts tuple
+ * syntax, lowers `const` to `enum`, converts numeric exclusive bounds to the
+ * Draft-04 boolean form, and converts both the root schema and all definitions.
+ *
+ * **Gotchas**
+ *
+ * Unsupported Draft-2020-12 and Draft-07 keywords are dropped. For example,
+ * `propertyNames` has no general Draft-04 equivalent and is omitted.
+ *
+ * **Example** (Converting exclusive bounds)
+ *
+ * ```ts import.meta.vitest
+ * import { JsonSchema } from "effect"
+ *
+ * const doc = JsonSchema.fromSchemaDraft2020_12({
+ *   type: "number",
+ *   exclusiveMinimum: 0
+ * })
+ *
+ * JsonSchema.toDocumentDraft04(doc).schema // => { type: "number", minimum: 0, exclusiveMinimum: true }
+ * ```
+ *
+ * @see {@link toDocumentDraft07} for converting to Draft-07
+ * @category encoding
+ * @since 4.0.0
+ */
+export function toDocumentDraft04(document) {
+  const draft07 = toDocumentDraft07(document);
+  return {
+    dialect: "draft-04",
+    schema: toSchemaDraft04(draft07.schema),
+    definitions: Rec.map(draft07.definitions, toSchemaDraft04)
+  };
+}
+function toSchemaDraft04(schema) {
+  return walk(schema);
+  function walk(node) {
+    if (node === true) return {};
+    if (node === false) return {
+      not: {}
+    };
+    if (Array.isArray(node)) return node.map(walk);
     if (!Predicate.isObject(node)) return node;
     const src = node;
     const out = {};
-    let prefixItems = undefined;
-    let items = undefined;
+    let hasConst = false;
+    let constValue = undefined;
     for (const k of Object.keys(src)) {
       const v = src[k];
+      if (DRAFT_04_COPY_KEYWORDS.has(k)) {
+        out[k] = v;
+        continue;
+      }
+      if (rewriteSubschemaKeyword(out, k, v, walk, DRAFT_04_SINGLE_SUBSCHEMA_KEYWORDS)) continue;
       switch (k) {
-        // We already rewrote $ref via rewrite_refs, so just copy it through.
-        case "$ref":
-        case "type":
-        case "required":
-        case "enum":
         case "const":
-        case "title":
-        case "description":
-        case "default":
-        case "examples":
-        case "format":
-        case "pattern":
+          hasConst = true;
+          constValue = v;
+          break;
         case "minimum":
         case "maximum":
         case "exclusiveMinimum":
         case "exclusiveMaximum":
-        case "minLength":
-        case "maxLength":
-        case "minItems":
-        case "maxItems":
-        case "minProperties":
-        case "maxProperties":
-        case "multipleOf":
-        case "uniqueItems":
-          out[k] = v;
           break;
-        // Schema maps
-        case "properties":
-        case "patternProperties":
-          {
-            const mapped = walk_object(v, walk);
-            out[k] = mapped ?? v;
-            break;
-          }
-        // Single subschemas
         case "additionalProperties":
-        case "propertyNames":
-          out[k] = walk(v, false);
+        case "additionalItems":
+          out[k] = typeof v === "boolean" ? v : walk(v);
+          break;
+        case "items":
+          out.items = Array.isArray(v) ? v.map(walk) : walk(v);
           break;
-        // Schema arrays
-        case "allOf":
-        case "anyOf":
-        case "oneOf":
-          out[k] = Array.isArray(v) ? v.map(x => walk(x, false)) : v;
+        default:
           break;
+      }
+    }
+    convertExclusiveBound(src, out, "minimum", "exclusiveMinimum", (bound, exclusive) => bound > exclusive);
+    convertExclusiveBound(src, out, "maximum", "exclusiveMaximum", (bound, exclusive) => bound < exclusive);
+    if (hasConst) {
+      const constSchema = {
+        enum: [constValue]
+      };
+      if (Object.hasOwn(src, "enum")) {
+        out.allOf = Array.isArray(out.allOf) ? [...out.allOf, constSchema] : [constSchema];
+      } else {
+        out.enum = constSchema.enum;
+      }
+    }
+    return out;
+  }
+}
+function convertExclusiveBound(src, out, boundKey, exclusiveKey, isBoundStricter) {
+  const bound = src[boundKey];
+  const exclusive = src[exclusiveKey];
+  if (typeof exclusive === "number") {
+    if (typeof bound === "number" && isBoundStricter(bound, exclusive)) {
+      out[boundKey] = bound;
+    } else {
+      out[boundKey] = exclusive;
+      out[exclusiveKey] = true;
+    }
+  } else if (bound !== undefined) {
+    out[boundKey] = bound;
+  }
+}
+function toSchemaDraft07(schema) {
+  return transformSchema(schema, src => {
+    rewriteSchemaRef(src, ref => ref.replace(RE_DEFS, "#/definitions"));
+    const out = {};
+    let prefixItems = undefined;
+    let items = undefined;
+    for (const k of Object.keys(src)) {
+      const v = src[k];
+      if (k === "required" && Array.isArray(v) && v.length === 0) continue;
+      if (DRAFT_07_COPY_KEYWORDS.has(k)) {
+        out[k] = v;
+        continue;
+      }
+      if (MAP_SUBSCHEMA_KEYWORDS.has(k) || ARRAY_SUBSCHEMA_KEYWORDS.has(k) || DRAFT_07_SINGLE_SUBSCHEMA_KEYWORDS.has(k)) {
+        out[k] = v;
+        continue;
+      }
+      switch (k) {
         // Tuple handling (2020-12 form)
         case "prefixItems":
           prefixItems = v;
@@ -438,18 +499,25 @@ function toSchemaDraft07(schema) {
     // 2020-12 tuples -> Draft-07 tuples
     if (prefixItems !== undefined) {
       if (Array.isArray(prefixItems)) {
-        out.items = prefixItems.map(x => walk(x, false));
-        if (items !== undefined) out.additionalItems = walk(items, false);
+        out.items = prefixItems;
+        if (items !== undefined) out.additionalItems = items;
       } else {
         // Non-standard, but keep a reasonable behavior
-        out.items = walk(prefixItems, false);
+        out.items = prefixItems;
       }
     } else if (items !== undefined) {
       // Regular items schema stays as items
-      out.items = walk(items, false);
+      out.items = items;
+    }
+    const $ref = out.$ref;
+    if (typeof $ref === "string" && Object.keys(out).length > 1) {
+      delete out.$ref;
+      out.allOf = [{
+        $ref
+      }, ...(Array.isArray(out.allOf) ? out.allOf : [])];
     }
     return out;
-  }
+  });
 }
 /**
  * Converts a `MultiDocument<"draft-2020-12">` to a
@@ -462,15 +530,21 @@ function toSchemaDraft07(schema) {
  *
  * **Details**
  *
- * This rewrites `#/$defs/...` refs to `#/components/schemas/...`, sanitizes
- * definition keys to match the OpenAPI component key pattern
- * (`^[a-zA-Z0-9.\-_]+$`) by replacing invalid characters with `_`, updates all
- * `$ref` pointers to use the sanitized keys, and converts all schemas and
- * definitions in the multi-document.
+ * This rewrites local `#/$defs/...` refs to `#/components/schemas/...` and
+ * sanitizes definition keys to match the OpenAPI component key pattern
+ * (`^[a-zA-Z0-9.\-_]+$`) by replacing invalid characters with `_`. Valid keys
+ * are preserved. When sanitized keys collide, the converter appends the first
+ * available `_1`, `_2`, and subsequent suffix, with allocation independent of
+ * definition insertion order. All local refs are updated to use the allocated
+ * keys, including refs to paths within a definition.
+ *
+ * **Gotchas**
+ *
+ * External refs and local refs outside `#/$defs` are left unchanged.
  *
  * **Example** (Converting to OpenAPI 3.1)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { JsonSchema } from "effect"
  *
  * const multi: JsonSchema.MultiDocument<"draft-2020-12"> = {
@@ -482,8 +556,8 @@ function toSchemaDraft07(schema) {
  * }
  *
  * const openapi = JsonSchema.toMultiDocumentOpenApi3_1(multi)
- * console.log(openapi.dialect) // "openapi-3.1"
- * console.log(openapi.schemas[0]) // { $ref: "#/components/schemas/User" }
+ * openapi.dialect // => "openapi-3.1"
+ * openapi.schemas[0] // => { $ref: "#/components/schemas/User" }
  * ```
  *
  * @see {@link toDocumentDraft07}
@@ -492,25 +566,33 @@ function toSchemaDraft07(schema) {
  * @since 4.0.0
  */
 export function toMultiDocumentOpenApi3_1(multiDocument) {
+  const definitionKeys = Object.keys(multiDocument.definitions);
   const keyMap = new Map();
-  for (const key of Object.keys(multiDocument.definitions)) {
-    const sanitized = sanitizeOpenApiComponentsSchemasKey(key);
-    if (sanitized !== key) {
-      keyMap.set(key, sanitized);
-    }
+  const usedKeys = new Set(definitionKeys.filter(key => VALID_OPEN_API_COMPONENTS_SCHEMAS_KEY_REGEXP.test(key)));
+  const invalidKeys = definitionKeys.filter(key => !VALID_OPEN_API_COMPONENTS_SCHEMAS_KEY_REGEXP.test(key)).sort().map(key => [key, sanitizeOpenApiComponentsSchemasKey(key)]);
+  for (const [key, base] of invalidKeys) {
+    if (usedKeys.has(base)) continue;
+    usedKeys.add(base);
+    keyMap.set(key, base);
+  }
+  for (const [key, base] of invalidKeys) {
+    if (keyMap.has(key)) continue;
+    let candidate;
+    let suffix = 0;
+    do candidate = `${base}_${++suffix}`; while (usedKeys.has(candidate));
+    usedKeys.add(candidate);
+    keyMap.set(key, candidate);
   }
   function rewrite(schema) {
-    return rewrite_refs(schema, $ref => {
-      const tokens = $ref.split("/");
-      if (tokens.length > 0) {
-        const identifier = unescapeToken(tokens[tokens.length - 1]);
-        const sanitized = keyMap.get(identifier);
-        if (sanitized !== undefined) {
-          $ref = tokens.slice(0, -1).join("/") + "/" + sanitized;
-        }
-      }
-      return $ref.replace(RE_DEFS, "#/components/schemas");
-    });
+    return transformSchema(schema, schema => rewriteSchemaRef(schema, $ref => {
+      if (!$ref.startsWith("#/$defs/")) return $ref;
+      const path = $ref.slice("#/$defs/".length);
+      const separatorIndex = path.indexOf("/");
+      const token = separatorIndex === -1 ? path : path.slice(0, separatorIndex);
+      const rest = separatorIndex === -1 ? "" : path.slice(separatorIndex);
+      const key = keyMap.get(unescapeToken(token)) ?? token;
+      return `#/components/schemas/${key}${rest}`;
+    }));
   }
   return {
     dialect: "openapi-3.1",
@@ -527,54 +609,55 @@ export const VALID_OPEN_API_COMPONENTS_SCHEMAS_KEY_REGEXP = /^[a-zA-Z0-9.\-_]+$/
  * @internal
  */
 export function sanitizeOpenApiComponentsSchemasKey(s) {
-  if (s.length === 0) return "_";
-  if (VALID_OPEN_API_COMPONENTS_SCHEMAS_KEY_REGEXP.test(s)) return s;
-  const out = [];
-  for (const ch of s) {
-    const code = ch.codePointAt(0);
-    if (code !== undefined && (code >= 48 && code <= 57 ||
-    // 0-9
-    code >= 65 && code <= 90 ||
-    // A-Z
-    code >= 97 && code <= 122 ||
-    // a-z
-    code === 46 ||
-    // .
-    code === 45 ||
-    // -
-    code === 95) // _
-    ) {
-      out.push(ch);
-    } else {
-      out.push("_");
+  return s.length === 0 ? "_" : s.replace(/[^a-zA-Z0-9._-]/gu, "_");
+}
+function transformSchema(node, transform) {
+  return walk(node);
+  function walk(node) {
+    if (!Predicate.isObject(node) || Array.isArray(node)) return node;
+    const out = {};
+    for (const key of Object.keys(node)) {
+      const value = node[key];
+      let transformed = value;
+      if (DRAFT_2020_12_MAP_SUBSCHEMA_KEYWORDS.has(key)) {
+        transformed = Array.isArray(value) ? value : mapObject(value, walk) ?? value;
+      } else if (DRAFT_2020_12_ARRAY_SUBSCHEMA_KEYWORDS.has(key)) {
+        transformed = Array.isArray(value) ? value.map(walk) : value;
+      } else if (DRAFT_2020_12_SINGLE_SUBSCHEMA_KEYWORDS.has(key)) {
+        transformed = walk(value);
+      }
+      InternalRecord.assignProperty(out, key, transformed);
     }
+    return transform(out);
   }
-  return out.join("");
 }
-function rewrite_refs(node, f) {
-  if (Array.isArray(node)) return node.map(v => rewrite_refs(v, f));
-  if (!Predicate.isObject(node)) return node;
-  const out = {};
-  for (const k of Object.keys(node)) {
-    const v = node[k];
-    if (k === "$ref") {
-      InternalRecord.assignProperty(out, k, typeof v === "string" ? f(v) : v);
-    } else if (Array.isArray(v) || Predicate.isObject(v)) {
-      InternalRecord.assignProperty(out, k, rewrite_refs(v, f));
-    } else {
-      InternalRecord.assignProperty(out, k, v);
-    }
+function rewriteSchemaRef(schema, rewrite) {
+  if (typeof schema.$ref === "string") {
+    InternalRecord.assignProperty(schema, "$ref", rewrite(schema.$ref));
   }
-  return out;
+  return schema;
 }
-function walk_object(value, walk) {
+function mapObject(value, f) {
   if (!Predicate.isObject(value)) return undefined;
   const out = {};
-  for (const k of Object.keys(value)) InternalRecord.assignProperty(out, k, walk(value[k], false));
+  for (const k of Object.keys(value)) InternalRecord.assignProperty(out, k, f(value[k]));
   return out;
 }
-function normalize_OpenApi3_0_to_Draft07(node) {
-  if (Array.isArray(node)) return node.map(normalize_OpenApi3_0_to_Draft07);
+function rewriteSubschemaKeyword(out, key, value, rewrite, singleKeywords) {
+  if (MAP_SUBSCHEMA_KEYWORDS.has(key)) {
+    out[key] = mapObject(value, rewrite) ?? value;
+    return true;
+  }
+  if (ARRAY_SUBSCHEMA_KEYWORDS.has(key)) {
+    out[key] = Array.isArray(value) ? value.map(rewrite) : value;
+    return true;
+  }
+  if (!singleKeywords.has(key)) return false;
+  out[key] = rewrite(value);
+  return true;
+}
+function normalizeOpenApi3_0ToDraft07(node) {
+  if (Array.isArray(node)) return node.map(normalizeOpenApi3_0ToDraft07);
   if (!Predicate.isObject(node)) return node;
   const src = node;
   let out = {};
@@ -587,62 +670,47 @@ function normalize_OpenApi3_0_to_Draft07(node) {
         out.examples = [v];
       }
     } else if (Array.isArray(v) || Predicate.isObject(v)) {
-      InternalRecord.assignProperty(out, k, normalize_OpenApi3_0_to_Draft07(v));
+      InternalRecord.assignProperty(out, k, normalizeOpenApi3_0ToDraft07(v));
     } else {
       InternalRecord.assignProperty(out, k, v);
     }
   }
   // Draft-04-style numeric exclusivity booleans
-  out = adjust_exclusivity(out);
+  out = adjustExclusivity(out);
   // OpenAPI 3.0 nullable
   if (out.nullable === true) {
-    out = apply_nullable(out);
+    out = applyNullable(out);
   }
   delete out.nullable;
   return out;
 }
-function adjust_exclusivity(node) {
-  let out = node;
-  if (typeof out.exclusiveMinimum === "boolean") {
-    if (out.exclusiveMinimum === true && typeof out.minimum === "number") {
-      out = {
-        ...out,
-        exclusiveMinimum: out.minimum
-      };
-      delete out.minimum;
-    } else {
-      out = {
-        ...out
-      };
-      delete out.exclusiveMinimum;
-    }
-  }
-  if (typeof out.exclusiveMaximum === "boolean") {
-    if (out.exclusiveMaximum === true && typeof out.maximum === "number") {
-      out = {
-        ...out,
-        exclusiveMaximum: out.maximum
-      };
-      delete out.maximum;
-    } else {
-      out = {
-        ...out
-      };
-      delete out.exclusiveMaximum;
-    }
+function adjustExclusivity(node) {
+  return adjustExclusiveBound(adjustExclusiveBound(node, "minimum", "exclusiveMinimum"), "maximum", "exclusiveMaximum");
+}
+function adjustExclusiveBound(node, boundKey, exclusiveKey) {
+  const exclusive = node[exclusiveKey];
+  if (typeof exclusive !== "boolean") return node;
+  const out = {
+    ...node
+  };
+  if (exclusive && typeof node[boundKey] === "number") {
+    out[exclusiveKey] = node[boundKey];
+    delete out[boundKey];
+  } else {
+    delete out[exclusiveKey];
   }
   return out;
 }
-function apply_nullable(node) {
+function applyNullable(node) {
   // enum widening
   if (Array.isArray(node.enum)) {
-    return widen_type({
+    return widenType({
       ...node,
       enum: node.enum.includes(null) ? node.enum : [...node.enum, null]
     });
   }
   // type widening
-  if (node.type !== undefined) return widen_type(node);
+  if (node.type !== undefined) return widenType(node);
   // const === null
   if (node.const === null) return node;
   // fallback
@@ -652,7 +720,7 @@ function apply_nullable(node) {
     }]
   };
 }
-function widen_type(node) {
+function widenType(node) {
   const t = node.type;
   if (typeof t === "string") return t === "null" ? node : {
     ...node,
@@ -684,18 +752,15 @@ function widen_type(node) {
  *
  * **Example** (Resolving a $ref)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { JsonSchema } from "effect"
  *
  * const definitions: JsonSchema.Definitions = {
  *   User: { type: "object", properties: { name: { type: "string" } } }
  * }
  *
- * const result = JsonSchema.resolve$ref("#/$defs/User", definitions)
- * console.log(result) // { type: "object", properties: { name: { type: "string" } } }
- *
- * const missing = JsonSchema.resolve$ref("#/$defs/Unknown", definitions)
- * console.log(missing) // undefined
+ * JsonSchema.resolve$ref("#/$defs/User", definitions) // => { type: "object", properties: { name: { type: "string" } } }
+ * JsonSchema.resolve$ref("#/$defs/Unknown", definitions) // => undefined
  * ```
  *
  * @see {@link resolveTopLevel$ref}
@@ -705,10 +770,8 @@ function widen_type(node) {
  */
 export function resolve$ref($ref, definitions) {
   const tokens = $ref.split("/");
-  if (tokens.length > 0) {
-    const identifier = unescapeToken(tokens[tokens.length - 1]);
-    if (Object.hasOwn(definitions, identifier)) return definitions[identifier];
-  }
+  const identifier = unescapeToken(tokens[tokens.length - 1]);
+  if (Object.hasOwn(definitions, identifier)) return definitions[identifier];
 }
 /**
  * Resolves a document whose root schema is a top-level `$ref`.
@@ -725,7 +788,7 @@ export function resolve$ref($ref, definitions) {
  *
  * **Example** (Resolving a top-level $ref)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { JsonSchema } from "effect"
  *
  * const doc: JsonSchema.Document<"draft-2020-12"> = {
@@ -737,7 +800,7 @@ export function resolve$ref($ref, definitions) {
  * }
  *
  * const resolved = JsonSchema.resolveTopLevel$ref(doc)
- * console.log(resolved.schema) // { type: "object", properties: { name: { type: "string" } } }
+ * resolved.schema // => { type: "object", properties: { name: { type: "string" } } }
  * ```
  *
  * @see {@link resolve$ref}