effect 4.0.0-rc.113 → 4.0.0-rc.115

package/dist/internal/schema/fromJsonSchemaDocument.js

@@ -16,16 +16,23 @@ const string = {
   _tag: "String",
   checks: []
 };
-function makeJsonLiteral(input) {
+const unsupportedStructuredValue = "Only primitive values are supported in \"const\" and \"enum\".";
+function isObject(input) {
+  return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function makeJsonLiteral(input, path) {
   if (input === null) return {
     _tag: "Null",
     checks: []
   };
-  return typeof input === "string" || typeof input === "number" || typeof input === "boolean" ? {
-    _tag: "Literal",
-    literal: input,
-    checks: []
-  } : undefined;
+  if (typeof input === "string" || typeof input === "number" || typeof input === "boolean") {
+    return {
+      _tag: "Literal",
+      literal: input,
+      checks: []
+    };
+  }
+  if (typeof input === "object") throw errorWithPath(unsupportedStructuredValue, path);
 }
 const jsonSchemaValueTypes = ["null", "string", "number", "boolean", "object", "array"];
 const jsonSchemaTypeSpecificKeys = ["minLength", "maxLength", "pattern", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "properties", "required", "additionalProperties", "patternProperties", "propertyNames", "minProperties", "maxProperties", "items", "prefixItems", "minItems", "maxItems", "uniqueItems"];
@@ -84,66 +91,77 @@ function jsonDeclaration(annotations) {
     typeParameters: []
   };
 }
-function unknownJsonSchemas(representation) {
-  switch (representation._tag) {
-    case "Unknown":
-      return jsonDeclaration(representation.annotations);
-    case "Suspend":
-      return {
-        ...representation,
-        thunk: unknownJsonSchemas(representation.thunk)
-      };
-    case "Arrays":
-      return {
-        ...representation,
-        elements: representation.elements.map(element => ({
-          ...element,
-          type: unknownJsonSchemas(element.type)
-        })),
-        rest: representation.rest.map(unknownJsonSchemas)
-      };
-    case "Objects":
-      return {
-        ...representation,
-        propertySignatures: representation.propertySignatures.map(property => ({
-          ...property,
-          type: unknownJsonSchemas(property.type)
-        })),
-        indexSignatures: representation.indexSignatures.map(indexSignature => ({
-          parameter: unknownJsonSchemas(indexSignature.parameter),
-          type: unknownJsonSchemas(indexSignature.type)
-        })),
-        checks: representation.checks.map(unknownJsonSchemaCheck)
-      };
-    case "Union":
-      return {
-        ...representation,
-        types: representation.types.map(unknownJsonSchemas)
-      };
-    default:
-      return representation;
-  }
-}
-function unknownJsonSchemaCheck(check) {
-  const representation = check.representation;
-  const schemas = representation?.schemas;
-  if (representation === undefined || schemas === undefined) {
-    return check;
-  }
-  return {
-    ...check,
-    representation: {
-      ...representation,
-      schemas: schemas.map(unknownJsonSchemas)
-    }
-  };
-}
 function translateJsonSchemaMultiDocument(document, options, singleRoot = false) {
   const definitionCache = new Map();
   const reachableDefinitions = new Map();
   const objectScopesByProperties = new WeakMap();
   const annotatedReferences = [];
   const resolvingChoices = new Set();
+  const finalReferences = new Set();
+  let inNestedResource = false;
+  function finalize(representation) {
+    switch (representation._tag) {
+      case "Unknown":
+        return jsonDeclaration(representation.annotations);
+      case "Reference":
+        finalReferences.add(representation.$ref);
+        return representation;
+      case "Suspend":
+        return {
+          ...representation,
+          thunk: finalize(representation.thunk)
+        };
+      case "Arrays":
+        return {
+          ...representation,
+          elements: representation.elements.map(element => ({
+            ...element,
+            type: finalize(element.type)
+          })),
+          rest: representation.rest.map(finalize)
+        };
+      case "Objects":
+        // Intersections may reduce open patterns to fixed properties, so reject only
+        // if an open pattern remains in the final representation.
+        const [scopes, path] = objectScopesByProperties.get(representation.propertySignatures);
+        if (representation.indexSignatures[0]?.parameter === string && scopes.some(scope => scope.patterns.length > 0)) {
+          throw errorWithPath("Cannot import open \"patternProperties\": unmatched keys cannot be typed correctly.", path);
+        }
+        return {
+          ...representation,
+          propertySignatures: representation.propertySignatures.map(property => ({
+            ...property,
+            type: finalize(property.type)
+          })),
+          indexSignatures: representation.indexSignatures.map(indexSignature => ({
+            parameter: finalize(indexSignature.parameter),
+            type: finalize(indexSignature.type)
+          })),
+          checks: representation.checks.map(finalizeCheck)
+        };
+      case "Union":
+        return {
+          ...representation,
+          types: representation.types.map(finalize)
+        };
+      default:
+        return representation;
+    }
+  }
+  function finalizeCheck(check) {
+    const representation = check.representation;
+    const schemas = representation?.schemas;
+    if (representation === undefined || schemas === undefined) {
+      return check;
+    }
+    return {
+      ...check,
+      representation: {
+        ...representation,
+        schemas: schemas.map(finalize)
+      }
+    };
+  }
   function annotate(representation, annotations) {
     if (annotations === undefined) return representation;
     if (representation._tag === "Reference") {
@@ -166,29 +184,26 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     const cached = definitionCache.get(key);
     if (cached !== undefined) {
       if (cached === null) {
-        throw errorWithPath(recursiveReferenceError ?? `Invalid reference ${key}`, [...path, "$ref"]);
+        throw errorWithPath(recursiveReferenceError ?? `Definition ${JSON.stringify(key)} is a circular alias.`, [...path, "$ref"]);
       }
       return cached;
     }
-    if (!Object.hasOwn(document.definitions, key)) {
-      throw errorWithPath(`Invalid reference ${key}`, [...path, "$ref"]);
-    }
     definitionCache.set(key, null);
-    const representation = recur(document.definitions[key], ["definitions", key]);
+    const representation = translateSchema(document.definitions[key], ["definitions", key]);
     definitionCache.set(key, representation);
     return representation;
   }
-  function resolveReference(reference, path, options, seen = new Set()) {
+  function resolveReference(reference, path, recursiveReferenceError, seen = new Set()) {
     if (seen.has(reference.$ref)) {
-      throw errorWithPath(`Invalid reference ${reference.$ref}`, [...path, "$ref"]);
+      throw errorWithPath(`Definition ${JSON.stringify(reference.$ref)} is a circular alias.`, [...path, "$ref"]);
     }
     seen.add(reference.$ref);
-    const representation = translateDefinition(reference.$ref, path, options?.recursiveReferenceError);
+    const representation = translateDefinition(reference.$ref, path, recursiveReferenceError);
     if (representation._tag === "Reference") {
-      return resolveReference(representation, path, options, seen);
+      return resolveReference(representation, path, recursiveReferenceError, seen);
     }
     if (representation._tag === "Suspend" && representation.thunk._tag === "Reference") {
-      return annotate(resolveReference(representation.thunk, path, options, seen), representation.annotations);
+      return annotate(resolveReference(representation.thunk, path, recursiveReferenceError, seen), representation.annotations);
     }
     return representation;
   }
@@ -200,35 +215,31 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
       ...right
     };
   }
-  function combinedAnnotations(representation, left, right) {
+  function annotateIntersection(representation, left, right) {
     return annotate(representation, mergeAnnotations(left._tag === "Reference" ? undefined : left.annotations, right._tag === "Reference" ? undefined : right.annotations));
   }
-  function asChecks(checks, annotations) {
-    if (checks.length === 0) return undefined;
-    if (annotations === undefined) return checks;
-    if (checks.length === 1 && checks[0].annotations === undefined) {
-      return [{
-        ...checks[0],
-        annotations
-      }];
-    }
-    return [{
-      _tag: "FilterGroup",
-      checks: checks,
-      annotations
-    }];
-  }
-  function combineChecks(left, right, annotations, deduplicate = []) {
+  function intersectChecks(left, right, deduplicate = []) {
+    let checks = right.checks;
     for (const id of deduplicate) {
-      if (left.some(check => checkId(check) === id)) {
-        right = right.filter(check => checkId(check) !== id);
+      if (left.checks.some(check => check._tag === "Filter" && check.representation?.id === id)) {
+        checks = checks.filter(check => check._tag !== "Filter" || check.representation?.id !== id);
       }
     }
-    const checks = asChecks(right, annotations);
-    return checks === undefined ? undefined : [...left, ...checks];
-  }
-  function checkId(check) {
-    return check._tag === "Filter" ? check.representation?.id : undefined;
+    if (checks.length === 0) {
+      const annotations = mergeAnnotations(left.annotations, right.annotations);
+      return [left.checks, annotations];
+    }
+    if (right.annotations !== undefined) {
+      checks = checks.length === 1 && checks[0].annotations === undefined ? [{
+        ...checks[0],
+        annotations: right.annotations
+      }] : [{
+        _tag: "FilterGroup",
+        checks: checks,
+        annotations: right.annotations
+      }];
+    }
+    return [[...left.checks, ...checks], left.annotations];
   }
   function satisfiesPrimitiveCheck(check, value) {
     if (check._tag === "FilterGroup") {
@@ -266,11 +277,11 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     }
     return representation.checks.every(check => satisfiesPrimitiveCheck(check, value));
   }
-  function combinePrimitiveWithLiteral(primitive, literal) {
+  function intersectPrimitiveWithLiteral(primitive, literal) {
     const satisfies = primitive._tag === "Boolean" ? typeof literal.literal === "boolean" : satisfiesLiteral(primitive, literal);
-    return satisfies ? combinedAnnotations(literal, primitive, literal) : never;
+    return satisfies ? annotateIntersection(literal, primitive, literal) : never;
   }
-  function combineArrays(left, right, path) {
+  function intersectArrays(left, right, path) {
     const elements = [];
     const length = Math.max(left.elements.length, right.elements.length);
     for (let index = 0; index < length; index++) {
@@ -285,7 +296,7 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
           rest: []
         } : undefined;
       }
-      const type = combine(leftType, rightType, [...path, "elements", index, "type"]);
+      const type = intersect(leftType, rightType, [...path, "elements", index, "type"]);
       if (type._tag === "Never") {
         return isOptional ? {
           elements,
@@ -305,16 +316,16 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
         rest: []
       };
     }
-    const rest = combine(leftRest, rightRest, [...path, "rest", 0]);
+    const rest = intersect(leftRest, rightRest, [...path, "rest", 0]);
     return {
       elements,
       rest: rest._tag === "Never" ? [] : [rest]
     };
   }
-  function combineTypes(types, path) {
+  function intersectAll(types, path) {
     let out = types[0] ?? unknown;
     for (let index = 1; index < types.length; index++) {
-      out = combine(out, types[index], [...path, index]);
+      out = intersect(out, types[index], [...path, index]);
     }
     return out;
   }
@@ -327,8 +338,9 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
       hasFiniteKeyDomain ||= scope.additionalProperties._tag === "Never" && scope.patterns.length === 0;
       requiresFiniteKeyDomain ||= scope.additionalProperties._tag === "Never" || scope.additionalProperties._tag !== "Unknown" && (scope.hasProperties || scope.patterns.length > 0);
     }
-    if (!hasFiniteKeyDomain && requiresFiniteKeyDomain) {
-      throw errorWithPath("Unsupported object keyword scopes", path);
+    const closedPattern = scopes.length === 1 && names.size === 0 && scopes[0].additionalProperties._tag === "Never" && scopes[0].patterns.length === 1 ? scopes[0].patterns[0] : undefined;
+    if (!hasFiniteKeyDomain && requiresFiniteKeyDomain && closedPattern === undefined) {
+      throw errorWithPath(scopes.some(scope => scope.additionalProperties._tag === "Never") ? "Cannot import this closed patterned object: only one pattern without properties is supported." : "Cannot combine typed \"additionalProperties\" with other property schemas: Effect index signatures also check excluded keys.", path);
     }
     const properties = [];
     for (const name of names) {
@@ -349,7 +361,7 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
         }
         if (property?.type === undefined && !matches) types.push(scope.additionalProperties);
       }
-      const type = combineTypes(types, [...path, "properties", name]);
+      const type = intersectAll(types, [...path, "properties", name]);
       if (!isOptional && type._tag === "Never") return never;
       properties.push({
         name,
@@ -358,46 +370,25 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
         isMutable: false
       });
     }
-    const indexSignatures = [];
-    if (!hasFiniteKeyDomain) {
-      const additionalProperties = combineTypes(scopes.map(scope => scope.additionalProperties), [...path, "additionalProperties"]);
-      const patterns = new Map();
-      for (const scope of scopes) {
-        for (const pattern of scope.patterns) {
-          const previous = patterns.get(pattern.source);
-          patterns.set(pattern.source, previous === undefined ? pattern : {
-            ...pattern,
-            type: combine(previous.type, pattern.type, [...path, "patternProperties", pattern.source])
-          });
-        }
-      }
-      for (const {
-        parameter,
-        type
-      } of patterns.values()) {
-        indexSignatures.push({
-          parameter,
-          type: combine(type, additionalProperties, [...path, "indexSignatures"])
-        });
-      }
-      indexSignatures.push({
-        parameter: string,
-        type: additionalProperties
-      });
-    } else if (properties.length === 0) {
-      indexSignatures.push({
-        parameter: string,
-        type: never
-      });
-    }
-    objectScopesByProperties.set(properties, scopes);
-    return {
+    const indexSignatures = closedPattern !== undefined ? [{
+      parameter: closedPattern.parameter,
+      type: closedPattern.type
+    }] : !hasFiniteKeyDomain ? [{
+      parameter: string,
+      type: intersectAll(scopes.map(scope => scope.additionalProperties), [...path, "additionalProperties"])
+    }] : properties.length === 0 ? [{
+      parameter: string,
+      type: never
+    }] : [];
+    const representation = {
       _tag: "Objects",
       propertySignatures: properties,
       indexSignatures,
       checks,
       annotations
     };
+    objectScopesByProperties.set(properties, [scopes, path]);
+    return representation;
   }
   const jsonRootTags = ["Null", "String", "Number", "Boolean", "Objects", "Arrays"];
   const allMasks = (1 << jsonRootTags.length) - 1;
@@ -452,7 +443,7 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
       case "Arrays":
         return representation.elements.some(element => hasChoices(element.type)) || representation.rest.some(type => hasChoices(type));
       case "Objects":
-        return representation.propertySignatures.some(property => hasChoices(property.type)) || representation.indexSignatures.some(indexSignature => hasChoices(indexSignature.parameter) || hasChoices(indexSignature.type)) || representation.checks.some(checkHasChoices);
+        return representation.propertySignatures.some(property => hasChoices(property.type)) || representation.indexSignatures.some(indexSignature => hasChoices(indexSignature.parameter) || hasChoices(indexSignature.type)) || objectScopesByProperties.get(representation.propertySignatures)[0].some(scope => scope.patterns.some(pattern => hasChoices(pattern.type))) || representation.checks.some(checkHasChoices);
       default:
         return false;
     }
@@ -474,7 +465,7 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     const literal = representation.literal;
     return typeof literal === "string" || typeof literal === "number" || typeof literal === "boolean" ? literal : undefined;
   }
-  function combineLiteralUnions(left, right, path) {
+  function intersectLiteralUnions(left, right, path) {
     if ((left.options?.mode ?? "anyOf") !== "anyOf" || (right.options?.mode ?? "anyOf") !== "anyOf") {
       return undefined;
     }
@@ -491,11 +482,11 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
       const value = literalValue(representation);
       if (value === undefined) return undefined;
       const match = rightByValue.get(value);
-      if (match !== undefined) types.push(combine(representation, annotate(match, right.annotations), path));
+      if (match !== undefined) types.push(intersect(representation, annotate(match, right.annotations), path));
     }
     return makeUnion(left, types);
   }
-  function combineUnionWithType(union, type, path, unionOnLeft) {
+  function intersectUnionWithType(union, type, path, unionOnLeft) {
     const mask = rootMask(type);
     const members = union.types.map((member, index) => ({
       index,
@@ -506,9 +497,9 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     }
     if (members.length === 1 && union.checks.length === 0) {
       const member = annotate(members[0].type, union.annotations);
-      return unionOnLeft ? combine(member, type, [...path, "types", members[0].index]) : combine(type, member, [...path, "types", members[0].index]);
+      return unionOnLeft ? intersect(member, type, [...path, "types", members[0].index]) : intersect(type, member, [...path, "types", members[0].index]);
     }
-    return makeUnion(union, members.map(member => unionOnLeft ? combine(member.type, type, [...path, "types", member.index]) : combine(type, member.type, [...path, "types", member.index])).filter(type => type._tag !== "Never"));
+    return makeUnion(union, members.map(member => unionOnLeft ? intersect(member.type, type, [...path, "types", member.index]) : intersect(type, member.type, [...path, "types", member.index])).filter(type => type._tag !== "Never"));
   }
   function isTypePartition(union) {
     let mask = 0;
@@ -520,9 +511,9 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     return true;
   }
   function unsupportedIntersection(path) {
-    throw errorWithPath("Unsupported intersection of overlapping unions", path);
+    throw errorWithPath("Cannot intersect these \"anyOf\" or \"oneOf\" alternatives without expanding their branches.", path);
   }
-  function combinePartition(partition, other, path, partitionOnLeft) {
+  function intersectPartition(partition, other, path, partitionOnLeft) {
     const partitionTypes = partition.types;
     const otherTypes = other.types;
     for (const type of otherTypes) {
@@ -534,114 +525,112 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     const types = [];
     for (let index = 0; index < partitionTypes.length; index++) {
       const member = partitionTypes[index];
-      const type = combineUnionWithType(other, member, [...path, "types", index], !partitionOnLeft);
+      const type = intersectUnionWithType(other, member, [...path, "types", index], !partitionOnLeft);
       if (type._tag !== "Never") types.push(type);
     }
     return makeUnion(partition, types);
   }
-  function combineUnions(left, right, path) {
-    const literals = combineLiteralUnions(left, right, path);
+  function intersectUnions(left, right, path) {
+    const literals = intersectLiteralUnions(left, right, path);
     if (literals !== undefined) return literals;
-    if (isTypePartition(left)) return combinePartition(left, right, path, true);
-    if (isTypePartition(right)) return combinePartition(right, left, path, false);
+    if (isTypePartition(left)) return intersectPartition(left, right, path, true);
+    if (isTypePartition(right)) return intersectPartition(right, left, path, false);
     return unsupportedIntersection(path);
   }
-  function combine(left, right, path) {
+  function intersect(left, right, path) {
     if (left._tag === "Never") return left;
     if (right._tag === "Never") return right;
-    if (left._tag === "Unknown") return combinedAnnotations(right, left, right);
-    if (right._tag === "Unknown") return combinedAnnotations(left, left, right);
-    if (left._tag === "Reference") return combine(resolveReference(left, path), right, path);
-    if (right._tag === "Reference") return combine(left, resolveReference(right, path), path);
+    if (left._tag === "Unknown") return annotateIntersection(right, left, right);
+    if (right._tag === "Unknown") return annotateIntersection(left, left, right);
+    if (left._tag === "Reference") return intersect(resolveReference(left, path), right, path);
+    if (right._tag === "Reference") return intersect(left, resolveReference(right, path), path);
     if (left._tag === "Suspend") {
-      return annotate(combine(left.thunk, right, path), left.annotations);
+      return annotate(intersect(left.thunk, right, path), left.annotations);
     }
     if (right._tag === "Suspend") {
-      return annotate(combine(left, right.thunk, path), right.annotations);
+      return annotate(intersect(left, right.thunk, path), right.annotations);
     }
-    if (left._tag === "Union" && right._tag === "Union") return combineUnions(left, right, path);
-    if (left._tag === "Union") return combineUnionWithType(left, right, path, true);
-    if (right._tag === "Union") return combineUnionWithType(right, left, path, false);
+    if (left._tag === "Union" && right._tag === "Union") return intersectUnions(left, right, path);
+    if (left._tag === "Union") return intersectUnionWithType(left, right, path, true);
+    if (right._tag === "Union") return intersectUnionWithType(right, left, path, false);
     switch (left._tag) {
       case "Null":
-        return right._tag === "Null" ? combinedAnnotations({
+        return right._tag === "Null" ? annotateIntersection({
           _tag: "Null",
           checks: [...left.checks, ...right.checks]
         }, left, right) : never;
       case "String":
         if (right._tag === "Literal") {
-          return combinePrimitiveWithLiteral(left, right);
+          return intersectPrimitiveWithLiteral(left, right);
         }
         if (right._tag !== "String") return never;
-        const stringChecks = combineChecks(left.checks, right.checks, right.annotations);
+        const [stringChecks, stringAnnotations] = intersectChecks(left, right);
         return annotate({
           _tag: "String",
-          checks: stringChecks ?? left.checks
-        }, mergeAnnotations(left.annotations, stringChecks === undefined ? right.annotations : undefined));
+          checks: stringChecks
+        }, stringAnnotations);
       case "Number":
         if (right._tag === "Literal") {
-          return combinePrimitiveWithLiteral(left, right);
+          return intersectPrimitiveWithLiteral(left, right);
         }
         if (right._tag !== "Number") return never;
-        const numberChecks = combineChecks(left.checks, right.checks, right.annotations, ["effect/schema/isFinite", "effect/schema/isInt"]);
+        const [numberChecks, numberAnnotations] = intersectChecks(left, right, ["effect/schema/isFinite", "effect/schema/isInt"]);
         return annotate({
           _tag: "Number",
-          checks: numberChecks ?? left.checks
-        }, mergeAnnotations(left.annotations, numberChecks === undefined ? right.annotations : undefined));
+          checks: numberChecks
+        }, numberAnnotations);
       case "Boolean":
         if (right._tag === "Literal") {
-          return combinePrimitiveWithLiteral(left, right);
+          return intersectPrimitiveWithLiteral(left, right);
         }
-        return right._tag === "Boolean" ? combinedAnnotations({
+        return right._tag === "Boolean" ? annotateIntersection({
           _tag: "Boolean",
           checks: [...left.checks, ...right.checks]
         }, left, right) : never;
       case "Literal":
         if (right._tag === "Literal") {
-          return left.literal === right.literal ? combinedAnnotations({
+          return left.literal === right.literal ? annotateIntersection({
             ...left,
             checks: [...left.checks, ...right.checks]
           }, left, right) : never;
         }
         if ((right._tag === "String" || right._tag === "Number") && satisfiesLiteral(right, left) || right._tag === "Boolean" && typeof left.literal === "boolean") {
-          return combinedAnnotations(left, left, right);
+          return annotateIntersection(left, left, right);
         }
         return never;
       case "Arrays":
         {
           if (right._tag !== "Arrays") return never;
-          const arrays = combineArrays(left, right, path);
+          const arrays = intersectArrays(left, right, path);
           if (arrays === undefined) return never;
-          const arrayChecks = combineChecks(left.checks, right.checks, right.annotations, ["effect/schema/isUnique"]);
+          const [checks, annotations] = intersectChecks(left, right, ["effect/schema/isUnique"]);
           return annotate({
             _tag: "Arrays",
-            elements: arrays.elements,
-            rest: arrays.rest,
-            checks: arrayChecks ?? left.checks
-          }, mergeAnnotations(left.annotations, arrayChecks === undefined ? right.annotations : undefined));
+            ...arrays,
+            checks
+          }, annotations);
         }
       case "Objects":
         {
           if (right._tag !== "Objects") return never;
-          const objectChecks = combineChecks(left.checks, right.checks, right.annotations);
-          const scopes = [...objectScopesByProperties.get(left.propertySignatures), ...objectScopesByProperties.get(right.propertySignatures)];
-          return lowerObject(scopes, objectChecks ?? left.checks, mergeAnnotations(left.annotations, objectChecks === undefined ? right.annotations : undefined), path);
+          const [checks, annotations] = intersectChecks(left, right);
+          const scopes = [...objectScopesByProperties.get(left.propertySignatures)[0], ...objectScopesByProperties.get(right.propertySignatures)[0]];
+          return lowerObject(scopes, checks, annotations, path);
         }
     }
   }
-  function recur(input, path) {
+  function translateSchema(input, path, isRoot = false) {
     if (input === false) {
       return never;
     }
-    if (typeof input !== "object" || input === null || Array.isArray(input)) return unknown;
+    if (!isObject(input)) return unknown;
     const schema = options?.onEnter === undefined ? input : options.onEnter(input);
     if (schema === undefined) {
       return unknown;
     }
-    const enumIndex = Array.isArray(schema.enum) ? schema.enum.findIndex(value => typeof value === "object" && value !== null) : -1;
-    if (enumIndex !== -1) {
-      throw errorWithPath(`Unsupported structured JSON Schema value for "enum"`, [...path, "enum", enumIndex]);
-    }
+    if (isObject(schema.not) && Object.keys(schema.not).length === 0) return annotate(never, jsonSchemaAnnotations(schema));
+    const wasInNestedResource = inNestedResource;
+    inNestedResource ||= !isRoot && typeof schema.$id === "string";
     for (const keyword of Object.keys(schema)) {
       if (keyword === "if" && !Object.hasOwn(schema, "then") && !Object.hasOwn(schema, "else")) continue;
       switch (keyword) {
@@ -653,41 +642,40 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
         case "not":
         case "unevaluatedItems":
         case "unevaluatedProperties":
-          throw errorWithPath(`Unsupported JSON Schema keyword "${keyword}"`, [...path, keyword]);
+          throw errorWithPath(`Cannot import JSON Schema keyword "${keyword}": Effect has no equivalent constraint.`, [...path, keyword]);
       }
     }
-    let representation = on(schema, path);
+    let representation = translateType(schema, path);
     if (Object.hasOwn(schema, "const")) {
-      const literal = makeJsonLiteral(schema.const);
-      if (literal === undefined && typeof schema.const === "object") {
-        throw errorWithPath(`Unsupported structured JSON Schema value for "const"`, [...path, "const"]);
-      }
-      if (literal !== undefined) representation = combine(representation, literal, [...path, "const"]);
+      const constPath = [...path, "const"];
+      const literal = makeJsonLiteral(schema.const, constPath);
+      if (literal !== undefined) representation = intersect(representation, literal, constPath);
     }
     if (Array.isArray(schema.enum)) {
-      const types = schema.enum.map(value => makeJsonLiteral(value) ?? unknown);
-      representation = combine(representation, types.length === 1 ? types[0] : {
+      const types = schema.enum.map((value, index) => makeJsonLiteral(value, [...path, "enum", index]) ?? unknown);
+      representation = intersect(representation, types.length === 1 ? types[0] : {
         _tag: "Union",
         types,
         checks: []
       }, [...path, "enum"]);
     }
     if (typeof schema.$ref === "string") {
+      if (inNestedResource) {
+        throw errorWithPath("Cannot resolve $ref under a nested \"$id\". Resolve or flatten it first.", [...path, "$ref"]);
+      }
       const $ref = JsonSchema.getReferenceKey(schema.$ref);
       if ($ref === undefined) {
-        throw errorWithPath(`Unsupported reference ${JSON.stringify(schema.$ref)}`, [...path, "$ref"]);
+        throw errorWithPath(`Unsupported $ref ${JSON.stringify(schema.$ref)}. Use "#/$defs/Name".`, [...path, "$ref"]);
       }
       if (!Object.hasOwn(document.definitions, $ref)) {
-        throw errorWithPath(`Invalid reference ${JSON.stringify(schema.$ref)}`, [...path, "$ref"]);
+        throw errorWithPath(`Missing definition ${JSON.stringify($ref)} for $ref ${JSON.stringify(schema.$ref)}.`, [...path, "$ref"]);
       }
       if (!reachableDefinitions.has($ref)) reachableDefinitions.set($ref, path);
       const reference = {
         _tag: "Reference",
         $ref
       };
-      representation = representation._tag === "Unknown" ? reference : representation._tag === "Never" ? never : combine(resolveReference(reference, path, {
-        recursiveReferenceError: `Unsupported assertion siblings on recursive reference ${reference.$ref}`
-      }), representation, path);
+      representation = representation._tag === "Unknown" ? reference : representation._tag === "Never" ? never : intersect(resolveReference(reference, path, `Recursive $ref ${JSON.stringify(reference.$ref)} cannot have sibling constraints.`), representation, path);
     }
     const annotations = jsonSchemaAnnotations(schema);
     if (annotations !== undefined && representation._tag === "Reference") {
@@ -699,7 +687,7 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     representation = annotate(representation, annotations);
     if (Array.isArray(schema.allOf)) {
       for (let index = 0; index < schema.allOf.length; index++) {
-        representation = combine(representation, recur(schema.allOf[index], [...path, "allOf", index]), [...path, "allOf", index]);
+        representation = intersect(representation, translateSchema(schema.allOf[index], [...path, "allOf", index]), [...path, "allOf", index]);
       }
     }
     for (const mode of ["anyOf", "oneOf"]) {
@@ -707,7 +695,7 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
       if (Array.isArray(members)) {
         const union = {
           _tag: "Union",
-          types: members.map((member, index) => recur(member, [...path, mode, index])),
+          types: members.map((member, index) => translateSchema(member, [...path, mode, index])),
           ...(mode === "oneOf" ? {
             options: {
               mode
@@ -715,17 +703,18 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
           } : {}),
           checks: []
         };
-        representation = combine(union, representation, [...path, mode]);
+        representation = intersect(union, representation, [...path, mode]);
       }
     }
+    inNestedResource = wasInNestedResource;
     return representation;
   }
-  function on(schema, path) {
+  function translateType(schema, path) {
     const types = Array.isArray(schema.type) && schema.type.every(isImportedJsonSchemaType) ? schema.type : !isImportedJsonSchemaType(schema.type) && hasTypeSpecificKeywords(schema) ? jsonSchemaValueTypes : undefined;
     if (types !== undefined) {
       return {
         _tag: "Union",
-        types: types.map(type => on({
+        types: types.map(type => translateType({
           ...schema,
           type
         }, path)),
@@ -761,14 +750,14 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
           const minItems = typeof schema.minItems === "number" ? schema.minItems : 0;
           const elements = prefixItems?.map((element, index) => ({
             isOptional: index + 1 > minItems,
-            type: recur(element, [...path, "prefixItems", index])
+            type: translateSchema(element, [...path, "prefixItems", index])
           })) ?? [];
           const isTupleClosed = schema.items === false || schema.items === undefined && prefixItems !== undefined && schema.maxItems === prefixItems.length;
           const isMaxItemsRedundant = isTupleClosed && typeof schema.maxItems === "number" && schema.maxItems >= elements.length;
           return {
             _tag: "Arrays",
             elements,
-            rest: isTupleClosed ? [] : [schema.items === undefined ? unknown : recur(schema.items, [...path, "items"])],
+            rest: isTupleClosed ? [] : [schema.items === undefined ? unknown : translateSchema(schema.items, [...path, "items"])],
             checks: collectArrayChecks(schema, isMaxItemsRedundant)
           };
         }
@@ -781,17 +770,17 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
         return unknown;
     }
   }
-  function importPatternChecks(pattern, path) {
+  function importPatternCheck(pattern, path) {
     switch (options?.patterns ?? "error") {
       case "error":
-        throw errorWithPath(`Pattern encountered while patterns is set to "error"`, path);
+        throw errorWithPath("Patterns may block validation and are disabled. Use patterns: \"apply\" for trusted schemas or \"ignore\" to discard them.", path);
       case "ignore":
-        return [];
+        return undefined;
       case "apply":
-        return [jsonSchemaFilter("effect/schema/isPattern", {
+        return jsonSchemaFilter("effect/schema/isPattern", {
           source: pattern,
           flags: ""
-        })];
+        });
     }
   }
   function collectStringChecks(schema, path) {
@@ -799,7 +788,8 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     addNumberCheck(checks, schema.minLength, "effect/schema/isMinLength", "minLength");
     addNumberCheck(checks, schema.maxLength, "effect/schema/isMaxLength", "maxLength");
     if (typeof schema.pattern === "string") {
-      checks.push(...importPatternChecks(schema.pattern, [...path, "pattern"]));
+      const check = importPatternCheck(schema.pattern, [...path, "pattern"]);
+      if (check !== undefined) checks.push(check);
     }
     return checks;
   }
@@ -826,20 +816,20 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     return checks;
   }
   function collectObjectScope(schema, path) {
-    const sourceProperties = typeof schema.properties === "object" && schema.properties !== null && !Array.isArray(schema.properties) ? schema.properties : {};
-    const required = Array.isArray(schema.required) ? schema.required.filter(key => typeof key === "string") : [];
+    const sourceProperties = isObject(schema.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema.required) ? schema.required.filter(key => typeof key === "string") : []);
     const propertyNames = Object.keys(sourceProperties);
     const keys = new Set([...propertyNames, ...required]);
     const properties = new Map(Array.from(keys, name => [name, {
-      type: Object.hasOwn(sourceProperties, name) ? recur(sourceProperties[name], [...path, "properties", name]) : undefined,
-      isOptional: !required.includes(name)
+      type: Object.hasOwn(sourceProperties, name) ? translateSchema(sourceProperties[name], [...path, "properties", name]) : undefined,
+      isOptional: !required.has(name)
     }]));
     const hasProperties = propertyNames.length > 0;
     const patterns = [];
-    if (typeof schema.patternProperties === "object" && schema.patternProperties !== null && !Array.isArray(schema.patternProperties)) {
+    if (isObject(schema.patternProperties)) {
       for (const [pattern, value] of Object.entries(schema.patternProperties)) {
-        const checks = importPatternChecks(pattern, [...path, "patternProperties", pattern]);
-        if (checks.length === 0) return {
+        const check = importPatternCheck(pattern, [...path, "patternProperties", pattern]);
+        if (check === undefined) return {
           properties,
           hasProperties,
           patterns: [],
@@ -849,13 +839,13 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
           source: pattern,
           parameter: {
             _tag: "String",
-            checks
+            checks: [check]
           },
-          type: recur(value, [...path, "patternProperties", pattern])
+          type: translateSchema(value, [...path, "patternProperties", pattern])
         });
       }
     }
-    const additionalProperties = schema.additionalProperties === false ? never : typeof schema.additionalProperties === "object" && schema.additionalProperties !== null ? recur(schema.additionalProperties, [...path, "additionalProperties"]) : unknown;
+    const additionalProperties = schema.additionalProperties === false ? never : isObject(schema.additionalProperties) ? translateSchema(schema.additionalProperties, [...path, "additionalProperties"]) : unknown;
     return {
       properties,
       hasProperties,
@@ -869,14 +859,15 @@ function translateJsonSchemaMultiDocument(document, options, singleRoot = false)
     addNumberCheck(checks, schema.maxProperties, "effect/schema/isMaxProperties", "maxProperties");
     if (schema.propertyNames !== undefined) {
       const propertyNamesPath = [...path, "propertyNames"];
-      checks.push(jsonSchemaFilter("effect/schema/isPropertyNames", null, [combine(string, recur(schema.propertyNames, propertyNamesPath), propertyNamesPath)]));
+      checks.push(jsonSchemaFilter("effect/schema/isPropertyNames", null, [intersect(string, translateSchema(schema.propertyNames, propertyNamesPath), propertyNamesPath)]));
     }
     return checks;
   }
   const references = {};
-  const representations = document.schemas.map((schema, index) => unknownJsonSchemas(recur(schema, singleRoot ? ["schema"] : ["schemas", index])));
-  for (const [key, path] of reachableDefinitions) {
-    InternalRecord.assignProperty(references, key, unknownJsonSchemas(translateDefinition(key, path)));
+  const representations = document.schemas.map((schema, index) => finalize(translateSchema(schema, singleRoot ? ["schema"] : ["schemas", index], true)));
+  // Definitions expanded away by intersections do not need a standalone output schema.
+  for (const key of finalReferences) {
+    InternalRecord.assignProperty(references, key, finalize(translateDefinition(key, reachableDefinitions.get(key))));
   }
   for (const {
     reference,