Expand nested evidence arrays without inflating parent counts — what should the operator record?
A nested response can contain several links or observations beneath one source object. Flattening makes review easier but changes row grain. Keep parent membership visible so the expanded row count is not later presented as the number of independent source records or unique people represented by the response.
Keep parent and child identities explicit when flattening returned arrays into rows.
Use parent_source_key and child_index or an actual child identifier, naming what each expanded row represents. If children have no persistent identifier, use parent_key plus local child position only within the same receipt and label that reference unsuitable across future responses.
Offer a parent index and child table linked by keys when needed, with explicit headings that prevent accidental population claims from the expansion. Recipients should know whether child rows represent links, comments or local annotations, since the same flattening shape can otherwise imply very different evidence relationships.Define parent and child grain
Use parent_source_key and child_index or an actual child identifier, naming what each expanded row represents. If children have no persistent identifier, use parent_key plus local child position only within the same receipt and label that reference unsuitable across future responses.
Preserve empty arrays
Decide whether an empty child list produces a parent-only state row or a separate exception, documenting the choice rather than silently losing parents. An empty array and an absent array may carry different meanings; the transformation should preserve that distinction rather than emitting the same silent zero-child interpretation.
Test mixed inputs
Use fixtures containing empty, single and multiple children, plus missing arrays, and check the expected parent-to-child relationships. Verify that a parent with two child references produces the declared child rows without duplicating an unrelated nested array into an accidental Cartesian product.
Reconcile both counts
Validate distinct parent keys separately from expanded row count, preserving repeated parent fields without treating them as additional independent observations. For example, expanded relationship rows may exceed distinct parent objects; both actual counts belong in validation without calling the larger one a count of independent sources.
Deliver two interpretable views
Offer a parent index and child table linked by keys when needed, with explicit headings that prevent accidental population claims from the expansion. Recipients should know whether child rows represent links, comments or local annotations, since the same flattening shape can otherwise imply very different evidence relationships.
Keep the boundaries clear.
- Keep parent and child identities explicit when flattening returned arrays into rows.
- Operational record: Define parent and child grain. Context badges do not certify access.
Start with a read-only check: ask your agent to report actual source coverage before collecting records or exporting an audience.
Primary references
Documentation reviewed 2026-11-15. Product capabilities, client availability and plans can change. Third-party marks identify their products, not an affiliation.