Fix JSON Schema prefixItems import semantics by fubhy · Pull Request #7060 · Effect-TS/effect

fubhy · 2026-08-05T21:29:52Z

Summary

Importing prefixItems with maxItems can accept arrays longer than maxItems and reject permitted trailing items when the bound exceeds the prefix length. The resulting Effect schema therefore disagrees with both bounded and open Draft 2020-12 tuple forms.

Important

This PR starts with focused failing reproduction tests. Add the implementation fix to this same branch; CI is expected to fail until that fix is included.

JSON Schema prefixItems loses maxItems semantics

Module: effect/internal/schema/fromJsonSchemaDocument
Audit ID: effect-ff1a063c2ab0dc92
Severity / confidence: medium / high

What happens

Importing prefixItems with maxItems can accept arrays longer than maxItems and reject permitted trailing items when the bound exceeds the prefix length. The resulting Effect schema therefore disagrees with both bounded and open Draft 2020-12 tuple forms.

Why it happens

The importer creates an element for every prefixItems entry, sets rest to empty whenever any numeric maxItems is present, and suppresses maxLength checks whenever prefixItems exists. Thus a bound shorter than the prefix is not enforced, while a bound longer than the prefix is converted into a closed tuple at the prefix length.

Expected behavior

SchemaRepresentation.fromJsonSchemaDocument must treat prefixItems as positional constraints, maxItems as the total array-length bound, and absent or permissive items as allowing values after the prefix up to that bound.

Relevant implementation

These links and excerpts are pinned to audit base 17f0b91a243ccfe4a38d27debdc983adf434e738.

packages/effect/src/internal/schema/fromJsonSchemaDocument.ts:759-820

View problematic code at packages/effect/src/internal/schema/fromJsonSchemaDocument.ts:759-808

      case "array": {
        const minItems = typeof schema.minItems === "number" ? schema.minItems : 0
        const elements = Array.isArray(schema.prefixItems)
          ? schema.prefixItems.map((element, index) => ({
            isOptional: index + 1 > minItems,
            type: recur(element, [...path, "prefixItems", index])
          }))
          : []
        const rest = schema.items !== undefined
          ? [recur(schema.items, [...path, "items"])]
          : schema.prefixItems !== undefined && typeof schema.maxItems === "number"
          ? []
          : [unknown]
        return {
          _tag: "Arrays",
          elements,
          rest,
          checks: collectArrayChecks(schema)
        }
      }
      case "object":
        return {
          _tag: "Objects",
          propertySignatures: collectProperties(schema, path),
          indexSignatures: collectIndexSignatures(schema, path),
          checks: collectObjectChecks(schema, path)
        }
      default:
        return unknown
    }
  }

  function collectStringChecks(schema: JsonSchema.JsonSchema): Array<Check> {
    const checks: Array<Check> = []
    addNumberCheck(checks, schema.minLength, "effect/schema/isMinLength", "minLength")
    addNumberCheck(checks, schema.maxLength, "effect/schema/isMaxLength", "maxLength")
    if (typeof schema.pattern === "string") {
      checks.push(jsonSchemaFilter("effect/schema/isPattern", { source: schema.pattern, flags: "" }))
    }
    return checks
  }

  function collectNumberChecks(schema: JsonSchema.JsonSchema): Array<Check> {
    const checks: Array<Check> = []
    addNumberCheck(checks, schema.minimum, "effect/schema/isGreaterThanOrEqualTo", "minimum")
    addNumberCheck(checks, schema.maximum, "effect/schema/isLessThanOrEqualTo", "maximum")
    addNumberCheck(checks, schema.exclusiveMinimum, "effect/schema/isGreaterThan", "exclusiveMinimum")
    addNumberCheck(checks, schema.exclusiveMaximum, "effect/schema/isLessThan", "exclusiveMaximum")
    addNumberCheck(checks, schema.multipleOf, "effect/schema/isMultipleOf", "divisor")
    return checks

View exact lines on GitHub

Excerpt truncated. Open the complete packages/effect/src/internal/schema/fromJsonSchemaDocument.ts:759-820 range.

Reproduction

pnpm test --run packages/effect/test/schema/representation/fromJsonSchemaDocument.test.ts

Observed failure: Focused contract assertion failed against 17f0b91, demonstrating: JSON Schema prefixItems loses maxItems semantics.

Implementation handoff

The initial reproduction tests on this branch are the regression specification for the implementation fix that should follow in this PR.

Start with the pinned implementation excerpts and the Why it happens analysis above.
Change the implementation so it satisfies the stated Expected behavior; do not weaken or remove the reproduction assertions.
Run the focused reproduction command(s) and confirm the observed failures become passing tests:

pnpm test --run packages/effect/test/schema/representation/fromJsonSchemaDocument.test.ts

Run the affected package's existing tests, then the repository lint and type checks before requesting review.

Audit provenance

Audit base: 17f0b91a243ccfe4a38d27debdc983adf434e738
Reproduction base: 17f0b91a243ccfe4a38d27debdc983adf434e738
Findings: effect-ff1a063c2ab0dc92
Initial patch: focused reproduction tests; implementation fix pending

Closes EFF-491

changeset-bot · 2026-08-05T21:29:57Z

🦋 Changeset detected

Latest commit: 8aea002

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 30 packages

Name	Type
effect	Patch
@effect/ai-anthropic	Patch
@effect/ai-openai	Patch
@effect/ai-openai-compat	Patch
@effect/ai-openrouter	Patch
@effect/atom-react	Patch
@effect/atom-solid	Patch
@effect/atom-vue	Patch
@effect/docgen	Patch
@effect/doctest	Patch
@effect/openapi-generator	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-deno	Patch
@effect/platform-node	Patch
@effect/platform-node-shared	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-pglite	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-node	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/vitest	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pullfrog

Important

The reproduction tests are correct and fail as expected against the current fromJsonSchemaDocument implementation, but this branch still needs the implementation fix before it can merge. CI is expected to remain red until collectArrayChecks and the tuple rest logic in packages/effect/src/internal/schema/fromJsonSchemaDocument.ts:759-820 are updated.

Reviewed changes

Added a focused regression test in packages/effect/test/schema/representation/fromJsonSchemaDocument.test.ts that pins the expected semantics for prefixItems combined with maxItems: both the bounded form (reject arrays longer than the bound) and the open form (allow trailing items after the prefix up to the bound) are covered.

^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Fix it ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

pullfrog

✅ No new issues found.

Reviewed changes

Implemented the fix in packages/effect/src/internal/schema/fromJsonSchemaDocument.ts: maxItems is now enforced as an array-length bound except when it exactly matches the length of a closed prefixItems tuple.
Added a changeset describing the runtime behavior fix.
The focused regression test added in the prior commit now passes.

^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

github-actions · 2026-08-06T00:33:02Z

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name	Current Size	Previous Size	Difference
`basic.ts`	6.92 KB	6.92 KB	0.00 KB (0.00%)
`batching.ts`	9.72 KB	9.72 KB	0.00 KB (0.00%)
`brand.ts`	6.60 KB	6.60 KB	0.00 KB (0.00%)
`cache.ts`	10.59 KB	10.59 KB	0.00 KB (0.00%)
`config.ts`	20.83 KB	20.83 KB	0.00 KB (0.00%)
`differ.ts`	19.67 KB	19.67 KB	0.00 KB (0.00%)
`http-client.ts`	21.50 KB	21.50 KB	0.00 KB (0.00%)
`logger.ts`	10.81 KB	10.81 KB	0.00 KB (0.00%)
`metric.ts`	8.86 KB	8.86 KB	0.00 KB (0.00%)
`optic.ts`	6.68 KB	6.68 KB	0.00 KB (0.00%)
`pubsub.ts`	14.86 KB	14.86 KB	0.00 KB (0.00%)
`queue.ts`	11.54 KB	11.54 KB	0.00 KB (0.00%)
`schedule.ts`	10.71 KB	10.71 KB	0.00 KB (0.00%)
`schema-class.ts`	19.38 KB	19.38 KB	0.00 KB (0.00%)
`schema-fromJsonSchemaDocument.ts`	29.24 KB	29.20 KB	+0.04 KB (+0.15%)
`schema-representation-roundtrip.ts`	25.51 KB	25.51 KB	0.00 KB (0.00%)
`schema-string-transformation.ts`	13.49 KB	13.49 KB	0.00 KB (0.00%)
`schema-string.ts`	11.03 KB	11.03 KB	0.00 KB (0.00%)
`schema-template-literal.ts`	15.30 KB	15.30 KB	0.00 KB (0.00%)
`schema-toArbitraryLazy.ts`	21.43 KB	21.43 KB	0.00 KB (0.00%)
`schema-toCodeDocument.ts`	23.87 KB	23.87 KB	0.00 KB (0.00%)
`schema-toCodecJson.ts`	18.64 KB	18.64 KB	0.00 KB (0.00%)
`schema-toEquivalence.ts`	18.47 KB	18.47 KB	0.00 KB (0.00%)
`schema-toFormatter.ts`	18.32 KB	18.32 KB	0.00 KB (0.00%)
`schema-toJsonSchemaDocument.ts`	22.09 KB	22.09 KB	0.00 KB (0.00%)
`schema-toRepresentation.ts`	19.01 KB	19.01 KB	0.00 KB (0.00%)
`schema.ts`	18.62 KB	18.62 KB	0.00 KB (0.00%)
`stm.ts`	12.59 KB	12.59 KB	0.00 KB (0.00%)
`stream.ts`	9.67 KB	9.67 KB	0.00 KB (0.00%)

pullfrog

✅ No new issues found.

Reviewed changes

Refined items: false handling so prefixItems tuples are closed with rest: [] instead of a Never rest element.
Extended maxItems redundancy detection to cover items: false when the bound is at least the prefix length.
Replaced the focused runtime behavior test with representation assertions inside the existing prefixItems test block.

^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

pullfrog

✅ No new issues found.

Reviewed changes

Simplified the isMaxItemsRedundant derivation in packages/effect/src/internal/schema/fromJsonSchemaDocument.ts by computing it from the existing isTupleClosed flag; the resulting behavior is unchanged but the logic is easier to follow.
Refactored packages/effect/test/schema/representation/fromJsonSchemaDocument.test.ts to split combined for-loop test cases into individual it blocks with more descriptive titles; assertions are preserved.

^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

fubhy added the audit Findings originating from the Effect runtime correctness audit label Aug 5, 2026

pullfrog Bot reviewed Aug 5, 2026

View reviewed changes

pullfrog Bot approved these changes Aug 5, 2026

View reviewed changes

tim-smart requested a review from gcanti August 5, 2026 23:45

effect-slopcop Bot added 4.0 bug Something isn't working labels Aug 6, 2026

gcanti changed the title ~~Fix jSON Schema prefixItems loses maxItems semantics~~ Fix JSON Schema prefixItems import semantics Aug 6, 2026

gcanti force-pushed the audit/repro-17f0b91a-json-schema-prefix-items-max-items branch 2 times, most recently from 0ee4c23 to 7bac144 Compare August 6, 2026 18:56

pullfrog Bot approved these changes Aug 6, 2026

View reviewed changes

fubhy and others added 3 commits August 7, 2026 07:43

Fix jSON Schema prefixItems loses maxItems semantics

b6c02d3

Fix JSON Schema prefixItems maxItems import

294e3bd

Fix JSON Schema prefixItems import semantics

8ac2a54

gcanti force-pushed the audit/repro-17f0b91a-json-schema-prefix-items-max-items branch from 7bac144 to 8ac2a54 Compare August 7, 2026 05:43

gcanti added 2 commits August 7, 2026 08:10

wip

4443e2c

refactor tests

8aea002

pullfrog Bot approved these changes Aug 7, 2026

View reviewed changes

gcanti merged commit d170596 into main Aug 7, 2026
20 checks passed

gcanti deleted the audit/repro-17f0b91a-json-schema-prefix-items-max-items branch August 7, 2026 06:59

effect-bot mentioned this pull request Aug 7, 2026

Version Packages (beta) #7103

Open

Navigation Menu

Uh oh!

Uh oh!

Fix JSON Schema prefixItems import semantics - #7060

Fix JSON Schema prefixItems import semantics#7060
gcanti merged 5 commits into
mainfrom
audit/repro-17f0b91a-json-schema-prefix-items-max-items

fubhy commented Aug 5, 2026 •

edited by tim-smart

Loading

Uh oh!

changeset-bot Bot commented Aug 5, 2026 •

edited

Loading

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot left a comment

Uh oh!

github-actions Bot commented Aug 6, 2026 •

edited

Loading

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

fubhy commented Aug 5, 2026 • edited by tim-smart Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

JSON Schema prefixItems loses maxItems semantics

What happens

Why it happens

Expected behavior

Relevant implementation

Reproduction

Implementation handoff

Audit provenance

Uh oh!

changeset-bot Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Analysis

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fubhy commented Aug 5, 2026 •

edited by tim-smart

Loading

changeset-bot Bot commented Aug 5, 2026 •

edited

Loading

github-actions Bot commented Aug 6, 2026 •

edited

Loading