schema-components 1.20.0 → 1.21.0

package/dist/{typeInference-CDoD_LZ_.d.mts → typeInference-Bxw3NOG1.d.mts}

@@ -1,4 +1,4 @@
-import { d as FieldOverrides, u as FieldOverride } from "./types-C9zw9wbX.mjs";
+import { d as FieldOverrides, u as FieldOverride } from "./types-BnxPEElk.mjs";
 import { z } from "zod";
 
 //#region src/core/typeInference.d.ts
@@ -24,20 +24,51 @@ type UnrepresentableZodType = z.ZodBigInt | z.ZodDate | z.ZodMap | z.ZodSet | z.
 interface UnrepresentableZodSchemaError {
   readonly __schemaComponentsError: "Zod 4 type has no JSON Schema representation. See SchemaNormalisationError code 'zod-type-unrepresentable'.";
 }
+/**
+ * Recursively unwrap Zod 4 wrappers that hold an inner schema —
+ * `ZodOptional`, `ZodNullable`, `ZodReadonly`, `ZodLazy`, and `ZodPipe`.
+ *
+ * The runtime conversion still throws for `z.optional(z.bigint())`,
+ * `z.lazy(() => z.bigint())`, `z.nullable(z.bigint())`,
+ * `z.bigint().readonly()`, and `z.bigint().pipe(z.bigint())` because
+ * `z.toJSONSchema()` walks into the wrapped schema before reporting the
+ * unrepresentable type. The compile-time rejection must therefore peel
+ * those wrappers off before checking against the rejection list, or the
+ * brand would never surface for wrapped inputs.
+ *
+ * `ZodCodec` is short-circuited at the top because it is itself listed
+ * in {@link UnrepresentableZodType}. It extends `ZodPipe` structurally,
+ * so without the early exit the `ZodPipe` branch would unwrap a bare
+ * codec into its two sides and the rejection would no longer fire for
+ * `z.codec(...)`.
+ *
+ * `ZodPipe` (non-codec) has two slots (`in` and `out`); both are
+ * unwrapped into a union so a single unrepresentable side surfaces via
+ * {@link AnyMemberIsUnrepresentable}.
+ */
+type UnwrapZodWrapper<T> = T extends z.ZodCodec ? T : T extends z.ZodOptional<infer Inner> ? UnwrapZodWrapper<Inner> : T extends z.ZodNullable<infer Inner> ? UnwrapZodWrapper<Inner> : T extends z.ZodReadonly<infer Inner> ? UnwrapZodWrapper<Inner> : T extends z.ZodLazy<infer Inner> ? UnwrapZodWrapper<Inner> : T extends z.ZodPipe<infer InnerIn, infer InnerOut> ? UnwrapZodWrapper<InnerIn> | UnwrapZodWrapper<InnerOut> : T;
+/**
+ * True when any member of the (possibly unioned) input extends one of
+ * the unrepresentable Zod types. Distribution over the union ensures a
+ * single unrepresentable member triggers true — matching runtime
+ * semantics for `ZodPipe`, whose two sides expand to a union via
+ * {@link UnwrapZodWrapper}.
+ */
+type AnyMemberIsUnrepresentable<T> = (T extends UnrepresentableZodType ? true : false) extends false ? false : true;
 /**
  * Reject Zod 4 inputs whose runtime conversion is known to throw.
  *
- * - When `T` is one of the {@link UnrepresentableZodType} variants, the
- *   resolved type is {@link UnrepresentableZodSchemaError}, which is
- *   not assignable from any legitimate Zod / JSON Schema / OpenAPI
- *   input — so the prop fails to typecheck.
+ * - When `T` (or any inner schema wrapped by `ZodOptional`,
+ *   `ZodNullable`, `ZodReadonly`, `ZodLazy`, or `ZodPipe`) is one of
+ *   the {@link UnrepresentableZodType} variants, the resolved type is
+ *   {@link UnrepresentableZodSchemaError}, which is not assignable from
+ *   any legitimate Zod / JSON Schema / OpenAPI input — so the prop
+ *   fails to typecheck.
  * - Anything else (Zod 4 schemas that DO convert, JSON Schema literals,
  *   OpenAPI documents, `unknown` for runtime inputs) passes through
  *   unchanged.
- *
- * Wrapped in a tuple to suppress distribution over union types.
  */
-type RejectUnrepresentableZod<T> = [T] extends [UnrepresentableZodType] ? UnrepresentableZodSchemaError : T;
+type RejectUnrepresentableZod<T> = AnyMemberIsUnrepresentable<UnwrapZodWrapper<T>> extends true ? UnrepresentableZodSchemaError : T;
 /**
  * Convert a readonly tuple/array of values to a union type.
  * Handles both `as const` readonly tuples and mutable arrays.
@@ -66,7 +97,7 @@ type ArrayToUnion<A> = A extends readonly unknown[] ? A[number] : never;
  * - not -> unknown (negation not expressible in TS)
  * - patternProperties -> merged into loose index signature
  */
-type FromJSONSchema<S, Defs extends Record<string, unknown> = Record<string, never>> = S extends {
+type FromJSONSchema<S, Defs extends Record<string, unknown> = Record<string, never>, Depth extends readonly unknown[] = []> = MergeRootDefs<S, Defs> extends infer MergedDefs extends Record<string, unknown> ? S extends {
   nullable: true;
 } ?
 /**
@@ -77,21 +108,21 @@ type FromJSONSchema<S, Defs extends Record<string, unknown> = Record<string, nev
 * `FromJSONSchema` level means nested fields inside refs preserve
 * nullability when resolved.
 */
-FromJSONSchema<Omit<S, "nullable">, Defs> | null : S extends {
+FromJSONSchema<Omit<S, "nullable">, MergedDefs, Depth> | null : S extends {
   $ref: infer R extends string;
-} ? ResolveSchemaRef<R, Defs> : S extends {
+} ? ResolveSchemaRef<R, MergedDefs, Depth> : S extends {
   $recursiveRef: string;
 } ? unknown : S extends {
   $dynamicRef: infer R extends string;
-} ? ResolveSchemaRef<R, Defs> : S extends {
+} ? ResolveSchemaRef<R, MergedDefs, Depth> : S extends {
   allOf: infer A;
-} ? AllOfToType<A, Defs> : S extends {
+} ? AllOfToType<A, MergedDefs, Depth> : S extends {
   anyOf: infer A;
-} ? UnionOfMembers<A, Defs> : S extends {
+} ? UnionOfMembers<A, MergedDefs, Depth> : S extends {
   oneOf: infer A;
-} ? UnionOfMembers<A, Defs> : S extends {
+} ? UnionOfMembers<A, MergedDefs, Depth> : S extends {
   if: unknown;
-} ? FromJSONSchema<Omit<S, "if" | "then" | "else">, Defs> : S extends {
+} ? FromJSONSchema<Omit<S, "if" | "then" | "else">, MergedDefs, Depth> : S extends {
   not: unknown;
 } ? unknown : S extends {
   const: infer V;
@@ -99,7 +130,68 @@ FromJSONSchema<Omit<S, "nullable">, Defs> | null : S extends {
   enum: infer E;
 } ? ArrayToUnion<E> : S extends {
   type: infer T;
-} ? TypeToTs<T, S, Defs> : S extends readonly (infer E)[] ? E : unknown;
+} ? TypeToTs<T, S, MergedDefs, Depth> : S extends readonly (infer E)[] ? E : unknown : unknown;
+/**
+ * Merge `$defs` / `definitions` declared at the current schema position with
+ * the caller-supplied `Defs` map BEFORE the ref/allOf/anyOf/oneOf dispatch.
+ *
+ * SOURCE-OF-TRUTH: parity with the runtime walker, which uses `rootDocument`
+ * (see `packages/core/src/core/ref.ts` line 91) to resolve any `$ref` against
+ * the full document — including sibling definitions colocated with the
+ * reference. Without this merge, a legal schema like
+ * `{ $ref: "#/definitions/Foo", definitions: { Foo: {...} } }` would lose
+ * its sibling defs because the ref branch fires before `ExtractDefs` runs
+ * inside `ObjectSchemaToTs`.
+ *
+ * Merge semantics (per-key resolution via {@link CollisionSafeMerge}):
+ * - Parent-only keys: parent value wins
+ * - Local-only keys: local value wins
+ * - Shared keys: parent value wins (caller / inherited context takes
+ *   precedence over a deeper redeclaration)
+ *
+ * When the current schema declares no local defs (`HasLocalDefs<S>` is
+ * `false`), `ParentDefs` is returned unchanged so the inherited context
+ * is never poisoned by the empty index-signature sentinel.
+ */
+type MergeRootDefs<S, ParentDefs extends Record<string, unknown>> = HasLocalDefs<S> extends true ? ExtractRawDefs<S> extends infer RawDefs extends Record<string, unknown> ? CollisionSafeMerge<CollisionSafeMerge<RawDefs, ExtractAnchors<RawDefs>>, ParentDefs> : ParentDefs : ParentDefs;
+/**
+ * Merge two record-shaped types where keys present in `B` always take
+ * precedence over the same key in `A`.
+ *
+ * The empty default `Record<string, never>` is detected explicitly via
+ * {@link IsEmptyDefs}: when either side is the sentinel, the other side
+ * is returned unchanged. This avoids two pitfalls of the naive
+ * `Omit<A, keyof B> & B` approach:
+ *
+ * 1. `keyof Record<string, never>` is the entire `string` type, so
+ *    `Omit<A, string>` would strip every key from `A`.
+ * 2. Iterating a mapped type over `keyof A | keyof B` where either side
+ *    contributes `string` collapses every entry to the index-signature
+ *    value (`never` in the sentinel), wiping the literal keys from the
+ *    other side.
+ *
+ * Only when both sides hold concrete literal keys does the per-key
+ * mapped merge run.
+ */
+type CollisionSafeMerge<A, B> = IsEmptyDefs<A> extends true ? B : IsEmptyDefs<B> extends true ? A : { [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never };
+/**
+ * True for the empty-default `Record<string, never>` sentinel used as the
+ * initial `Defs` map — i.e. an open index signature `[string]: never`
+ * with no literal keys. Distinguished from a record with at least one
+ * literal key by checking that `string extends keyof T`.
+ */
+type IsEmptyDefs<T> = [keyof T] extends [never] ? true : string extends keyof T ? true : false;
+/**
+ * True when the schema declares `$defs` or `definitions` as an object,
+ * false otherwise. Used by {@link MergeRootDefs} and {@link ExtractDefs}
+ * to avoid intersecting the parent context with an empty
+ * index-signature sentinel.
+ */
+type HasLocalDefs<S> = S extends {
+  $defs: Record<string, unknown>;
+} ? true : S extends {
+  definitions: Record<string, unknown>;
+} ? true : false;
 /**
  * Marker type emitted when OpenAPI $ref resolution hits the type-level
  * recursion depth limit. Instead of silently falling back to
@@ -137,18 +229,23 @@ type DetectRecursiveFallback<T> = unknown extends T ? __SchemaInferenceFellBack
  *
  * The TypeScript type system imposes its own recursion limit; without an
  * explicit bound a cyclic schema graph would exhaust it and degrade to
- * `any`/`unknown` silently. Ten levels is the runtime walker's parallel
- * — see `countDistinctRefs` in `ref.ts` (lines 52-55), which derives its
- * bound from the number of distinct `$ref` strings in the document.
+ * `any`/`unknown` silently. This number is the runtime walker's parallel
+ * — see `resolveRef` in `packages/core/src/core/ref.ts` (line 119), whose
+ * default `maxDepth` is `64`. Matching the runtime bound here means a
+ * schema that the runtime resolves successfully is never silently dropped
+ * to `__SchemaInferenceFellBack` at compile time purely because the
+ * type-level limit was lower.
  *
  * A fixed bound is used here rather than a derived one because the type
  * system has no way to count distinct strings across a recursive `Defs`
  * map without itself recursing — which is the problem the bound exists
- * to solve. Ten covers every realistic schema graph encountered in
- * practice; deeper graphs surface as `__SchemaInferenceFellBack` so
- * consumers can detect the limit explicitly.
+ * to solve. Real-world OpenAPI documents (Stripe, GitHub, AWS) routinely
+ * contain 30-100+ distinct `$ref` strings, so a low ceiling would mask
+ * legitimate references. Deeper graphs surface as
+ * `__SchemaInferenceFellBack` so consumers can detect the limit
+ * explicitly.
  */
-type DEFAULT_MAX_DEPTH = 10;
+type DEFAULT_MAX_DEPTH = 64;
 /**
  * Resolve a $ref against the local definitions context.
  *
@@ -170,11 +267,11 @@ type DEFAULT_MAX_DEPTH = 10;
  * a Zod-converted or hand-written JSON Schema that points into the
  * OpenAPI component tree, this branch produces the corresponding type.
  */
-type ResolveSchemaRef<R extends string, Defs extends Record<string, unknown>, Depth extends number = 0> = Depth extends DEFAULT_MAX_DEPTH ? __SchemaInferenceFellBack : R extends "#" ? unknown : R extends `#/$defs/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#/definitions/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#/components/schemas/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs>> : unknown : R extends `#${infer AnchorName}` ? AnchorName extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[AnchorName], Defs>> : unknown : unknown;
+type ResolveSchemaRef<R extends string, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = Depth["length"] extends DEFAULT_MAX_DEPTH ? __SchemaInferenceFellBack : R extends "#" ? unknown : R extends `#/$defs/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs, [unknown, ...Depth]>> : unknown : R extends `#/definitions/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs, [unknown, ...Depth]>> : unknown : R extends `#/components/schemas/${infer Name}` ? Name extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[Name], Defs, [unknown, ...Depth]>> : unknown : R extends `#${infer AnchorName}` ? AnchorName extends keyof Defs ? DetectRecursiveFallback<FromJSONSchema<Defs[AnchorName], Defs, [unknown, ...Depth]>> : unknown : unknown;
 /**
  * Merge an allOf array into an intersection type.
  */
-type AllOfToType<A, Defs extends Record<string, unknown>> = A extends readonly unknown[] ? UnionToIntersection<FromJSONSchema<A[number], Defs>> : unknown;
+type AllOfToType<A, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = A extends readonly unknown[] ? UnionToIntersection<FromJSONSchema<A[number], Defs, Depth>> : unknown;
 /**
  * Convert an anyOf/oneOf array into a union type.
  *
@@ -195,7 +292,7 @@ type AllOfToType<A, Defs extends Record<string, unknown>> = A extends readonly u
  * nullable when at least one null member is present — mirrors the
  * walker's `normaliseAnyOf`.
  */
-type UnionOfMembers<A, Defs extends Record<string, unknown>> = A extends readonly unknown[] ? HasNullMember<A> extends true ? Exclude<FromJSONSchema<A[number], Defs>, null> | null : FromJSONSchema<A[number], Defs> : unknown;
+type UnionOfMembers<A, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = A extends readonly unknown[] ? HasNullMember<A> extends true ? Exclude<FromJSONSchema<A[number], Defs, Depth>, null> | null : FromJSONSchema<A[number], Defs, Depth> : unknown;
 /**
  * Check whether an anyOf/oneOf array contains a `{ type: "null" }` member.
  *
@@ -212,12 +309,12 @@ type HasNullMember<A> = A extends readonly unknown[] ? null extends A[number] ?
  * Dispatch on a `type` value -- handles single types, type arrays,
  * and delegates to the appropriate type-specific resolver.
  */
-type TypeToTs<T, S, Defs extends Record<string, unknown>> = T extends "string" ? string : T extends "number" | "integer" ? number : T extends "boolean" ? boolean : T extends "null" ? null : T extends "array" ? ArraySchemaToTs<S, Defs> : T extends "object" ? ObjectSchemaToTs<S, Defs> : T extends readonly (infer E)[] ? TypeArrayToTs<E, S, Defs> : unknown;
+type TypeToTs<T, S, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = T extends "string" ? string : T extends "number" | "integer" ? number : T extends "boolean" ? boolean : T extends "null" ? null : T extends "array" ? ArraySchemaToTs<S, Defs, Depth> : T extends "object" ? ObjectSchemaToTs<S, Defs, Depth> : T extends readonly (infer E)[] ? TypeArrayToTs<E, S, Defs, Depth> : unknown;
 /**
  * Handle `type` as an array (Draft 04-07): `["string", "null"]`.
  * Filters out "null" and makes the result nullable.
  */
-type TypeArrayToTs<E, S, Defs extends Record<string, unknown>> = E extends "null" ? null : E extends "string" ? NullableResult<string, S> : E extends "number" | "integer" ? NullableResult<number, S> : E extends "boolean" ? NullableResult<boolean, S> : E extends "array" ? NullableResult<ArraySchemaToTs<OmitArrayHelpers<S>, Defs>, S> : E extends "object" ? NullableResult<ObjectSchemaToTs<OmitArrayHelpers<S>, Defs>, S> : unknown;
+type TypeArrayToTs<E, S, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = E extends "null" ? null : E extends "string" ? NullableResult<string, S> : E extends "number" | "integer" ? NullableResult<number, S> : E extends "boolean" ? NullableResult<boolean, S> : E extends "array" ? NullableResult<ArraySchemaToTs<OmitArrayHelpers<S>, Defs, Depth>, S> : E extends "object" ? NullableResult<ObjectSchemaToTs<OmitArrayHelpers<S>, Defs, Depth>, S> : unknown;
 /**
  * Make a type nullable if the original schema `type` array includes "null".
  * Detects nullable from the type array directly.
@@ -243,17 +340,17 @@ type OmitArrayHelpers<S> = Omit<S, "prefixItems" | "items" | "additionalProperti
  * `contains` / `minContains` / `maxContains` constrain elements at runtime
  * but don't change the compile-time array element type.
  */
-type ArraySchemaToTs<S, Defs extends Record<string, unknown>> = S extends {
+type ArraySchemaToTs<S, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = S extends {
   prefixItems: infer P;
-} ? PrefixItemsToTuple<P, Defs> : S extends {
+} ? PrefixItemsToTuple<P, Defs, Depth> : S extends {
   items: infer I extends readonly unknown[];
-} ? PrefixItemsToTuple<I, Defs> : S extends {
+} ? PrefixItemsToTuple<I, Defs, Depth> : S extends {
   items: infer I;
-} ? FromJSONSchema<I, Defs>[] : unknown[];
+} ? FromJSONSchema<I, Defs, Depth>[] : unknown[];
 /**
  * Convert a prefixItems array to a TypeScript tuple type.
  */
-type PrefixItemsToTuple<P, Defs extends Record<string, unknown>> = P extends readonly [infer First, ...infer Rest] ? [FromJSONSchema<First, Defs>, ...PrefixItemsToTuple<Rest, Defs>] : [];
+type PrefixItemsToTuple<P, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = P extends readonly [infer First, ...infer Rest] ? [FromJSONSchema<First, Defs, Depth>, ...PrefixItemsToTuple<Rest, Defs, Depth>] : [];
 /**
  * Parse an object schema: properties + required -> specific object,
  * additionalProperties -> Record, or empty object.
@@ -267,24 +364,24 @@ type PrefixItemsToTuple<P, Defs extends Record<string, unknown>> = P extends rea
  * - `dependentSchemas` / `dependentRequired` -> ignored (runtime-only conditionals)
  * - `unevaluatedProperties` -> ignored (runtime-only)
  */
-type ObjectSchemaToTs<S, Defs extends Record<string, unknown>> = S extends {
+type ObjectSchemaToTs<S, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = S extends {
   type: "object";
   properties: infer P;
-} ? ExtractDefs<S, Defs> extends infer D extends Record<string, unknown> ? MergePatternProps<{ [K in keyof P as K extends RequiredKeysOf<S> ? K : never]: FromJSONSchema<P[K], D> } & { [K in keyof P as K extends RequiredKeysOf<S> ? never : K]?: FromJSONSchema<P[K], D> }, S, D> : never : S extends {
+} ? ExtractDefs<S, Defs> extends infer D extends Record<string, unknown> ? MergePatternProps<{ [K in keyof P as K extends RequiredKeysOf<S> ? K : never]: FromJSONSchema<P[K], D, Depth> } & { [K in keyof P as K extends RequiredKeysOf<S> ? never : K]?: FromJSONSchema<P[K], D, Depth> }, S, D, Depth> : never : S extends {
   additionalProperties: infer V;
-} ? Record<string, FromJSONSchema<V, Defs>> : Record<string, unknown>;
+} ? Record<string, FromJSONSchema<V, Defs, Depth>> : Record<string, unknown>;
 /**
  * If the schema has `patternProperties`, intersect the base object type
  * with a `Record<string, T>` index signature covering all pattern values.
  * If no `patternProperties`, return the base type unchanged.
  */
-type MergePatternProps<Base, S, Defs extends Record<string, unknown>> = S extends {
+type MergePatternProps<Base, S, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = S extends {
   patternProperties: infer PP;
-} ? PP extends Record<string, unknown> ? Base & Record<string, UnionOfPatternValues<PP, Defs>> : Base : Base;
+} ? PP extends Record<string, unknown> ? Base & Record<string, UnionOfPatternValues<PP, Defs, Depth>> : Base : Base;
 /**
  * Extract the union of all pattern property value types.
  */
-type UnionOfPatternValues<PP extends Record<string, unknown>, Defs extends Record<string, unknown>> = { [K in keyof PP]: FromJSONSchema<PP[K], Defs> }[keyof PP];
+type UnionOfPatternValues<PP extends Record<string, unknown>, Defs extends Record<string, unknown>, Depth extends readonly unknown[] = []> = { [K in keyof PP]: FromJSONSchema<PP[K], Defs, Depth> }[keyof PP];
 /**
  * Extract the `required` array from a schema as a union of string literals.
  * Handles both readonly `as const` arrays and mutable arrays.
@@ -294,11 +391,16 @@ type RequiredKeysOf<S> = S extends {
 } ? R extends readonly string[] ? R[number] : never : never;
 /**
  * Extract $defs / definitions from a schema for $ref resolution context.
- * Also indexes schemas with `$anchor` or `$dynamicAnchor` by their anchor name,
- * enabling `#SomeName` ref resolution.
- * Merges with the existing Defs context from parent schemas.
+ * Also indexes schemas with `$anchor` or `$dynamicAnchor` by their anchor
+ * name, enabling `#SomeName` ref resolution.
+ *
+ * Shares merge semantics with {@link MergeRootDefs}: caller-supplied
+ * (`ParentDefs`) entries win on key collision, the empty-default
+ * sentinel is detected so it does not poison the parent context, and the
+ * `HasLocalDefs` guard short-circuits when the current node declares no
+ * defs of its own.
  */
-type ExtractDefs<S, ParentDefs extends Record<string, unknown>> = ExtractRawDefs<S> extends infer RawDefs extends Record<string, unknown> ? RawDefs & ParentDefs & ExtractAnchors<RawDefs> : ParentDefs;
+type ExtractDefs<S, ParentDefs extends Record<string, unknown>> = HasLocalDefs<S> extends true ? ExtractRawDefs<S> extends infer RawDefs extends Record<string, unknown> ? CollisionSafeMerge<CollisionSafeMerge<RawDefs, ExtractAnchors<RawDefs>>, ParentDefs> : ParentDefs : ParentDefs;
 /** Extract raw $defs / definitions maps. */
 type ExtractRawDefs<S> = S extends {
   $defs: infer D;
@@ -441,9 +543,11 @@ type ParameterNamesOf<Doc, Path extends string, Method extends string> = Operati
  * Detect whether a document is Swagger 2.0 (OpenAPI 2.0).
  *
  * SOURCE-OF-TRUTH: mirrors runtime `isSwagger2` in
- * `packages/core/src/core/version.ts`, which checks for `swagger: "2.0"`.
- * The runtime path also recognises top-level `definitions` / parameters in
- * the body location, but `swagger: "2.0"` is the canonical marker.
+ * `packages/core/src/core/version.ts` (line 305), which parses the
+ * `swagger` field via `detectOpenApiVersion` (line 264) and returns true
+ * for any document whose major version is `2`. Runtime therefore accepts
+ * `"2.0"`, `"2.0.0"`, `"2.1"`, and any other `2.x` form — so the
+ * type-level detector must too.
  *
  * Type-level Swagger 2.0 documents cannot be fully normalised at compile
  * time — the rewrite reorders the document tree (definitions →
@@ -451,9 +555,19 @@ type ParameterNamesOf<Doc, Path extends string, Method extends string> = Operati
  * TypeScript's mapped-type machinery cannot express. Detecting the
  * version is tractable, so we surface `__SchemaInferenceFellBack`
  * deliberately rather than silently producing `unknown`.
+ *
+ * Two shapes are accepted:
+ * - `{ swagger: "2.<anything>" }` — the on-the-wire string form
+ * - `{ swagger: { major: 2, ... } }` — the parsed `OpenApiVersionInfo`
+ *   object form, mirroring the runtime's tolerance for pre-parsed
+ *   version metadata
  */
 type IsSwagger2Doc<Doc> = Doc extends {
-  swagger: "2.0";
+  swagger: `2.${string}`;
+} ? true : Doc extends {
+  swagger: {
+    major: 2;
+  };
 } ? true : false;
 /**
  * Infer the TypeScript type of an OpenAPI operation's request body.

package/dist/{types-C9zw9wbX.d.mts → types-BnxPEElk.d.mts}

@@ -84,8 +84,6 @@ interface ArrayConstraints {
   minItems?: number;
   maxItems?: number;
   uniqueItems?: boolean;
-  /** Schema that at least one array item must match. */
-  contains?: Record<string, unknown>;
   minContains?: number;
   maxContains?: number;
   /** Constraint schema for unevaluated items. */
@@ -176,6 +174,12 @@ interface ArrayField extends FieldBase {
   constraints: ArrayConstraints;
   /** The element sub-schema. */
   element?: WalkedField;
+  /**
+   * Walked schema that at least one array item must match
+   * (`contains` keyword). Constrains element membership at runtime;
+   * paired with `minContains`/`maxContains` for cardinality.
+   */
+  contains?: WalkedField;
   /** Walked schema for unevaluated items. */
   unevaluatedItems?: WalkedField;
 }
@@ -190,6 +194,12 @@ interface TupleField extends FieldBase {
    * absent, additional items are permitted but unconstrained.
    */
   restItems?: WalkedField;
+  /**
+   * Walked schema that at least one array item must match
+   * (`contains` keyword). Tuples may declare it alongside positional
+   * element schemas to require the presence of a specific element.
+   */
+  contains?: WalkedField;
 }
 interface RecordField extends FieldBase {
   type: "record";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "schema-components",
-    "version": "1.20.0",
+    "version": "1.21.0",
     "description": "React components that render UI from Zod schemas, JSON Schema, and OpenAPI documents",
     "type": "module",
     "main": "./dist/index.mjs",