@rjsf/utils 6.2.5 → 6.3.0

package/lib/types.d.ts

@@ -413,6 +413,10 @@ export interface Registry<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
     readonly globalFormOptions: GlobalFormOptions;
     /** The optional global UI Options that are available for all templates, fields and widgets to access */
     globalUiOptions?: GlobalUISchemaOptions;
+    /** The optional uiSchema definitions extracted from the root uiSchema, keyed by `$ref` paths.
+     * Used to automatically apply uiSchema when a schema with a matching `$ref` is resolved.
+     */
+    uiSchemaDefinitions?: UiSchemaDefinitions<T, S, F>;
 }
 /** The properties that are passed to a `Field` implementation */
 export interface FieldProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any> extends GenericObjectType, RJSFBaseProps<T, S, F>, Pick<HTMLAttributes<HTMLElement>, Exclude<keyof HTMLAttributes<HTMLElement>, 'onBlur' | 'onFocus' | 'onChange'>> {
@@ -892,6 +896,14 @@ export type UIOptionsType<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
  * Handles both standard arrays and readonly arrays.
  */
 export type ArrayElement<A> = A extends readonly (infer E)[] ? E : A;
+/** Type describing the uiSchema definitions that can be applied to schemas referenced by `$ref`.
+ * Keys are the full `$ref` path (e.g., '#/$defs/node', '#/definitions/address').
+ * When a schema with a matching `$ref` is resolved, the corresponding uiSchema definition
+ * is automatically applied and merged with any local uiSchema overrides.
+ */
+export type UiSchemaDefinitions<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any> = {
+    [refPath: string]: UiSchema<T, S, F>;
+};
 /** Type describing the well-known properties of the `UiSchema` while also supporting all user defined properties,
  * starting with `ui:`.
  */
@@ -920,6 +932,12 @@ export type UiSchema<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends
      * When using a function, it receives the item data, index, and optionally the form context as parameters.
      */
     items?: UiSchema<ArrayElement<T>, S, F> | ((itemData: ArrayElement<T>, index: number, formContext?: F) => UiSchema<ArrayElement<T>, S, F>);
+    /** An object containing uiSchema definitions keyed by JSON Schema `$ref` paths.
+     * When a schema with a `$ref` is resolved, the corresponding uiSchema definition is automatically
+     * applied and merged with any local uiSchema overrides at that path.
+     * Keys must be full `$ref` paths (e.g., '#/$defs/node', '#/definitions/address').
+     */
+    'ui:definitions'?: UiSchemaDefinitions<T, S, F>;
 };
 /** A `CustomValidator` function takes in a `formData`, `errors`, `uiSchema` and `errorSchema` objects and returns the given `errors`
  * object back, while potentially adding additional messages to the `errors`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rjsf/utils",
-  "version": "6.2.5",
+  "version": "6.3.0",
   "main": "dist/index.js",
   "module": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -68,8 +68,8 @@
     "@x0k/json-schema-merge": "^1.0.2",
     "fast-uri": "^3.1.0",
     "jsonpointer": "^5.0.1",
-    "lodash": "^4.17.21",
-    "lodash-es": "^4.17.21",
+    "lodash": "^4.17.23",
+    "lodash-es": "^4.17.23",
     "react-is": "^18.3.1"
   },
   "devDependencies": {

package/src/constants.ts

@@ -45,6 +45,7 @@ export const UI_FIELD_KEY = 'ui:field';
 export const UI_WIDGET_KEY = 'ui:widget';
 export const UI_OPTIONS_KEY = 'ui:options';
 export const UI_GLOBAL_OPTIONS_KEY = 'ui:globalOptions';
+export const UI_DEFINITIONS_KEY = 'ui:definitions';
 
 /** The JSON Schema version strings
  */

package/src/createSchemaUtils.ts

@@ -38,9 +38,11 @@ import get from 'lodash/get';
  * providing a simplified set of APIs to the `@rjsf/core` components and the various themes as well. This class
  * implements the `SchemaUtilsType` interface.
  */
-class SchemaUtils<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>
-  implements SchemaUtilsType<T, S, F>
-{
+class SchemaUtils<
+  T = any,
+  S extends StrictRJSFSchema = RJSFSchema,
+  F extends FormContextType = any,
+> implements SchemaUtilsType<T, S, F> {
   rootSchema: S;
   validator: ValidatorType<T, S, F>;
   experimental_defaultFormStateBehavior: Experimental_DefaultFormStateBehavior;

package/src/index.ts

@@ -58,6 +58,7 @@ import pad from './pad';
 import parseDateString from './parseDateString';
 import rangeSpec from './rangeSpec';
 import replaceStringParameters from './replaceStringParameters';
+import resolveUiSchema, { expandUiSchemaDefinitions } from './resolveUiSchema';
 import schemaRequiresTrueValue from './schemaRequiresTrueValue';
 import shouldRender, { ComponentUpdateStrategy } from './shouldRender';
 import shouldRenderOptionalField from './shouldRenderOptionalField';
@@ -152,6 +153,8 @@ export {
   parseDateString,
   rangeSpec,
   replaceStringParameters,
+  resolveUiSchema,
+  expandUiSchemaDefinitions,
   schemaRequiresTrueValue,
   shallowEquals,
   shouldRender,

package/src/parser/ParserValidator.ts

@@ -29,9 +29,11 @@ export type SchemaMap<S extends StrictRJSFSchema = RJSFSchema> = {
  * the hashed value of the schema. NOTE: After hashing the schema, an $id with the hash value is added to the
  * schema IF that schema doesn't already have an $id, prior to putting the schema into the map.
  */
-export default class ParserValidator<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>
-  implements ValidatorType<T, S, F>
-{
+export default class ParserValidator<
+  T = any,
+  S extends StrictRJSFSchema = RJSFSchema,
+  F extends FormContextType = any,
+> implements ValidatorType<T, S, F> {
   /** The rootSchema provided during construction of the class */
   readonly rootSchema: S;
 

package/src/resolveUiSchema.ts

@@ -0,0 +1,156 @@
+import {
+  ADDITIONAL_PROPERTIES_KEY,
+  ALL_OF_KEY,
+  ANY_OF_KEY,
+  ITEMS_KEY,
+  ONE_OF_KEY,
+  PROPERTIES_KEY,
+  REF_KEY,
+} from './constants';
+import findSchemaDefinition from './findSchemaDefinition';
+import isObject from './isObject';
+import mergeObjects from './mergeObjects';
+import { FormContextType, GenericObjectType, Registry, RJSFSchema, StrictRJSFSchema, UiSchema } from './types';
+
+// Keywords where child schemas map to uiSchema at the SAME key
+const SAME_KEY_KEYWORDS = [ITEMS_KEY, ADDITIONAL_PROPERTIES_KEY] as const;
+
+// Keywords where child schemas are in an array, each mapping to uiSchema[keyword][i]
+const ARRAY_KEYWORDS = [ONE_OF_KEY, ANY_OF_KEY, ALL_OF_KEY] as const;
+
+/** Expands `ui:definitions` into the uiSchema by walking the schema tree and finding all `$ref`s.
+ * Called once at form initialization to pre-expand definitions into the uiSchema structure.
+ *
+ * For recursive schemas, expansion stops at recursion points to avoid infinite loops.
+ * Runtime resolution via `resolveUiSchema` handles these cases using registry definitions.
+ *
+ * @param currentSchema - The current schema node being processed
+ * @param uiSchema - The uiSchema at the current path
+ * @param registry - The registry containing rootSchema and uiSchemaDefinitions
+ * @param visited - Set of $refs already visited (to detect recursion)
+ * @returns - The expanded uiSchema with definitions merged in
+ */
+export function expandUiSchemaDefinitions<
+  T = any,
+  S extends StrictRJSFSchema = RJSFSchema,
+  F extends FormContextType = any,
+>(
+  currentSchema: S,
+  uiSchema: UiSchema<T, S, F>,
+  registry: Registry<T, S, F>,
+  visited: Set<string> = new Set(),
+): UiSchema<T, S, F> {
+  const { rootSchema, uiSchemaDefinitions: definitions } = registry;
+  let result = { ...uiSchema };
+  let resolvedSchema = currentSchema;
+
+  const ref = currentSchema[REF_KEY] as string | undefined;
+  const isRecursive = ref && visited.has(ref);
+
+  if (ref) {
+    visited.add(ref);
+
+    if (definitions && ref in definitions) {
+      result = mergeObjects(definitions[ref] as GenericObjectType, result as GenericObjectType) as UiSchema<T, S, F>;
+    }
+
+    if (isRecursive) {
+      return result;
+    }
+
+    try {
+      resolvedSchema = findSchemaDefinition<S>(ref, rootSchema as S);
+    } catch {
+      resolvedSchema = currentSchema;
+    }
+  }
+
+  // Process properties (each property maps to uiSchema[propName] - flattened)
+  const properties = resolvedSchema[PROPERTIES_KEY];
+  if (properties && isObject(properties)) {
+    for (const [propName, propSchema] of Object.entries(properties as Record<string, S>)) {
+      const propUiSchema = (result[propName] || {}) as UiSchema<T, S, F>;
+      const expanded = expandUiSchemaDefinitions(propSchema, propUiSchema, registry, new Set(visited));
+      if (Object.keys(expanded).length > 0) {
+        result[propName] = expanded;
+      }
+    }
+  }
+
+  // Process keywords where child maps to same key in uiSchema (items, additionalProperties)
+  for (const keyword of SAME_KEY_KEYWORDS) {
+    const subSchema = resolvedSchema[keyword];
+    if (subSchema && isObject(subSchema) && !Array.isArray(subSchema)) {
+      const currentUiSchema = result[keyword];
+      if (typeof currentUiSchema !== 'function') {
+        const subUiSchema = ((currentUiSchema as GenericObjectType) || {}) as UiSchema<T, S, F>;
+        const expanded = expandUiSchemaDefinitions(subSchema as S, subUiSchema, registry, new Set(visited));
+        if (Object.keys(expanded).length > 0) {
+          (result as GenericObjectType)[keyword] = expanded;
+        }
+      }
+    }
+  }
+
+  // Process array keywords (oneOf, anyOf, allOf) - each option maps to uiSchema[keyword][i]
+  for (const keyword of ARRAY_KEYWORDS) {
+    const schemaOptions = resolvedSchema[keyword];
+    if (Array.isArray(schemaOptions) && schemaOptions.length > 0) {
+      const currentUiSchemaArray = (result as GenericObjectType)[keyword];
+      const uiSchemaArray: UiSchema<T, S, F>[] = Array.isArray(currentUiSchemaArray) ? [...currentUiSchemaArray] : [];
+
+      let hasExpanded = false;
+      for (let i = 0; i < schemaOptions.length; i++) {
+        const optionSchema = schemaOptions[i] as S;
+        const optionUiSchema = (uiSchemaArray[i] || {}) as UiSchema<T, S, F>;
+        const expanded = expandUiSchemaDefinitions(optionSchema, optionUiSchema, registry, new Set(visited));
+        if (Object.keys(expanded).length > 0) {
+          uiSchemaArray[i] = expanded;
+          hasExpanded = true;
+        }
+      }
+
+      if (hasExpanded) {
+        (result as GenericObjectType)[keyword] = uiSchemaArray;
+      }
+    }
+  }
+
+  return result;
+}
+
+/** Resolves the uiSchema for a given schema, considering `ui:definitions` stored in the registry.
+ *
+ * This function is called at runtime for each field. It handles recursive schemas where the
+ * pre-expansion in `expandUiSchemaDefinitions` couldn't go deeper.
+ *
+ * When the schema contains a `$ref`, this function looks up the corresponding uiSchema definition
+ * from `registry.uiSchemaDefinitions` and merges it with any local uiSchema overrides.
+ *
+ * Resolution order (later sources override earlier):
+ * 1. `ui:definitions[$ref]` - base definition from registry
+ * 2. `localUiSchema` - local overrides at current path
+ *
+ * @param schema - The JSON schema (may still contain `$ref` for recursive schemas)
+ * @param localUiSchema - The uiSchema at the current path (local overrides)
+ * @param registry - The registry containing `uiSchemaDefinitions`
+ * @returns - The resolved uiSchema with definitions merged in
+ */
+export default function resolveUiSchema<
+  T = any,
+  S extends StrictRJSFSchema = RJSFSchema,
+  F extends FormContextType = any,
+>(schema: S, localUiSchema: UiSchema<T, S, F> | undefined, registry: Registry<T, S, F>): UiSchema<T, S, F> {
+  const ref = schema[REF_KEY] as string | undefined;
+  const definitionUiSchema = ref ? registry.uiSchemaDefinitions?.[ref] : undefined;
+
+  if (!definitionUiSchema) {
+    return localUiSchema || {};
+  }
+
+  if (!localUiSchema || Object.keys(localUiSchema).length === 0) {
+    return { ...definitionUiSchema };
+  }
+
+  return mergeObjects(definitionUiSchema as GenericObjectType, localUiSchema as GenericObjectType) as UiSchema<T, S, F>;
+}

package/src/types.ts

@@ -478,11 +478,16 @@ export interface Registry<T = any, S extends StrictRJSFSchema = RJSFSchema, F ex
   readonly globalFormOptions: GlobalFormOptions;
   /** The optional global UI Options that are available for all templates, fields and widgets to access */
   globalUiOptions?: GlobalUISchemaOptions;
+  /** The optional uiSchema definitions extracted from the root uiSchema, keyed by `$ref` paths.
+   * Used to automatically apply uiSchema when a schema with a matching `$ref` is resolved.
+   */
+  uiSchemaDefinitions?: UiSchemaDefinitions<T, S, F>;
 }
 
 /** The properties that are passed to a `Field` implementation */
 export interface FieldProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>
-  extends GenericObjectType,
+  extends
+    GenericObjectType,
     RJSFBaseProps<T, S, F>,
     Pick<HTMLAttributes<HTMLElement>, Exclude<keyof HTMLAttributes<HTMLElement>, 'onBlur' | 'onFocus' | 'onChange'>> {
   /** The FieldPathId of the field in the hierarchy */
@@ -896,7 +901,8 @@ export interface MultiSchemaFieldTemplateProps<
 
 /** The properties that are passed to a `Widget` implementation */
 export interface WidgetProps<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>
-  extends GenericObjectType,
+  extends
+    GenericObjectType,
     RJSFBaseProps<T, S, F>,
     Pick<HTMLAttributes<HTMLElement>, Exclude<keyof HTMLAttributes<HTMLElement>, 'onBlur' | 'onFocus' | 'onChange'>> {
   /** The generated id for this widget, used to provide unique `name`s and `id`s for the HTML field elements rendered by
@@ -1113,6 +1119,15 @@ export type UIOptionsType<
  */
 export type ArrayElement<A> = A extends readonly (infer E)[] ? E : A;
 
+/** Type describing the uiSchema definitions that can be applied to schemas referenced by `$ref`.
+ * Keys are the full `$ref` path (e.g., '#/$defs/node', '#/definitions/address').
+ * When a schema with a matching `$ref` is resolved, the corresponding uiSchema definition
+ * is automatically applied and merged with any local uiSchema overrides.
+ */
+export type UiSchemaDefinitions<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any> = {
+  [refPath: string]: UiSchema<T, S, F>;
+};
+
 /** Type describing the well-known properties of the `UiSchema` while also supporting all user defined properties,
  * starting with `ui:`.
  */
@@ -1148,6 +1163,12 @@ export type UiSchema<
     items?:
       | UiSchema<ArrayElement<T>, S, F>
       | ((itemData: ArrayElement<T>, index: number, formContext?: F) => UiSchema<ArrayElement<T>, S, F>);
+    /** An object containing uiSchema definitions keyed by JSON Schema `$ref` paths.
+     * When a schema with a `$ref` is resolved, the corresponding uiSchema definition is automatically
+     * applied and merged with any local uiSchema overrides at that path.
+     * Keys must be full `$ref` paths (e.g., '#/$defs/node', '#/definitions/address').
+     */
+    'ui:definitions'?: UiSchemaDefinitions<T, S, F>;
   };
 
 /** A `CustomValidator` function takes in a `formData`, `errors`, `uiSchema` and `errorSchema` objects and returns the given `errors`