# Standard Schema & Server Validation

URL: https://docs.forms.saastro.io/docs/standard-schema
> Use a form as a Standard Schema, parse a FormData, and validate it in a Server Action or useActionState.

# Standard Schema & Server Validation

`@saastro/forms/standard-schema` turns a form config into a [Standard Schema](https://standardschema.dev) 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.

```ts
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`.

```ts
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.

```ts
'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;
}
```

```tsx
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              |
