Aglet

Investigate unexpected null API fields

Investigation should explain why a field’s representation now leads to a different state. Build populated, null, absent, empty, and filtered fixtures, then follow each through the mapper. Keep permission filtering, version drift, parser behavior, and server data as competing explanations.

Build a useful investigation brief

  1. Build representation fixtures

    Create one resource for each meaningful field state: value, explicit null, absence, empty, malformed, and filtered. Record expected local state and downstream action before execution. Use synthetic resource identifiers and redacted values.

  2. Trace mapper boundaries

    Capture raw presence and type, decoder output, optionality branch, default, persisted snapshot, and rendered state. Compare the first divergence between populated and null cases. Record endpoint, version, and client revision for each fixture.

  3. Challenge field meaning

    Vary only resource state, permission context, version, field value, or parser input. Compare whether null follows data, access, or contract. If the same output fits multiple causes, name the missing observation instead of choosing a default.

What to carry forward

The investigation is ready when each field representation has a trace to local state and downstream action. Recommend a narrow mapper or contract change. Keep permission and remote semantics explicit when local fixtures cannot establish them. Record the consumer effect beside the mapper trace.

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