Validation

At a glance

The idea in three lines: the same validation that already works on a form <input> should work on any typed value, a component prop, a data response, with no forms library.

<!-- a form control validates against its constraints, exactly as today -->
<input bind:value="email" type="email" required>

<!-- a typed component prop validates the same way, with no forms library -->
<x-field :value="draft.age" type="<number>" min="0" max="120">

<!-- structured data validates against a schema; failures carry a path -->
<data name="profile" src="/api/me" schema="/schemas/profile.json">

The rest of this page explains why the platform cannot do this yet, and how HTML Next generalizes it.

What the platform already has

HTML has a real validation system, the Constraint Validation API, but it is welded to form controls:

• Declarative constraints on <input>/<select>/<textarea>: required, pattern, min/max, step, minlength/maxlength, type.
• ValidityState, the machine-readable result: element.validity with typed flags (valueMissing, typeMismatch, rangeOverflow…).
• Methods (checkValidity, reportValidity), validationMessage, the invalid event, and the CSS :valid/:invalid/:user-invalid family.
• ElementInternals.setValidity(flags, message, anchor), the primitive an element uses to create an error, already exposed to script, and already free of the word “custom.”

Why it doesn't generalize yet

Valid or invalid, with a reason

Validity is binary: a value satisfies its constraints or it does not. When it does not, it carries an open list of reasons, a reason code plus a message, optionally a path. Because the vocabulary is open and meaningful, there is no “everything else” bucket and therefore no “custom.”

// the element knows its own value and declared type/constraints:
<input bind:value="email" type="email" required>

// validity recomputes reactively when the value changes — usually you read, not call
el.validity            // { valid: boolean, errors: ValidityError[] }
el.validationMessage   // the first error's message, or ""

// validate on demand (e.g. on submit): the element checks itself, no threading
el.validate()          // → { valid, errors }; updates .validity, fires `invalid` if newly invalid

// set validity the type CANNOT derive — async / server-side ("email already taken")
el.setValidity([{ reason: "taken", message: "That email is in use." }])
el.setValidity()       // clear the externally-set error

// pure helper: validate any value against a type or schema, no element involved
validate(value, type | schema)   // → { valid, errors }

interface ValidityError { reason: string; message: string; path?: string }

There are three levels, and the common one is the one you never call:

• Reactive (default). An element with a declared type validates itself when its value changes, because the value is already a reactive dependency. el.validity is simply current; you read it, you do not drive it.
• el.validate() for an explicit check, at submit time or on demand. The element validates itself against its own value and type, generalizing checkValidity(), so there is no validate(value, type) threading. It returns the rich result and fires invalid.
• el.setValidity(errors) only for validity the type cannot derive: an async, server-side answer such as “this email is already taken.” It keeps the customless name ElementInternals already uses, and adds a reason list (a value can fail more than one way) and a path, so a structured failure can point at the field, something native ValidityState cannot express.

The standalone validate(value, type | schema) stays a pure helper for validating raw data that is not attached to an element.

The type is the constraint

A declared type or a JSON Schema compiles to validity (the shapes shown at a glance above). One function does it, the parse-and-validate step a schema library performs, but emitting native ValidityState instead of a library-specific error. validate(value, type | schema) maps failures onto meaningful reasons, which map in turn onto the native flags for form interop:

When validation runs, and when errors show

These are two different questions, and conflating them is why validation UIs feel wrong. HTML Next separates them the way the platform already started to:

• Computing validity is reactive: it recomputes whenever the value changes, so el.validity is always current. No trigger is needed for the value to know whether it is valid.
• Showing an error is gated by interaction: you do not flag a field the user has not touched yet. This is exactly what CSS :user-invalid already means, invalid and interacted-with, and HTML Next drives the display from that state, not from raw validity.

So the native checkValidity() / reportValidity() split collapses: computing is reactive (or el.validate() on demand), and showing is ordinary CSS on :user-invalid (polyfilled as [data-invalid] once interacted). Submitting a <form> runs validate() across its fields, marks them interacted, and blocks the write when any is invalid, the native form-submission behaviour, now available to typed props and data too.

The surface, and the polyfill's limits

An element with validity should expose the same surface a form control does: the :valid/:invalid/:user-invalid pseudo-classes, an invalid event, validationMessage, and an anchor naming where to show the error. That is the platform change HTML Next proposes: make that surface available to any element with validity, not only form controls.

References

1. WHATWG HTML, the Constraint Validation API and ValidityState.
2. WHATWG HTML, ElementInternals.setValidity() (the existing, customless set primitive, gated to form-associated custom elements).
3. WAI-ARIA, aria-invalid (the invalid-state signal that applies to any element).
4. CSS Selectors Level 4, validity pseudo-classes (:valid, :invalid, :user-invalid).
5. IETF JSON Schema; Zod / Valibot (the issue-list model this mirrors).