Aglet

Investigate why an API request fails schema validation

Investigation should explain the rejected request at the wire boundary. Build a valid and invalid pair, capture the serializer output, and follow the response into local error handling. Keep required-field, type, encoding, and business-rule explanations distinct until one controlled variation changes the result.

Build a useful investigation brief

  1. Build request contract fixtures

    Create a complete request, one omitted field, one wrong type, one null, and one unknown property using synthetic values. Record expected status and local handling for each. Include nested and repeated fields where the operation uses them, without copying sensitive production content.

  2. Trace serialization and validation

    Capture domain input, serialized body, headers, server response, decoder output, and mapped error. Compare the first point where the valid and invalid fixtures diverge. Record content type, client revision, and schema revision so middleware changes remain distinguishable.

  3. Challenge the validation rule

    Change one property at a time and repeat only safe requests. Test whether the same response follows a serializer change, a schema version, or an actual business rule. If the endpoint does not expose enough detail to decide, name the missing contract evidence and stop there.

What to carry forward

The investigation is ready when valid and invalid fixtures, wire representation, response detail, serializer revision, and local branch show the first divergence. Recommend a narrow contract or mapping change. Leave undocumented server rules as explicit evidence requests.

Technical background: RFC Editor reference.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow