Standard Schema & Server Validation

Use a form as a Standard Schema, parse a FormData, and validate it in a Server Action or useActionState.

View as Markdown

Standard Schema & Server Validation

@saastro/forms/standard-schema turns a form config into a Standard Schema and validates a FormData on the server with the same rules the browser runs (field rules, crossFieldRules, hidden-by-condition pruning). It is React-free and lives in its own subpath, so neither the root bundle nor @saastro/forms/validation grows.

import {
  toStandardSchema,
  parseFormData,
  createServerValidate,
  initialServerValidateState,
} from '@saastro/forms/standard-schema';
import type {
  FormStandardSchema,
  FormStandardIssue,
  ServerValidateState,
  StandardSchemaOptions,
} from '@saastro/forms/standard-schema';

toStandardSchema

toStandardSchema(form, options?) returns a FormStandardSchema (Standard Schema v1, vendor saastro-forms). ~standard.validate is asynchronous and resolves to { value } or { issues }. Each FormStandardIssue has a message and, except for form-level problems, a path.

const schema = toStandardSchema(formConfig);
const result = await schema['~standard'].validate(body);
if (result.issues) return Response.json(result.issues, { status: 422 });

options is StandardSchemaOptions: { validateHidden?: boolean } (default false: a field hidden by a condition is not validated and is dropped).

parseFormData

parseFormData(form, formData) turns a FormData or URLSearchParams into the values the schema expects, using each field’s type:

Field type Result
checkbox, switch boolean (an unchecked box is false)
number, currency, slider, range, rating number (an empty string is absent)
checkbox-group, switch-group, button-checkbox array, even with a single value
repeater array of items, with their own fields converted

A repeated key (tags=a&tags=b) becomes an array. items[0][name] builds a repeater item and tags[] appends to an array. Keys such as __proto__, constructor and prototype, and indexes of 1000 or more, are ignored. A File passes through untouched.

createServerValidate

createServerValidate(form, options?) returns an action (prevState, formData) => Promise<ServerValidateState>, ready for React 19’s useActionState or a Server Action.

'use server';
const validate = createServerValidate(formConfig);

export async function send(prev: ServerValidateState, formData: FormData) {
  const state = await validate(prev, formData);
  if (state.status === 'valid') await save(state.data);
  return state;
}
const [state, action] = useActionState(send, initialServerValidateState);

ServerValidateState:

Key When Meaning
status always 'idle' (not sent yet), 'invalid' or 'valid'
data valid validated and converted values. A File stays in it: use it on the server and do not return it to the client
errors invalid field name → messages; form-level issues use the key _form
values invalid what was received, without files, to repaint the form