[V2] Add schema-validating formOptions helpers with a named schema output

[lucas-dtrn]

I am using @tanstack/react-form@2.0.0-alpha.2 and would like to propose a schema-backed options helper that combines type inference and runtime validation.

Current behavior

strictSchema and looseSchema use the supplied Standard Schema for type inference, but do not register it as a validator.

A schema-backed form therefore requires passing the same schema twice:

const form = useForm(
  formOptions.looseSchema(schema, {
    defaultValues: {
      firstName: 'John',
      lastName: 'Doe',
    },
    validators: [
      {
        triggers: [],
        run: schema,
      },
    ],
    onSubmit: ({ schemaOutputs: [validatedValue] }) => {
      return submit(validatedValue);
    },
  }),
);

This has two drawbacks:

1. It is easy to assume that looseSchema(schema, ...) also enables runtime validation.
2. The primary schema output is accessed through its validator index. Adding or reordering validators can change that index.

Proposed helpers

Add helpers that use the schema for both form-state inference and runtime validation. The names are only suggestions:

formOptions.validatedStrictSchema(schema, options)
formOptions.validatedLooseSchema(schema, options)

Example:

const form = useForm(
  formOptions.validatedLooseSchema(schema, {
    defaultValues: {
      firstName: 'Lucas',
    },
    validators: [
      {
        triggers: ['change'],
        run: businessRule,
      },
    ],
    onSubmit: ({
      value,
      schemaOutput,
      schemaOutputs,
    }) => {
      // value:
      // Editable form state inferred from the schema input

      // schemaOutput:
      // Validated and transformed output of the primary schema

      // schemaOutputs:
      // Outputs of the additional validators

      return submit(schemaOutput);
    },
  }),
);

The schema passed as the first argument would become a distinguished primary schema validator. Additional validators could still be supplied through validators.

The existing meaning of value should remain unchanged. It should continue to contain the editable form state rather than the transformed schema output.

This distinction matters for transforming schemas:

const schema = z.object({
  age: z.string().transform(Number),
});

In this case:

value.age
// string | null | undefined for a loose form

schemaOutput.age
// number

Named schema output

The primary schema output should be exposed as a named property in the onSubmit context:

onSubmit: ({ schemaOutput }) => {
  return submit(schemaOutput);
}

This avoids coupling application code to a position such as schemaOutputs[0].

The primary schema validator could remain part of the internal validator pipeline, but its output would be tracked separately. schemaOutputs could then represent the explicitly supplied validators without including the implicit primary schema output.

Validator merge strategy

createFormHook now supports reusable default options and a listenersMerge strategy. A similar validatorsMerge option could define where the automatically registered primary schema validator runs relative to explicitly supplied validators:

const { useAppForm } = createFormHook({
  fieldComponents,
  formComponents,
  defaultFormOptions: {
    validatorsMerge: 'append',
  },
});

No default validators would be configured in defaultFormOptions. Every form has different values and validation requirements. validatorsMerge would only configure the ordering between:

• the primary schema validator created by validatedStrictSchema or validatedLooseSchema
• the validators supplied by the concrete form

Suggested semantics:

type ValidatorsMergeMode = 'append' | 'prepend';

append would run the primary schema validator first:

[
  primarySchemaValidator,
  ...formValidators,
]

prepend would run the form validators first:

[
  ...formValidators,
  primarySchemaValidator,
]

I would omit replace because these helpers promise that the supplied schema participates in runtime validation. Replacing the primary validator would break that guarantee.

Behavior without createFormHook

The helpers should belong to the core FormOptionsApi, so they work with both formOptions and appFormOptions.

For plain useForm, the core could use a documented default:

validatorsMerge: 'append'

const form = useForm(
  formOptions.validatedLooseSchema(schema, {
    defaultValues,
    validators,
  }),
);

When the same formOptions object is passed to useAppForm, the form instance could apply the validatorsMerge strategy configured by createFormHook:

const options = formOptions.validatedLooseSchema(schema, {
  defaultValues,
  validators,
});

const form = useAppForm(options);

The options helper would not need to know the merge strategy when it creates the object. It could retain the primary schema validator separately, and the form instance could resolve the final validator order during initialization.

This also matches the current relationship between formOptions and appFormOptions: they are the same runtime helper, while appFormOptions additionally preserves the registered App Form component types.

Expected guarantees

The proposed helpers would guarantee that:

• The schema appears only once at the callsite.
• The schema controls strict or loose form-state inference.
• The schema always runs during submission.
• schemaOutput contains the validated and transformed schema output.
• value remains the editable form state.
• Additional validators remain supported.
• Validator execution order can be configured for App Forms.
• Plain formOptions uses a predictable core default.
• Application code does not depend on a schemaOutputs array index.

Would this fit the intended direction for the new schema and default-options APIs?

[LeCarbonator]

The main counter-argument I have against this is that the returned object is just the options you specified. You used a schema as reference, but what you actually do with the schema is up to you.

Previously, it was only one argument and it inferred the rest, so this was possible:

formOptions.looseSchema({
    defaultValues: {
      firstName: 'John',
      lastName: 'Doe',
    },
    validators: [
      {
        triggers: [],
        // It inferred from here
        run: schema,
      },
    ],
  }),
);

However, as soon as you added in any other validator, it would break completely. The two-argument approach does mean you have to specify the schema twice, but inference is as good as it can get, without worrying about any types happening.

[lucas-dtrn]

Okay, the main motivation behind my idea was to prevent a form from using a schema for type inference while accidentally omitting the corresponding runtime validator.

const schema = z.object({
  firstName: z.string(),
  lastName: z.string(),
});

const form = useAppForm(
  formOptions.looseSchema(schema, {
    defaultValues: {},
    // The schema validator is missing
    onSubmit: ({ schemaOutputs: [value] }) => {
      console.log(`${value.firstName} ${value.lastName}`);
    },
  }),
);

However, without a registered schema validator, there is no corresponding entry in schemaOutputs. The omission therefore becomes apparent when the submit handler tries to consume the validated output.

This only helps when the submit handler uses schemaOutputs rather than submitting the raw value, but I understand that looseSchema and strictSchema are intended to handle type inference only and should not introduce runtime behavior.

Given that separation, automatic schema registration may be more complexity than the helpers need.