Understanding the Validation Error Format

Chapter 19 showed the violations array – this chapter goes into detail on WHY this format looks the way it does and HOW React (block 9) makes sense of it.

Two layers: hydra:description and violations

The response contains the errors TWICE, in TWO different forms: hydra:description as ONE combined, human-readable string (all messages separated by a newline), AND violations as a STRUCTURED array – each entry tied to a SPECIFIC field via propertyPath.

Achtung: For a frontend, violations is the RIGHT choice: hydra:description can NOT be reliably mapped to a single form field, while propertyPath CAN.

Multiple errors on different fields

curl -k -X POST https://localhost/api/projects \
  -H 'Content-Type: application/json' \
  -d '{"name": "ab"}'

{
  "violations": [
    {"propertyPath": "name", "message": "This value is too short. It should have 3 characters or more."}
  ]
}

propertyPath matches EXACTLY the entity's property name (name) – for NESTED objects (block 5), it becomes a PATH EXPRESSION like tags[0].name.

Distinguishing from the parser error in chapter 16

Status code	Cause
`400 Bad Request`	JSON is syntactically BROKEN, the parser fails BEFORE any entity mapping
`422 Unprocessable Entity`	JSON is syntactically CORRECT, but a constraint fails (semantic error)

A frontend MUST treat these two cases DIFFERENTLY: 400 is a PROGRAMMING ERROR on the client (should NEVER occur with correctly written code), 422 is a NORMAL, USER-caused case that must be CAUGHT in the UI.

Tipp: React Hook Form (block 9) can be fed DIRECTLY with the violations array – setError(propertyPath, { message }) per entry is already enough to produce field-by-field error displays.