Extend `ui:emptyValue` and complement it with `ui:initialValue` and `ui:required`

[adamrimon]

Prerequisites

• I have read the documentation

What theme are you using?

utils

Is your feature request related to a problem? Please describe.

When the JSON Schema is shared across forms, comes from an API, or is auto-generated, you can't easily set per-form defaults or change which fields are required without touching the schema itself.

Example: a "person details" schema has a country field. A US-only form wants to hide it and pre-fill "US". Right now you'd have to modify the schema or stuff the value into formData, which mixes up user input with form setup.

Describe the solution you'd like

Two new uiSchema properties:

ui:initialValue: Pre-fills a field on initial render and after reset. Takes priority over schema.default.

This is about what the user sees, while the existing ui:emptyValue is about what gets stored when a field is blank. They're complementary:

• ui:initialValue pre-fills the field on render and reset, keeping it from being blank
• ui:emptyValue is stored in formData whenever the field is blank, whether from initial state, user clearing, or reset

This means ui:emptyValue would be extended from its current scope (only kicks in when a user clears a widget) to kick in whenever a field is blank, regardless of why.

ui:required: Overrides the schema's required for a field, but only on the UI side.

• true: makes a non-required field required (validation + asterisk)
• false: hides the required asterisk on a schema-required field

Importantly, ui:required only affects the form-level required check and the UI indicator. It does not change the JSON Schema itself, so schema-level validation still runs as-is. If the schema says a field is required and it's left empty, validation will still fail regardless of ui:required: false. The intended use for false is when the field is guaranteed to have a value through initialValue or emptyValue.

const uiSchema = {
  country: {
    "ui:widget": "hidden",
    "ui:initialValue": "US",
    "ui:required": false,  // hidden + pre-filled, no need to show as required
  },
  nickname: {
    "ui:required": true,   // required in this form, even if the schema doesn't say so
  },
};

Worth noting: ui:required: false on a schema-required field without initialValue or emptyValue is misleading, since the UI says "optional" but validation still fails. A console.warn for this would be nice, similar to the existing warning for deprecated ui:widget object syntax.

Describe alternatives you've considered

ui:emptyValue partly covers the defaults use case, but only on the data side. It doesn't pre-fill the field for the user and doesn't help with overriding required.

[x0k]

In my opinion, this is fairly niche functionality.

You can use the mergeSchemas function to achieve a similar result.

const schema = mergeSchemas(externalSchema, {
  properties: {
    country: {
      default: "US"
    },
  },
  required: ["nickname"]
})

If your schema uses tuples or combination keywords, you will need to write a function that accounts for them yourself.

[adamrimon]

I might agree that ui:required is more niche, but the core of this request is about extending ui:emptyValue. A common pattern is having the JSON Schema auto-generated from the data model while manually maintaining a uiSchema layer for each form. In that setup, you need to control what gets stored when a field is blank without touching the schema. That's why ui:emptyValue was added in the first place. But right now it only works when the user actively clears a field. If the user never touches it, there's no equivalent. The main suggestion here is to extend ui:emptyValue to apply whenever a field is blank, regardless of the reason.

ui:initialValue and ui:required complement that by controlling the UX side - what the user sees initially, and whether the field shows as required.

As for mergeSchemas(), using it means creating modified schema copies per form, which is exactly what the uiSchema layer is meant to avoid. The schema should describe the data model, the uiSchema should describe the UX behavior.