Schema-Driven Validation in VeeValidate v4: Cross-Field Rules and Server Errors

Your registration form has a password field and a confirm-password field. With VeeValidate's field-level rules, enforcing that they match means coordinating two independent useField calls: one field needs to know the value of its sibling, and your submit handler needs to verify both before firing an API call. When the backend later rejects the email as already registered, you need a second UI path to display that server message. The form starts to feel like a state machine rather than a set of declarative rules.

For multi-field forms with interdependencies, VeeValidate v4's schema-driven approach offers a cleaner alternative: define one validation schema, pass it to useForm, and let the composable handle cross-field references, submit gating, and error collection. This article walks through that decision, the mechanics, and the trade-offs.

The coordination cost of field-level rules

VeeValidate v4 ships with the useField composable, which is excellent for isolated inputs. A single email field with a required rule and an email format check is straightforward. Problems appear when fields depend on each other. A confirm-password field must compare itself against the password field. With independent field rules, you either write a custom rule that reaches into another field's value or synchronize state manually. Both approaches scatter the form's logic across multiple call sites.

Server-side validation adds another seam. If your API returns { email: "Already registered" }, you need to route that message into the same display path as client-side errors. Without a unified error bag, teams often build parallel UI state for server failures.

One schema, one source of truth

In v4, useForm accepts a validationSchema option. Instead of per-field rule strings, you provide a single declarative schema—commonly a Yup object schema passed through the official Yup resolver. The resolver adapter is a separate package, so confirm the exact import path for your installed version.

Cross-field constraints become natural. Yup's ref lets one field reference a sibling, and oneOf enforces equality:

import { useForm, useField } from 'vee-validate'
import * as yup from 'yup'
// Resolver import is version- and package-dependent; consult your installed resolver docs.

const schema = yup.object({
  password: yup.string().required().min(8),
  confirmPassword: yup
    .string()
    .required()
    .oneOf([yup.ref('password')], 'Passwords must match')
})

const { handleSubmit, setFieldError } = useForm({
  validationSchema: schema
})

const { value: password, errorMessage: passwordError } = useField('password')
const { value: confirmPassword, errorMessage: confirmError } = useField('confirmPassword')

Each useField still exposes reactive value, errorMessage, and meta flags such as touched and valid. Your template can show an error only after blur by checking meta.touched, but the validation logic itself lives in one place.

Gating submits and merging server errors

useForm's handleSubmit acts as a gate. It runs full-form validation and only invokes the first callback when the schema passes. The second callback receives the collected errors, giving you a hook for analytics or focus management:

const onSubmit = handleSubmit(
  async (values) => {
    try {
      await api.register(values)
    } catch (err) {
      // Merge a server failure into the same display path
      setFieldError('password', 'Server rejected this password')
    }
  },
  (errors) => {
    console.log('Validation failed', errors)
  }
)

setFieldError and setErrors inject backend messages directly into VeeValidate's error bag. The UI code does not need to know whether a message came from Yup or your API.

Limitation: injected errors persist until the field revalidates. If the user corrects the value and the schema passes, the message clears. But if the server error was injected for a field the user does not immediately touch, it can linger. Clear it explicitly before resubmission or on input if your flow requires it.

Trade-offs and when to stay with field rules

Schema-driven validation centralizes rules and simplifies cross-field logic, but it couples your form to a schema library. Heavily conditional per-field logic—rules that change based on another field's type or an async toggle—can become verbose inside a Yup schema. Async rules such as username-availability checks add latency and can race with newer user edits; debounce or cancel them to avoid flickering or outdated results. A simple contact form with three independent inputs is often lighter with plain field-level rules.

A practical decision is to adopt schema-driven validation for multi-field forms with cross-field or async uniqueness checks, while keeping per-field rules for isolated simple inputs elsewhere in the same app.

Verify before you commit

VeeValidate v4 (Vue 3 composables) and v3 (Vue 2 components) have different APIs. Check the major version in package.json before applying any pattern. To validate the approach in your own context:

• Build a minimal password-plus-confirm form with a Yup schema referencing the sibling field, and confirm handleSubmit's valid callback fires only when both values match.
• Force a failure path by calling setFieldError after a mocked API rejection, then enter a valid value and confirm the injected message clears on revalidation.
• Prototype the same form with per-field rules and compare code size and readability.

If the schema version feels heavier for your use case, fall back to field-level rules. The goal is not schema purity; it is keeping validation logic where your team can maintain it.