Aglet

Triage an API nullable field change

A field becoming null can be an allowed state, a permission boundary, or a contract change. Freeze one resource and compare raw presence, resource state, client default, and stored value. Keep absent, null, empty, and malformed representations distinct during triage.

Establish what is happening

  1. Capture field presence

    Record resource state, endpoint, version, field presence, raw null or value type, and client revision without copying sensitive data. Note the local label or fallback shown. Preserve whether the field was omitted or explicitly returned as null.

  2. Compare neighboring states

    Run a populated resource, explicit null, omitted field, empty value, and permission-filtered response when safe. Compare mapper output and stored state. A default that makes all five look alike can hide the contract boundary.

  3. Bound affected consumers

    Group cases by resource state, endpoint, client version, environment, and downstream decision. Separate display fallback, persistence mutation, and authorization filtering. If field meaning is undocumented, record the exact missing contract evidence.

What to carry forward

Triage ends with field representation, resource state, first client divergence, affected consumers, and explicit unknowns. Hold broad defaults. Route contract, mapper, and permission questions separately. Preserve examples of an absent field, an explicit null, and a populated value so the eventual mapping can be checked against each representation.

Technical background: Project documentation on GitHub.

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