Getting validation errors into the form

What this is about

When a form sends data that breaks field rules, CDMS answers with 422 and a list violations. Each entry names the field with its path and the violated rule. Your job in the client: map each entry to the matching input field and show an understandable message there.

From the 422 to the marked form

{
  "messageKey": "validation-failed",
  "code": "422",
  "violations": [
    { "field": "name",
      "rule": "cannot-be-empty" },
    { "field": "address.zip",
      "rule": "pattern-mismatch" },
    { "field": "contacts[1].email",
      "rule": "cannot-be-null" }
  ],
  …
}

Create customer
─────────────────────────────────────────
Name      [                 ]
          ⚠ must not be empty
Address
  Street  [ 1 Main Street   ]
  ZIP     [ 123             ]
          ⚠ does not have the allowed format
Contacts
  1  Anna   [ anna@muster.de ]
  2  Ben    [                ]
          ⚠ is required
─────────────────────────────────────────
Please correct the marked fields.

The flow

Reading the path

The path in field describes where the field sits in the object you sent. It starts inside data:

It is easiest if your form fields carry the same path as their name, for example name="contacts[1].email". Then field is directly the key under which you store the message.

The index in […] is the position in the list as you sent it. If the form shows the rows in the same order, the message hits the right row.

Translating the rules into text

The response does not contain the limits themselves, such as the allowed length or the minimum value. If you want to show them in the text, take them from your model. Which rule checks what is described in Validation.

An example in TypeScript

type Violation = { field: string; rule: string };

const TEXT: Record<string, string> = {
  'cannot-be-null':   'is required',
  'cannot-be-empty':  'must not be empty',
  'too-long':         'is too long',
  'pattern-mismatch': 'does not have the allowed format',
  'min-number':       'is smaller than allowed',
  'max-number':       'is larger than allowed',
  'not-in-future':    'must be in the future',
  'not-in-past':      'must be in the past',
};

function byField(violations: Violation[]) {
  const errors: Record<string, string[]> = {};
  for (const v of violations) {
    const text = TEXT[v.rule] ?? `is invalid (${v.rule})`;
    (errors[v.field] ??= []).push(text);
  }
  return errors;
}

const res = await fetch(url, { method: 'POST', … });
if (res.status === 422) {
  const body = await res.json();
  const errors = byField(body.violations ?? []);
  for (const [path, texts] of Object.entries(errors)) {
    const input = form.querySelector(`[name="${path}"]`);
    if (input) markField(input, texts);
    else showFormMessage(`${path} ${texts.join(', ')}`);
  }
}

The example does two things on purpose:

• An unknown rule gets a general text instead of a crash. That keeps your client stable when a rule is added.
• A field the form does not show ends up in the message above the form. This happens, for example, with a PUT when a required field is not in the form and therefore arrives as null.

All variants

Other errors with a field

It is not only 422 that can concern a field. A value that does not even fit the field type, such as text in a number field, is refused too: with 400 invalid-value|<path>. This comes before the rules are checked, so on its own and without violations.

Here the path is in the messageKey after the |. For create and PUT it starts at the root of the body (data.amount), for PATCH inside data (amount). Cut off a leading data., then it matches your form fields.

Pitfalls

Where to go next

• Which rules exist and when they apply: Validation
• Why PUT reports other fields than PATCH: PUT or PATCH? The null trap
• How every error response is built: The error format