Suppress empty parent objects when required children are absent (on_missing / required_slots) #264

Activity

1. amc-corey-cox

   added

   enhancementNew feature or requestNew feature or request

   on Jun 15, 2026
2. github-actions commented on Jun 15, 2026

   

   github-actionsBot

   on Jun 15, 2026 – with GitHub Actions

   More actions

   Summary

   This issue addresses the next step in a progression of "silent-shape" correctness hazards in the sparse-join pipeline. It introduces upward-propagating suppression for parent objects whose meaningful content is entirely absent — a problem that #217's fix cannot solve because it works at the wrong scope.

   ---

   Context Chain

   Issue	Status	Summary
   #211	✅ Closed (2026-06-12)	Silent nulls when a nested populated_from references a different table with no joins: — the original "silent-shape" hazard. Motivated the vocabulary.
   #217	🔴 Open (v0.5.3 milestone)	Sparse implicit-join miss leaves a nested object as {value: None} instead of absent; also causes data-dependent ambiguity enforcement inconsistency. Prerequisite for this issue.
   #264	🔴 Open (v0.6.0 target)	(This issue.) Even after #217's fix, a parent object is emitted as a hollow shell when all its derived children are suppressed.

   ---

   The Problem

   After #217 is resolved, a sparse-join miss correctly suppresses the nested object. But the parent — whose populated_from row genuinely exists — still emits with valid identity/constant slots and an empty child list (e.g. observations: []).

   Concrete example (BDCHM blood-pressure transform): A MeasurementObservationSet wraps systolic and diastolic MeasurementObservations. If neither reading exists in the source data, the set still emits with associated_participant, observation_type, etc. all populated — but observations: []. This silently asserts "a blood-pressure measurement occurred" when nothing was measured.

   Why #217's local rule can't be reused: #217's suppression is anchored to populated_from — no row in the joined table → no object. Here the parent's populated_from row does exist; suppression depends on the derived children, not the source row. This requires non-local, upward-propagating logic.

   ---

   Proposed Spec Changes

   Three cooperating mechanisms:

   1. on_missing: on class_derivation — opt-in enum (skip | none | empty), defaulting to current behavior. A parent is never automatically pruned; the user must declare intent.

   2. required_slots: on class_derivation — declares which slots define "non-emptiness." Necessary because constants (observation_type, unit) and identity slots (associated_participant) are never null; "all slots None" is the wrong test and would never trigger.

   3. Cascading suppression — when a parent is suppressed, its own container re-evaluates its required_slots, allowing emptiness to propagate up a multi-level hierarchy.

   ---

   Key Design Considerations

   • Opt-in is essential. Auto-pruning parents based on child absence would break transforms that legitimately want a parent record even with no children.
   • required_slots: vs. inferring emptiness. The proposal explicitly acknowledges that slot-level inference doesn't work because constants always have values. Declared required slots give the user control.
   • Cascading propagation. A suppressed grandchild that causes a suppressed child should then allow the grandparent to re-evaluate — this needs careful ordering in ObjectTransformer (post-child-resolution pass before parent emission).
   • Interaction with on_missing: none vs. skip. The semantics of each value need to be pinned down: does none emit null in the parent list? Does skip omit entirely? Does empty permit an empty object through?
   • Test scaffolding. The BDCHM blood-pressure case is an ideal scaffold test: two child observations, both absent → parent suppressed; one present → parent emitted with partial observations list.

   ---

   Status & Path Forward

   • Blocked on Sparse implicit-join semantics: nested object on no-match + data-dependent ambiguity enforcement #217 — the prerequisite fix (nested object suppression on join miss) must land in v0.5.3 first.
   • Targeted for v0.6.0 — this is net-new spec semantics, not a patch-level fix.
   • No implementation has started; this is a design-stage issue.
   • The on_missing: vocabulary was already surfaced as an option in Sparse implicit-join semantics: nested object on no-match + data-dependent ambiguity enforcement #217's design discussion, making this a natural continuation of that design thread.