From harness-claude
Designs API validation error responses using JSON Pointers for multi-field failures, 400/422 status choices, and JSON:API conventions. For form submissions, OpenAPI specs, and PR reviews.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> FIELD-LEVEL VALIDATION ERROR DESIGN — RETURNING ALL VALIDATION FAILURES IN A SINGLE RESPONSE WITH JSON POINTER PATHS AND PER-FIELD MESSAGES ELIMINATES THE ONE-ERROR-AT-A-TIME DEBUGGING LOOP AND GIVES CLIENTS ENOUGH INFORMATION TO HIGHLIGHT EVERY INVALID FIELD WITHOUT A SECOND REQUEST.
Defines consistent API error contracts with machine-readable codes, human-readable messages, remediation advice, taxonomy, and envelope structure. Use for API design, PR reviews, style guides, audits, SDKs, and OpenAPI docs.
Provides step-by-step guidance, generates production-ready code, and validates request bodies for REST, GraphQL, and OpenAPI APIs. Useful for request validation tasks.
Implements API error handling with standardized responses, logging, monitoring, retry logic, circuit breakers, and validation patterns for Node.js and Python APIs.
Share bugs, ideas, or general feedback.
FIELD-LEVEL VALIDATION ERROR DESIGN — RETURNING ALL VALIDATION FAILURES IN A SINGLE RESPONSE WITH JSON POINTER PATHS AND PER-FIELD MESSAGES ELIMINATES THE ONE-ERROR-AT-A-TIME DEBUGGING LOOP AND GIVES CLIENTS ENOUGH INFORMATION TO HIGHLIGHT EVERY INVALID FIELD WITHOUT A SECOND REQUEST.
400 with a single error message for a request that may have multiple invalid fields400 Bad Request and 422 Unprocessable Entity for semantic validation failuresMulti-field error arrays — A single validation response should report all failing fields simultaneously, not just the first one encountered. The response body includes an array of error objects, each describing one invalid field: "errors": [{ "pointer": "/email", ... }, { "pointer": "/birthdate", ... }]. Stopping at the first failure creates a "whack-a-mole" experience where callers must submit, fail, fix, and resubmit for each field in turn.
JSON Pointer (RFC 6901) — A standardized syntax for identifying a specific value within a JSON document. Pointers use / as a separator: /user/email identifies the email field inside a user object; /items/0/price identifies the price of the first element in an items array. In validation error responses, the pointer (or source.pointer in JSON:API) field identifies exactly which part of the request body failed validation — no ambiguity, no path string parsing.
source/pointer vs source/parameter — JSON:API distinguishes two sources of validation error:
"source": { "pointer": "/data/attributes/email" } — the error is in the request body, at a JSON Pointer location."source": { "parameter": "filter[status]" } — the error is in a query parameter, not the body.
Use pointer for body fields, parameter for query string inputs. RFC 9457 extensions use "pointer" directly as a top-level extension field rather than nesting under source.422 vs 400 — Use 400 Bad Request for structurally malformed requests: unparseable JSON, missing Content-Type, invalid URL path parameters. Use 422 Unprocessable Entity for requests that are syntactically valid but semantically invalid: a correctly parsed JSON body where email is not an email address, end_date precedes start_date, or a required field is present but empty. The distinction matters because 422 tells the client "your request reached the validation layer and failed there" — it is never retryable without changing the payload.
Per-field titles and details — Each error object in the array should include a stable title (the validation rule that failed: "Must be a valid email address") and an instance-specific detail ("'not-an-email' is not a valid email address format"). The title is reusable across occurrences of the same rule; detail adds the specific value that failed, making it debuggable without inspecting the original request.
A Stripe-style account creation endpoint returning multi-field validation errors:
Request with multiple invalid fields:
POST /v1/accounts
Authorization: Bearer sk_test_...
Content-Type: application/json
{
"email": "not-an-email",
"country": "XX",
"business_type": "individual",
"individual": {
"dob": {
"day": 32,
"month": 13,
"year": 1850
}
}
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
{
"type": "https://api.example.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "3 fields failed validation. Correct the highlighted fields and resubmit.",
"instance": "/errors/correlation/a1b2-c3d4",
"errors": [
{
"pointer": "/email",
"title": "Must be a valid email address",
"detail": "'not-an-email' does not match the expected email format."
},
{
"pointer": "/country",
"title": "Must be a valid ISO 3166-1 alpha-2 country code",
"detail": "'XX' is not a recognized country code."
},
{
"pointer": "/individual/dob/day",
"title": "Day must be between 1 and 31",
"detail": "Received 32. Days in a month range from 1 to 31."
}
]
}
The pointer paths use RFC 6901 syntax: /email addresses the top-level field; /individual/dob/day drills into the nested individual.dob.day path. A client rendering a form can use each pointer to highlight the exact input that failed without any string parsing.
Query parameter validation error (400 Bad Request):
GET /v1/payments?status=unknownstatus&limit=abc
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"type": "https://api.example.com/errors/invalid-query-parameter",
"title": "Invalid Query Parameter",
"status": 400,
"detail": "2 query parameters are invalid.",
"errors": [
{
"parameter": "status",
"title": "Must be one of: pending, succeeded, failed",
"detail": "'unknownstatus' is not a valid status value."
},
{
"parameter": "limit",
"title": "Must be an integer",
"detail": "'abc' cannot be parsed as an integer."
}
]
}
Query parameter errors use "parameter" instead of "pointer" because they are not in the request body.
Returning a single error for the first failing field. A form with 5 invalid fields returns only the first error. The user fixes it, resubmits, receives the second error, and so on for 5 round-trips. Fix: validate the entire request body, collect all errors, and return the full list in a single 422 response.
Using vague path strings instead of RFC 6901 pointers. "field": "individual.dob.day" uses dot notation that requires parsing and breaks for array indices. "field": "items[0].price" uses a mix of dot and bracket notation with no standard. Fix: use RFC 6901 JSON Pointer syntax ("/individual/dob/day", "/items/0/price") — it is unambiguous, parseable by standard libraries, and consistent across implementations.
Returning 400 for semantic validation failures. A request body that is valid JSON but contains an email address string that fails the email format check is not malformed — it passed JSON parsing. Returning 400 mixes structural errors with semantic ones, complicating client error routing. Fix: reserve 400 for structural failures (unparseable JSON, wrong Content-Type) and use 422 for any failure that occurs after successful parsing and type coercion.
Omitting the pointer for nested fields. Returning { "field": "dob", "message": "Invalid date of birth" } for a nested field fails to identify which level of nesting failed, and whether dob.day, dob.month, or dob.year is the problem. Fix: use the full JSON Pointer path to the failing field, however deep it is in the payload.
RFC 6901 defines two escape sequences for characters that conflict with the pointer syntax: ~0 represents a literal ~, and ~1 represents a literal /. If a field name contains a slash — e.g., "Content-Type" — the pointer is /Content~1Type. This is rare in practice but important when generating pointers programmatically from field names.
For bulk operations or array inputs, the pointer must include the array index: /items/2/quantity identifies the quantity field of the third element (zero-indexed) in the items array. This is essential for bulk import endpoints where clients need to know which rows failed without re-matching errors to rows by field name.
Shopify's Admin API (both REST and GraphQL) returns structured validation errors with field paths. In the REST API, errors follow a { "errors": { "field_name": ["message"] } } shape. In the GraphQL API, errors use the userErrors pattern: { "userErrors": [{ "field": ["lineItems", "0", "quantity"], "message": "Quantity must be greater than zero" }] }. The field array is equivalent to a JSON Pointer path split on /. Shopify's developer documentation shows that APIs returning structured field-path errors report significantly fewer "which field caused the error?" support questions than APIs returning only top-level messages. The field path is the minimum information needed for a client to display inline validation feedback without guessing.
pointer (for body fields using RFC 6901) or parameter (for query string inputs).422 response with an errors array containing per-field title and detail entries.harness validate to confirm skill files are well-formed and cross-references are correct./field/subfield/index), not dot notation or custom path formats.422 Unprocessable Entity is used for semantic validation failures; 400 Bad Request is reserved for structural/parse failures.title (the rule) and an instance-specific detail (the offending value and why it failed).parameter field, not a pointer field.