Skip to content

fix(utils): guard non-string $ref values in makeAllReferencesAbsolute - #5459

Merged
heath-freenome merged 10 commits into
rjsf-team:v7from
charan-rathore:fix/ref-keyword-property-crash
Oct 9, 2026
Merged

heath-freenome merged 10 commits into
rjsf-team:v7from
charan-rathore:fix/ref-keyword-property-crash

Conversation

@charan-rathore

@charan-rathore charan-rathore commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Description

Fixes #5457 on v7, where the same walk no longer crashes but silently corrupts the schema instead.

makeAllReferencesAbsolute treated any property named $ref or $id as a reference: with an absolute root $id, a property named $ref was resolved as a URL and replaced with the string "https://example.com/[object%20Object]", losing that property's schema with nothing reported; a property named $id re-based its siblings; and $ref-looking strings inside const, default, enum and examples were rewritten, so a pre-filled default no longer matched the user's data.

The walk is now keyword-aware:

  • only a string $ref is resolved;
  • only a string $id re-bases the subtree;
  • const, default, enum and examples are instance data and are left untouched.

Checklist

  • I have read the documentation
  • In the case of a bug fix, I have added tests to prove that my fix is effective and existing tests are passing
  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have made corresponding changes to the documentation (CHANGELOG entry added)
  • My changes generate no new warnings (the 3 pre-existing @types/react errors on v7 are unchanged)
  • New and existing unit tests pass locally with my changes (findSchemaDefinition.test.ts: 130/130; the 10 failures in schemaParser/getWidget/hashForSchema/utcToLocal/AdditionalPropertyKeySelect/useAltDateWidgetProps are identical with and without this change on v7)
  • Any dependent changes have been merged and published in downstream modules

Tests added: property named $ref without and with an absolute root $id, a property named $id not re-basing siblings, and const/default/enum/examples data left intact. Note: the checkbox above is deliberately half-ticked - tests were added and the targeted suite passes, but the full v7 utils suite has pre-existing failures in this environment (listed above), so I am not claiming a full green run.

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Size limit report

Sizes are minified + brotli, measured by size-limit at 72d51c7.

A package listed twice is measured both as installed and, on the second row, as its own code with its dependencies excluded. Peer dependencies are always excluded.

Check Base PR Δ
@rjsf/antd 7.16 kB 7.16 kB =
@rjsf/antd (without dependencies) 6.75 kB 6.75 kB =
@rjsf/chakra-ui 18.79 kB 18.79 kB =
@rjsf/chakra-ui (without dependencies) 10.71 kB 10.71 kB =
@rjsf/core 29.11 kB 29.11 kB =
@rjsf/core/markdown 25.53 kB 25.53 kB =
@rjsf/core/testing 60.75 kB 60.75 kB =
@rjsf/core: Form 28.87 kB 28.87 kB =
@rjsf/daisyui 53.85 kB 53.85 kB =
@rjsf/daisyui (without dependencies) 11.00 kB 11.00 kB =
@rjsf/fluentui-rc 5.75 kB 5.75 kB =
@rjsf/mantine 14.34 kB 14.34 kB =
@rjsf/mantine (without dependencies) 9.98 kB 9.98 kB =
@rjsf/mui 6.56 kB 6.56 kB =
@rjsf/react-bootstrap 7.76 kB 7.76 kB =
@rjsf/react-bootstrap (without dependencies) 5.31 kB 5.31 kB =
@rjsf/shadcn 43.49 kB 43.49 kB =
@rjsf/shadcn (without dependencies) 9.11 kB 9.11 kB =
@rjsf/utils 29.18 kB 29.43 kB +0.25 kB
@rjsf/utils (without dependencies) 23.66 kB 23.91 kB +0.24 kB
@rjsf/utils: getUiOptions 0.65 kB 0.65 kB =
@rjsf/validator-ajv8 38.14 kB 38.14 kB =
@rjsf/validator-ajv8 (without dependencies) 2.66 kB 2.66 kB =
@rjsf/validator-ata 86.24 kB 86.24 kB =
@rjsf/validator-ata (without dependencies) 2.41 kB 2.41 kB =
@rjsf/validator-cfworker 7.22 kB 7.22 kB =
@rjsf/validator-cfworker (without dependencies) 2.30 kB 2.30 kB =

@heath-freenome heath-freenome left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for picking this up. The guard fixes the exact repro in #5457, but the root cause is still there: makeAllReferencesAbsolute treats keyword maps (properties, $defs, ...) and data keywords (const, default, ...) as schemas. Details are inline. Two points couldn't go inline:

findEmbeddedSchemaRecursive has the same flaw (findSchemaDefinition.ts:23). ID_KEY in schema is true for a $defs (or properties) entry named $id, so that entry's schema object is cast to a string and passed to UriResolver.equal() during a non-fragment $ref lookup under draft 2020-12. This is the $id twin of the $ref check fixed here.

Changelog. Please add an entry for the fix as the last bullet under ## @rjsf/utils in CHANGELOG.md.

@heath-freenome

Copy link
Copy Markdown
Member

A note on how this looks on v7, since it changes where the fix might best land.

v7 no longer crashes on these schemas, but only by luck. #5313 replaced fast-uri with a local resolveUri() wrapped in try/catch that returns ref unchanged when anything throws. The walk still passes it an object, and what saves it is that ref.startsWith('/') / base.startsWith('/') throws a TypeError on that object, which the catch swallows. I ran these against v7 (65fb46692):

Case main v7
Property named $ref, no root $id (the #5457 repro) throws uri.match is not a function schema comes back intact
Property named $ref, absolute root $id throws properties.$ref is silently replaced with the string "https://example.com/[object%20Object]", so that property's schema is lost and nothing reports it
Property named $id throws no crash, but $refs under that map aren't made absolute (lookups I tried still resolved via the root $id)
{ $ref: '#/a' } inside const/default rewritten still rewritten to https://example.com/root.json#/a

The absolute-$id case fails because new URL(obj, 'https://…') turns the object into the string [object Object] and resolves it as a path. The scheme is then https:, so resolveUri() returns before it reaches the startsWith that would have thrown.

So v7 needs this fix too, and on v7 the bug is silent schema corruption rather than a crash, which is arguably worse. Since v7 is where findSchemaDefinition.ts is actively changing (it no longer uses fast-uri), maybe the fix should move there: retarget this PR to v7, ideally with the keyword-aware walk suggested above, and a test that uses an absolute root $id (the current tests wouldn't catch the v7 case). If #5457 also needs fixing in a 6.x release, the small typeof guard here could still go to main on its own.

…ord-aware

On v7 a property named $ref with an absolute root $id no longer crashed,
but was silently rewritten to "[object Object]", losing the property's
schema; a property named $id re-based its siblings; and $ref-looking
strings inside const/default/enum/examples were rewritten, corrupting
instance data.

Only a string $ref is now resolved and only a string $id re-bases the
subtree, and the walk skips the data keywords const, default, enum and
examples. Adds tests for each case, including an absolute root $id.
Fixes rjsf-team#5457.

Signed-off-by: Charan Rathore <[email protected]>
@charan-rathore

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed comparison - the v7 table made the call clear. The PR is retargeted to v7 with the keyword-aware walk, and the base now shows one commit (7a27803) with three files.

On your four v7 cases: I reproduced each before the change (the no-root-$id case passed "by luck" exactly as you described, via the try/catch in resolveUri; the other three failed). After the change, all four pass: a property named $ref passes through intact with or without an absolute root $id, a property named $id no longer re-bases its siblings, and const/default/enum/examples keep their data untouched. The new tests include the absolute-root-$id shape you asked for.

On the two points that could not go inline: findEmbeddedSchemaRecursive on v7 already guards with typeof schema[ID_KEY] === 'string' before uriEqual, so the $id twin does not bite there; the changelog entry is added as the last bullet under ## @rjsf/utils.

Test runs: findSchemaDefinition.test.ts 130/130. The v7 utils suite has pre-existing failures here (schemaParser, getWidget, hashForSchema, utcToLocal, AdditionalPropertyKeySelect, useAltDateWidgetProps) - I diffed the failing test names with and without this change and the sets are identical, so nothing regressed, but I am not claiming a full green suite.

If #5457 should also be fixed in a 6.x release, I can put the small typeof guard on main as its own PR - say the word.

Comment thread CHANGELOG.md Resolved
@heath-freenome

Copy link
Copy Markdown
Member

@charan-rathore you have lint issues

@charan-rathore

Copy link
Copy Markdown
Contributor Author

@heath-freenome Both addressed:

  • Lint: the build (22.x) failure was no-continue in makeAllReferencesAbsolute. The loop is restructured without continue; the file is clean under the repo's pinned oxlint 1.85.0 and findSchemaDefinition.test.ts still passes 130/130.
  • Changelog: entry moved from CHANGELOG.md to CHANGELOG-v7.md as the last bullet under ## @rjsf/utils.

Pushed as a separate commit (446171e) so the review diff stays readable.

@heath-freenome

Copy link
Copy Markdown
Member

@charan-rathore now your tests are failing

The data-keyword skip means enum/default/const/examples arrays no
longer reach the items walk, so a test now pins that arrays under
other keywords (required, a type list) still pass non-object entries
through unchanged.

Signed-off-by: Charan Rathore <[email protected]>
@charan-rathore

Copy link
Copy Markdown
Contributor Author

@heath-freenome Found it - not the lint this time. The 100% branch-coverage gate failed on findSchemaDefinition.ts (98.75%): the DATA_KEYWORDS skip means enum/default/const/examples arrays no longer reach the items walk, and it turned out the : item branch of that walk's isObject(item) ternary was only ever exercised by enum arrays of primitives. No remaining test covered it.

Fixed by pinning the behavior with a test instead of reshaping the code: leaves non-object entries of schema arrays untouched covers required: ['link'] and a type: ['string', 'null'] list passing through unchanged while a sibling $ref still resolves. 131/131 in findSchemaDefinition.test.ts, and the file's only branch this test file alone doesn't cover is the draft-2019 allOf wrap, which the rest of the suite covers. oxlint 1.85.0 clean.

Pushed as 729e00e.

@heath-freenome heath-freenome left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for retargeting and for the thorough follow-ups. The $id crash and the rewriting of const/default data are fixed, and the tests now live in findSchemaDefinition.test.ts with the absolute-root-$id and $id-property shapes I asked for.

I ran another pass against 729e00eb. One thing is a regression, and I confirmed it by running createSchemaUtils + retrieveSchema against both v7 (65fb46692) and this branch: a property or $defs entry named default, const, enum or examples no longer has its $ref made absolute (comment on line 143). It comes from the denylist being checked against property names. The comment on line 120 explains why I think the walk that knows the schema's structure, from my first round, is still the right fix: it covers this, the lookup walker, and unknown keywords together. The rest are smaller.

Both makeAllReferencesAbsolute() and the embedded-schema lookup now
recurse only through the keywords that hold a schema, an array of
schemas, or a map of names to schemas, sharing the same keyword sets.
This fixes the regression where a property or $defs entry named
default, const, enum or examples lost $ref resolution, keeps instance
data and unknown keywords (vendor annotations, OpenAPI discriminator
maps) untouched in both walkers, and builds each node once, returning
the original object when nothing changed.

Signed-off-by: Charan Rathore <[email protected]>
@charan-rathore

Copy link
Copy Markdown
Contributor Author

Done in a41a2ce. Both walkers now share the structure-aware walk from your first-round comment: three keyword sets (single schema, array of schemas, map of names to schemas) drive the recursion, so property names are never mistaken for keywords and unknown keywords are never walked.

  • The regression is fixed: a property or $defs entry named default, const, enum or examples keeps its $ref resolution. Your exact repro resolves through createSchemaUtils + retrieveSchema again, pinned by an end-to-end test, plus a unit test covering all four names in both properties and $defs.
  • findEmbeddedSchemaRecursive walks the same sets, so a $id carried by a default or const value is no longer matched as an embedded schema resource (test added).
  • dependentSchemas is in the map set and covered, along with tuple items, prefixItems, draft-7 dependencies (schema values walked, string arrays left alone) and malformed keyword values.
  • Comment nits: the rule is stated once, on the keyword sets, and the before/after wording is out of the code comments and in the commit message.
  • The rebuild is linear now: each node is built once via Object.fromEntries and the original object is returned when nothing changed, pinned by identity tests.

Two decisions, as you framed them:

  • Non-string $ref: I kept the silent pass-through. This walk runs on every 2020-12 createSchemaUtils construction, so throwing there would break forms that render fine today because the bad $ref is never resolved. A clear error near the cause is the right end state, but it is a behavior change for its own PR.
  • Relative nested $id: agreed, follow-up issue, including the uriEqual side against the literal $id. I can file it once this lands.

Ran on my box: full @rjsf/utils suite (2540 passing; the 23 failures across getWidget, hashForSchema, AdditionalPropertyKeySelect, schemaParser, utcToLocal and useAltDateWidgetProps reproduce identically on 729e00e without my changes, so they are environmental here), findSchemaDefinition.ts at 100% lines/branches/functions/statements, oxlint --type-check clean.

@heath-freenome

Copy link
Copy Markdown
Member

@charan-rathore Thanks, the structure-aware walk is the right shape. One thing first: a41a2ce is on your fix/ref-keyword-property-crash-v7 branch, but this PR is opened from fix/ref-keyword-property-crash, which is still at 729e00e. So the PR doesn't show the new commit yet. Please push it to the PR's branch. Since the diff isn't in the PR, I'm leaving this round as one comment with links into a41a2ce instead of inline comments.

What I checked, and what holds up

  • Keyword sets: they match the 2020-12 and draft-7 keywords that hold subschemas, including tuple items, additionalItems, definitions, and dependencies with only its schema values walked. Nothing is wrongly included.
  • Last round's regression: fixed. A property or $defs entry named default or enum gets its $ref made absolute again.
  • Data values: default, const and x-* values are left alone. A $id inside a default is no longer found as an embedded schema.
  • Identity: the original object comes back when nothing changes.
  • Tests: the full @rjsf/utils suite passes with 100% coverage.
  • Non-string $ref: your reasoning for keeping the pass-through holds, since v7 already fails the same way at render. That's fine for this PR.
  • Relative nested $id: agreed as a follow-up.

1. Schemas kept under a keyword the walk doesn't know stop resolving, and the changelog doesn't say so

mapSubschemas and subschemas now skip keywords that aren't on the lists. That's what I asked for, and I still think the walk should work this way. It does change behavior for schemas kept under a container like an OpenAPI-style components block or an x-* key. Both of these resolve on v7 and throw with a41a2ce:

// A: a `$ref` inside a schema kept under `components` is no longer made absolute.
// The schema is reached by a JSON pointer, which the spec allows.
{
  $schema: 'https://json-schema.org/draft/2020-12/schema',
  $id: 'https://ex.com/root.json',
  properties: { a: { $ref: 'https://ex.com/lib.json#/components/Foo' } },
  $defs: {
    lib: {
      $id: 'https://ex.com/lib.json',
      components: {
        Foo: { type: 'object', properties: { x: { $ref: '#/components/Bar' } } },
        Bar: { type: 'string' },
      },
    },
  },
}
// retrieveSchema(root.properties.a) -> v7: resolves
//                                      a41a2ce2: "Could not find a definition for #/components/Bar"

// B: a `$id` resource kept under `components` is no longer found
{
  $schema: 'https://json-schema.org/draft/2020-12/schema',
  $id: 'https://ex.com/root.json',
  properties: { a: { $ref: 'https://ex.com/foo.json' } },
  components: { schemas: { Foo: { $id: 'https://ex.com/foo.json', type: 'string' } } },
}
// retrieveSchema(root.properties.a) -> v7: Foo
//                                      a41a2ce2: "Could not find a definition for https://ex.com/foo.json"

The changelog entry lists "unknown keywords all pass through untouched" as part of the fix. Please:

  • state it as a breaking change, so people with bundles like these know to move the schemas under $defs;
  • add tests that pin both cases, so the behavior is clearly intended.

2. Symbol keys are dropped when a node is rebuilt

Object.fromEntries(entries) is built from Object.entries(schema), which leaves out symbol keys. The { ...result } spread on v7 kept them. RJSF_REF_KEY, ADDITIONAL_PROPERTY_FLAG and GUESSED_TYPE_FLAG are Symbols. So a schema that carries one and has a $ref rewritten somewhere below it loses the flag: c[sym] is 2 on v7 and undefined with a41a2ce. Spreading the original node and overwriting only the changed keys would keep them. A test with a symbol-keyed node would pin that.

3. The tests don't pin the keyword sets

A Set.has check has no branch for coverage to catch. So removing any of if/then/else, contains, propertyNames, unevaluatedItems, unevaluatedProperties or contentSchema from SUBSCHEMA_KEYWORDS still passes at 100% coverage. An it.each over every keyword in each of the three sets, for both walkers, would pin them:

  • a $ref under the keyword is made absolute;
  • a $id under the keyword is found.

4. The keyword-shape check is written out twice

The check for "map, array or single subschema", along with the extra || key === DEPENDENCIES_KEY and || key === ITEMS_KEY cases, appears in both subschemas and mapSubschemas. If a keyword is added to one and not the other, the two walkers disagree again, which is the drift this rework set out to remove. A single helper, such as keywordShape(key, value): 'map' | 'array' | 'single' | undefined, used by both, would remove the duplicated checks. The dependencies and tuple-items cases would then live in one place.

5. Minor: some nodes are still built more than once

A node whose subschemas and its own $ref both change is built twice: once by Object.fromEntries in mapSubschemas, then again by the { ...result, [REF_KEY]: absolute } spread. Map and array containers are also built and thrown away when nothing in them changed. This is low priority. If you fix #2 by spreading only when something changed, it's worth folding in.

6. Optional: the same mix-up of keywords and property names in the lookup path (already on v7)

findSchemaDefinitionRecursive reads current[REF_KEY] without a string check. So findSchemaDefinitionRecursive('#/properties', { properties: { $ref: { type: 'string' } } }) throws ref.startsWith is not a function on both v7 and a41a2ce. A typeof nextRef === 'string' check would match the guard you added in the walker. This isn't required for this PR, but it's the same #5457 mix-up and a one-line change.

…ope breaking change

Review follow-up: both walkers now classify entries through one keywordShape helper so their keyword handling cannot drift apart; mapSubschemas rebuilds by spreading the original node and overwriting only the changed keys, so symbol keys (RJSF_REF_KEY and friends) survive and unchanged containers are no longer copied; the $ref rewrite folds into the same rebuild instead of a second spread. findSchemaDefinition skips a non-string $ref the same way the walker does. The changelog now declares the breaking change: schemas kept under unknown keywords such as an OpenAPI-style components block are no longer part of the bundle and belong under $defs. Tests pin every keyword of the three sets for both walkers, the two unknown-keyword cases, symbol-key survival, and the non-string $ref lookup.

Signed-off-by: Charan Rathore <[email protected]>
@charan-rathore

Copy link
Copy Markdown
Contributor Author

Pushed: a41a2ce plus the follow-up for this round (0fb80ff) are now on fix/ref-keyword-property-crash, so the diff shows in the PR.

All six points are in:

  1. The changelog now declares the breaking change: schemas under a keyword the walk does not know (an OpenAPI-style components block, an x-* key) are no longer part of the bundle, with the advice to move them under $defs/definitions. Both of your examples are pinned as tests, including the retrieveSchema throw for #/components/Bar.
  2. Rebuilds now spread the original node and overwrite only the keys that changed, so symbol keys survive. Pinned with ADDITIONAL_PROPERTY_FLAG on a node whose subtree gets a $ref rewritten.
  3. Every keyword in the three sets is pinned by an it.each, for both directions: a $ref under the keyword is made absolute, and an $id under it is found. Dropping one from a set now fails a test.
  4. Both walkers classify entries through one keywordShape helper; the dependencies and tuple-items cases live there once.
  5. Folded in: unchanged containers are no longer copied, and the $ref rewrite rides the same rebuild instead of a second spread.
  6. Added the typeof guard in findSchemaDefinitionRecursive with your repro as a test (it threw ref.startsWith is not a function before).

Verification: full @rjsf/utils suite green (2637 tests; one pre-existing utcToLocal failure in my sandbox's timezone, excluded), findSchemaDefinition.ts at 100% statements/branches/functions/lines, oxlint and oxfmt clean. The symbol and guard tests fail on a41a2ce and pass with this commit.

… into fix/ref-keyword-property-crash-v7

Signed-off-by: Charan Rathore <[email protected]>

# Conflicts:
#	CHANGELOG-v7.md

@heath-freenome heath-freenome left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for getting both commits onto the PR's branch and for working through every round-3 point. I checked the head (bb0fa1f3) against v7 with the ajv8 validator, and these all hold up:

  • the components/x-* breaking-change entry and the tests that pin both examples;
  • symbol keys surviving a rebuild;
  • the it.each over every keyword set, in both directions;
  • the shared keywordShape helper;
  • nodes no longer being rebuilt twice.

What's left is small. The main item is my fault: the typeof check I suggested for findSchemaDefinitionRecursive in round 3 (#6) doesn't help any real caller, and it changes how an empty $ref is handled. Please revert it (comment on line 322). The rest is documentation and a couple of nits.

Separately, withIdRefPrefix() and the walkers in schemaHasNestedConditional.ts and parser/schemaParser.ts have the same mix-up between keywords and data, each with its own keyword list. Sharing keywordShape/subschemas with them is worth a follow-up issue. I'd keep it out of this PR.

Comment thread CHANGELOG-v7.md Resolved
Comment thread CHANGELOG-v7.md Outdated
- `omitExtraData()` reads what a key its object's `properties` don't name requires from the merge of the patterns describing it rather than off the `allOf` wrapping them, and keeps such a key where the object's own `required` names it. The wrapper requires nothing, so a pattern-matched object whose only child was required and empty was pruned the way an all-optional one is, and a required key described by a `patternProperties` pattern, an `additionalProperties` or an `unevaluatedProperties` was dropped from the data the form then reports it as missing from, for a key the user has a field for and has filled in as far as it asks them to ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- `omitExtraData()` drops a value whose `allOf` merges to `false`, which is what an `allOf` holding a `false` merges to and what no value satisfies. The merged boolean answered nothing to the keyword handlers that read it, so the value reached the fallback that returns it as it was written, keeping every key the other entries describe nothing about ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- Fixed `makeAllReferencesAbsolute()` treating any property named `$ref` or `$id` as a reference: a schema map or data value with a property named `$ref` crashed resolution on `main` and was silently rewritten to `"[object Object]"` on `v7`, and a property named `$id` re-based its siblings, fixing [#5457](https://github.com/rjsf-team/react-jsonschema-form/issues/5457). The walk now follows the schema's structure, recursing only through the keywords that hold a schema, an array of schemas or a map of names to schemas: only a string `$ref` is resolved, only a string `$id` re-bases its subtree, and instance data, schema-map entries named like data keywords, and unknown keywords all pass through untouched. The lookup path of `findSchemaDefinition()` skips a non-string `$ref` the same way
- **BREAKING CHANGE:** Because the `makeAllReferencesAbsolute()` walk no longer looks inside unknown keywords, schemas kept under a container it does not know, such as an OpenAPI-style `components` block or an `x-*` vendor key, are no longer treated as part of the bundle: a `$ref` inside one is no longer made absolute, and an `$id` declared there is no longer found as an embedded schema, so resolution that reached them before now throws `Could not find a definition for ...`. Move those schemas under `$defs` (draft 2020-12) or `definitions` (draft 7) so the walk reaches them

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please also add this break to packages/docs/docs/migration-guides/v7.x upgrade guide.md, including the advice to move those schemas under $defs/definitions. People upgrading read the guide.

One more detail is worth stating there. AJV collects $ids by walking every key (traverse(schema, { allKeys: true }) in ajv/dist/compile/resolve.js), so it still finds an $id kept under components or x-*. A form whose schema relies on that passes validation but throws Could not find a definition for … when it renders. That mismatch is the clearest symptom someone upgrading would see, so naming it in the guide will help them connect it to this change.

The typeof check on a found node's own $ref changed how an empty $ref
is handled: v6's falsy check skips it, the string check follows it and
throws. Reverted. It also helped no real caller, since retrieveSchema
on a reference to such a node fails the same way it did before. An
empty-$ref test pins the restored behavior in place of the dropped
non-string one.

The keyword sets are now the complete list of what the walkers recurse
through: items joins the array set and dependencies the map set, and
the Array.isArray/isObject checks tell the shapes apart, so the sets
match the it.each lists in the test exactly. unevaluatedProperties
reads the shared constant. The changelog entry names 6.x and 7.0 in
place of branch names, and the v7 upgrade guide gains the
components/x-* breaking change, including the AJV all-keys mismatch:
validation still finds an $id there while rendering throws.

Signed-off-by: Charan Rathore <[email protected]>
@charan-rathore

Copy link
Copy Markdown
Contributor Author

Thanks - and no worries on the round trip, the revert is the right call. I reproduced the empty-$ref regression before touching it: the typeof check follows '' and throws Could not find a definition for . where v7's falsy check returned the node. The reverted behavior now has a test pinning it.

In this round:

  • findSchemaDefinition is back to if (nextRef); the test pinning the non-string skip is replaced by one for the empty-$ref case.
  • The keyword sets are now the complete list: items joins the array set and dependencies the map set, the Array.isArray/isObject checks tell the shapes apart, and the it.each lists in the test match the sets exactly. unevaluatedProperties reads the shared constant.
  • Changelog: the findSchemaDefinition sentence is gone, and the entry now says 6.x crashed while 7.0 silently rewrites to "[object Object]".
  • The components/x-* breaking change is now in the v7 upgrade guide too, with the $defs/definitions advice and the AJV all-keys mismatch called out: validation still finds an $id there while rendering throws Could not find a definition for ....

Agreed on keeping withIdRefPrefix() and the schemaHasNestedConditional/schemaParser walkers out of this PR - sharing keywordShape with them belongs in a follow-up issue.

Verified locally: findSchemaDefinition.test.ts 192/192, full @rjsf/utils suite 2722/2723 (the one failure is utcToLocal, which fails on a pristine checkout in this environment too). Lint and format ran through the repo's pre-commit hook.

@heath-freenome heath-freenome left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this round covers everything from round 4. I checked a5e8fdf8 against v7 with the ajv8 validator:

  • findSchemaDefinitionRecursive is back to if (nextRef), and the empty-$ref test pins it;
  • the keyword sets are the complete list, and the it.each lists match them;
  • UNEVALUATED_PROPERTIES_KEY is used;
  • the upgrade guide covers the components/x-* break, including the AJV mismatch;
  • the full @rjsf/utils suite passes with 100% coverage, and the #5457 repro works through retrieveSchema() and getDefaultFormState().

What's left is three small wording nits. The changelog one is my fault, from how I phrased my request last round. Once those are in, this is ready from my side.

A reminder on the relative nested $id we agreed to treat as a follow-up: if there's no issue for it yet, please open one so it doesn't get lost.

Comment thread CHANGELOG-v7.md Outdated
- `retrieveSchema()` reads the rest of a `dependencies` entry spelled as a `$ref` without the `oneOf` behind that reference, as it does for an entry that spells its branches inline, when deciding which keys an `anyOf`/`oneOf` option renders. Read through the reference the branches were options of their own, so a name every one of them declares counted as a name the form renders even where no single branch qualified and `withExactlyOneSubschema()` merged none of the `oneOf` in, leaving the value it holds no field at all ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- `omitExtraData()` reads what a key its object's `properties` don't name requires from the merge of the patterns describing it rather than off the `allOf` wrapping them, and keeps such a key where the object's own `required` names it. The wrapper requires nothing, so a pattern-matched object whose only child was required and empty was pruned the way an all-optional one is, and a required key described by a `patternProperties` pattern, an `additionalProperties` or an `unevaluatedProperties` was dropped from the data the form then reports it as missing from, for a key the user has a field for and has filled in as far as it asks them to ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- `omitExtraData()` drops a value whose `allOf` merges to `false`, which is what an `allOf` holding a `false` merges to and what no value satisfies. The merged boolean answered nothing to the keyword handlers that read it, so the value reached the fallback that returns it as it was written, keeping every key the other entries describe nothing about ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- Fixed `makeAllReferencesAbsolute()` treating any property named `$ref` or `$id` as a reference: a schema map or data value with a property named `$ref` crashed resolution in 6.x and is silently rewritten to `"[object Object]"` in 7.0, and a property named `$id` re-based its siblings, fixing [#5457](https://github.com/rjsf-team/react-jsonschema-form/issues/5457). The walk now follows the schema's structure, recursing only through the keywords that hold a schema, an array of schemas or a map of names to schemas: only a string `$ref` is resolved, only a string `$id` re-bases its subtree, and instance data, schema-map entries named like data keywords, and unknown keywords all pass through untouched.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"is silently rewritten to "[object Object]" in 7.0": this one is my fault. I asked you to describe "what 7.0 does now" and meant the fixed behavior. No 7.x release has been published, so the [object Object] rewrite never reached anyone, and a reader of the 7.0 notes would take it for a 7.0 bug. Please describe only the change from 6.x: a property named $ref crashed resolution, a property named $id re-based its siblings, and both are fixed now.

DEPENDENCIES_KEY,
]);

/** Classifies one of a schema's own entries by the shape of the subschema(s) its keyword's value holds: a

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most of this docblock repeats the one on the keyword sets at line 97: that map names are data, so a property named default or enum isn't mistaken for the keyword, and the "every other keyword…" list. If the sets change, one copy will go stale. Please keep that explanation on the sets and limit this docblock to what's specific to the classification: tuple items sits in both the single set and the array set, and the Array.isArray/isObject checks tell them apart and drop a string-array dependencies entry.

}

/** Applies `fn` to the direct subschemas of `schema` (following the keyword shapes above), rebuilding only
* the containers whose contents changed. `extraChanges` carries updates to the schema's own data keys, folded

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: "folded into the same rebuild rather than a second copy" describes how this compares with the earlier code. The same goes for "rather than spreading the node a second time" on line 261. The repo's CLAUDE.md asks that before/after commentary go in the commit message rather than in code comments, because a reader of the shipped code has no "second copy" to compare against. Please say what extraChanges does and drop the comparison.

@heath-freenome

Copy link
Copy Markdown
Member

@charan-rathore I will approved after the last round of feedback is resolved

The 7.0 rewrite claim never shipped, so the changelog now describes
only the change from 6.x. The keywordShape docblock keeps what is
specific to classification and leaves the keyword-versus-data
explanation to the sets above it, and the two before/after comparisons
move out of code comments per the repo's CLAUDE.md.

Signed-off-by: Charan Rathore <[email protected]>
@charan-rathore

Copy link
Copy Markdown
Contributor Author

Thanks - all three nits are in (c184390):

  • Changelog describes only the change from 6.x now: a property named $ref crashed resolution, a property named $id re-based its siblings, both fixed. The 7.0 sentence is gone.
  • The keywordShape docblock keeps only what is specific to the classification (tuple items in both sets, the Array.isArray/isObject disambiguation, the string-array dependencies drop); the keyword-versus-data explanation lives on the sets alone.
  • Both before/after comparisons are out of the code comments; extraChanges and the $ref rewrite now just say what they do.

findSchemaDefinition.test.ts still 192/192.

Both follow-up issues are filed: #5466 for sharing keywordShape with withIdRefPrefix() and the schemaHasNestedConditional/schemaParser walkers, and #5467 for the relative nested $id, including the uriEqual side against the literal $id.

@heath-freenome heath-freenome left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working through all six rounds, and for filing #5466 and #5467. The walk now follows the schema's structure, the breaking change is declared and pinned, and CI passes on Node 22, 24 and 26. Approving.

The three inline comments are about wording and aren't blocking. They're quick to do here or in a follow-up, whichever you prefer. I'd do the first one before 7.0 ships, because the upgrade guide currently tells some users to make a change they don't need.

Comment thread CHANGELOG-v7.md Outdated
- `omitExtraData()` reads what a key its object's `properties` don't name requires from the merge of the patterns describing it rather than off the `allOf` wrapping them, and keeps such a key where the object's own `required` names it. The wrapper requires nothing, so a pattern-matched object whose only child was required and empty was pruned the way an all-optional one is, and a required key described by a `patternProperties` pattern, an `additionalProperties` or an `unevaluatedProperties` was dropped from the data the form then reports it as missing from, for a key the user has a field for and has filled in as far as it asks them to ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- `omitExtraData()` drops a value whose `allOf` merges to `false`, which is what an `allOf` holding a `false` merges to and what no value satisfies. The merged boolean answered nothing to the keyword handlers that read it, so the value reached the fallback that returns it as it was written, keeping every key the other entries describe nothing about ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- Fixed `makeAllReferencesAbsolute()` treating any property named `$ref` or `$id` as a reference: a schema map or data value with a property named `$ref` crashed resolution in 6.x, and a property named `$id` re-based its siblings, fixing [#5457](https://github.com/rjsf-team/react-jsonschema-form/issues/5457). The walk now follows the schema's structure, recursing only through the keywords that hold a schema, an array of schemas or a map of names to schemas: only a string `$ref` is resolved, only a string `$id` re-bases its subtree, and instance data, schema-map entries named like data keywords, and unknown keywords all pass through untouched.
- **BREAKING CHANGE:** Because the `makeAllReferencesAbsolute()` walk no longer looks inside unknown keywords, schemas kept under a container it does not know, such as an OpenAPI-style `components` block or an `x-*` vendor key, are no longer treated as part of the bundle: a `$ref` inside one is no longer made absolute, and an `$id` declared there is no longer found as an embedded schema, so resolution that reached them before now throws `Could not find a definition for ...`. Move those schemas under `$defs` (draft 2020-12) or `definitions` (draft 7) so the walk reaches them

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: this entry and the upgrade guide section (line 1326) say a $ref inside an unknown container "is no longer made absolute … so resolution that reached them before now throws". That's broader than what actually breaks. I ran this at c1843909 with the ajv8 validator:

createSchemaUtils({ validator }, {
  $schema: 'https://json-schema.org/draft/2020-12/schema',
  $id: 'https://example.com/root.json', // same result without $id
  type: 'object',
  properties: { a: { $ref: '#/components/schemas/Foo' } },
  components: { schemas: {
    Foo: { type: 'object', properties: { x: { $ref: '#/components/schemas/Bar' } } },
    Bar: { type: 'string' },
  } },
}).retrieveSchema({ $ref: '#/components/schemas/Foo' });
// -> { type: 'object', properties: { x: { type: 'string' } } }

A relative $ref left as written is still resolved against the root, so the usual OpenAPI layout, with components at the root and #/components/... refs, keeps working. Only the two cases your tests pin break:

  • an $id declared inside the container;
  • a relative $ref inside it that depends on a nested $id above it, like the lib.json case.

Could the entry and the guide name those two cases? Otherwise people with a root-level components block will move it under $defs when they don't need to.

Comment thread CHANGELOG-v7.md Outdated
- `retrieveSchema()` reads the rest of a `dependencies` entry spelled as a `$ref` without the `oneOf` behind that reference, as it does for an entry that spells its branches inline, when deciding which keys an `anyOf`/`oneOf` option renders. Read through the reference the branches were options of their own, so a name every one of them declares counted as a name the form renders even where no single branch qualified and `withExactlyOneSubschema()` merged none of the `oneOf` in, leaving the value it holds no field at all ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- `omitExtraData()` reads what a key its object's `properties` don't name requires from the merge of the patterns describing it rather than off the `allOf` wrapping them, and keeps such a key where the object's own `required` names it. The wrapper requires nothing, so a pattern-matched object whose only child was required and empty was pruned the way an all-optional one is, and a required key described by a `patternProperties` pattern, an `additionalProperties` or an `unevaluatedProperties` was dropped from the data the form then reports it as missing from, for a key the user has a field for and has filled in as far as it asks them to ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- `omitExtraData()` drops a value whose `allOf` merges to `false`, which is what an `allOf` holding a `false` merges to and what no value satisfies. The merged boolean answered nothing to the keyword handlers that read it, so the value reached the fallback that returns it as it was written, keeping every key the other entries describe nothing about ([#5330](https://github.com/rjsf-team/react-jsonschema-form/issues/5330))
- Fixed `makeAllReferencesAbsolute()` treating any property named `$ref` or `$id` as a reference: a schema map or data value with a property named `$ref` crashed resolution in 6.x, and a property named `$id` re-based its siblings, fixing [#5457](https://github.com/rjsf-team/react-jsonschema-form/issues/5457). The walk now follows the schema's structure, recursing only through the keywords that hold a schema, an array of schemas or a map of names to schemas: only a string `$ref` is resolved, only a string `$id` re-bases its subtree, and instance data, schema-map entries named like data keywords, and unknown keywords all pass through untouched.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking, two small corrections to the 6.x description, checked against main's walker:

  • In 6.x only a property named $ref with an object value crashed (UriResolver.resolve received an object). A data value holding a string $ref, such as default: { $ref: '#/a' }, didn't crash. It was silently rewritten to the absolute URI, so the form pre-filled changed data. That's worth saying, because it changed users' data without any error.
  • The lookup side is fixed too, but the entry doesn't mention it: an $id inside default/const data is no longer matched as an embedded schema. Your "does not match a $id carried by instance data" test pins this.

} as unknown as RJSFSchema;
expect(() => findSchemaDefinition(FOO_ID, bundle)).toThrow(`Could not find a definition for ${FOO_ID}`);
});
it('leaves a `$ref` inside an unknown-keyword container relative, so resolution no longer reaches it', () => {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: "no longer reaches it" here and "un-rewritten" on line 1016 describe the change rather than the behavior, the same wording we took out of the code comments last round. Something like "so resolution cannot reach it" and "the relative inner $ref" says the same thing without referring to earlier code.

@charan-rathore

Copy link
Copy Markdown
Contributor Author

Thanks for the careful reviews across all six rounds. I'll pick up the three wording nits on this PR now, starting with the changelog/upgrade-guide one so it's right before 7.0 ships.

Review nits on rjsf-team#5459: the changelog entry and upgrade guide said
resolution reaching a container's schemas now throws, but a relative
$ref left as written still resolves against the root, so the usual
root-level components layout keeps working. Name the two cases that
actually break (an $id declared inside the container, a relative
$ref depending on a nested $id above it), correct the 6.x
description (object-valued $ref crashed; a string $ref in data was
silently rewritten), and note the $id-in-data lookup fix. Reword two
test descriptions to state behavior, not the change.

Signed-off-by: Charan Rathore <[email protected]>
@charan-rathore

Copy link
Copy Markdown
Contributor Author

All three nits are in 72d51c7:

  • The changelog entry and the upgrade guide now say a $ref inside an unknown container is left as written, and that the usual root-level components layout with #/components/... refs keeps working. I reproduced your snippet on the branch before rewriting: retrieveSchema({ $ref: '#/components/schemas/Foo' }) returns { type: 'object', properties: { x: { type: 'string' } } }, so the two cases that break are named as the ones that throw: an $id declared inside the container, and a relative $ref depending on a nested $id above it.
  • The 6.x description now says only an object-valued $ref crashed, that a string $ref in data was silently rewritten (changing pre-filled data with no error), and that the $id-in-data lookup is fixed too.
  • Both test descriptions reworded to state behavior.

findSchemaDefinition.test.ts passes 192/192.

@heath-freenome
heath-freenome merged commit 4bda656 into rjsf-team:v7 Oct 9, 2026
6 checks passed
jimmycallin added a commit that referenced this pull request Oct 16, 2026
…5555)

* test(utils): pin #5457, a property named $ref under a 2020-12 root

A key under `properties` names a property of the data, not a keyword. Before #5459, `createSchemaUtils()` rewrote a property named `$ref` under an absolute root `$id` as if it were a reference. The two tests use the schema from the issue and the `$defs` shape its reporter generates with Zod. Both fail on 61a2c05, the commit before #5459, and pass on v7.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* test(utils): resolve the #5457 tests from the rewritten root schema

Co-Authored-By: Claude Opus 5.5 <[email protected]>

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
@heath-freenome heath-freenome mentioned this pull request Nov 13, 2026
Merged
8 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

uri.match is not a function when a property is named $ref under draft 2020-12

2 participants