Skip to content

Conversation

@adamrimon
Copy link

@adamrimon adamrimon commented Jan 26, 2026

Reasons for making this change

This PR adds a new ui:definitions property to uiSchema, enabling UI customizations for schema $ref references. This addresses a long-standing limitation where there was no way to define uiSchema for recursive schemas or to avoid repeating uiSchema for reused definitions.

Relates to #670 (Recursive references and uiSchema) and #477 (uiSchema for definitions)

The Problem:

// Schema with recursive definition
const schema = {
  definitions: {
    node: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        children: { type: 'array', items: { $ref: '#/definitions/node' } }
      }
    }
  },
  properties: { tree: { $ref: '#/definitions/node' } }
};

// Previously: No way to define uiSchema for recursive nodes
// uiSchema only applied to the first level, not deeper recursion

The Solution:

const uiSchema = {
  'ui:definitions': {
    '#/definitions/node': {
      name: { 'ui:placeholder': 'Enter node name' }
    }
  }
};
// Now applies at ALL recursion levels

Key features:

  • Define uiSchema once for schemas used in multiple places
  • Support for recursive schemas at any depth
  • Local overrides merge with and take precedence over definitions
  • Different uiSchema for same property names in different oneOf/anyOf branches
  • Keys use exact $ref paths (e.g., #/definitions/address or #/$defs/node)

Changes:

  • @rjsf/utils: Added expandUiSchemaDefinitions() and resolveUiSchema() functions, UiSchemaDefinitions type, and related constants
  • @rjsf/core: Integrated definition expansion at form initialization and runtime resolution in SchemaField
  • @rjsf/playground: Updated References sample to demonstrate the feature
  • @rjsf/docs: Added documentation for ui:definitions

Checklist

  • I'm updating documentation
  • I'm adding or updating code
    • I've added and/or updated tests. I've run npx nx run-many --target=build --exclude=@rjsf/docs && npm run test:update to update snapshots, if needed.
    • I've updated docs if needed
    • I've updated the changelog with a description of the PR
  • I'm adding a new feature
    • I've updated the playground with an example use of the feature

@adamrimon adamrimon changed the title feat(utils): Add ui:definitions for recursive and reusable uiSchema feat: Add ui:definitions for recursive and reusable uiSchema Jan 26, 2026
@adamrimon adamrimon marked this pull request as ready for review January 26, 2026 16:40
@adamrimon adamrimon changed the title feat: Add ui:definitions for recursive and reusable uiSchema feat: add ui:definitions for recursive and reusable uiSchema Jan 26, 2026
@adamrimon adamrimon marked this pull request as draft January 26, 2026 16:49
@adamrimon adamrimon force-pushed the feat/ui-definitions branch 3 times, most recently from 9d7ff2a to 39b915b Compare January 26, 2026 16:52
@adamrimon adamrimon marked this pull request as ready for review January 26, 2026 16:54
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.

2 participants