Enhancements to the family members (personen) component

[joeridiederen]

Thema / Theme

Frontend

Omschrijving / Description

This RFC proposes enhancements to the existing “personen” component within Open Forms. The component leverages a citizen service number (BSN) of the authenticated individual to query a backend registry (via StUF-BG or HaalCentraal) and retrieve person-related data.

Initially, it will focus on four key scenarios:

• retrieving children,
• retrieving a partner,
• retrieving housemates, and
• retrieving a specific person.

Each scenario can return a consistent set of core variables — full name, BSN, birthdate.

The “personen” component will integrate closely with HaalCentraal’s standardized fields and filtering capabilities. For the first three scenarios (children, partner, housemates), the component retrieves a curated list of individuals based on configured filters and returns the core variables once the user selects a single result. Additionally, these scenarios may provide counts (e.g., the number of children or housemates). For the “Haal Persoon Op” scenario, administrators can return not only the core variables but also additional attributes selected from HaalCentraal’s fields tool.

Scenario's

Retrieve Children
Description: This scenario fetches individuals who are children of the authenticated person. Administrators can configure filters such as:

• Age-based filters (e.g., only show children older or younger than 18).
• Address-based filters (e.g., only children living at the same address).
• Deceased status (e.g., exclude or include deceased children).
• The component can also return the total count of filtered children (e.g., “You have 3 children that match this criteria”). Once a user selects one child, the component provides the core variables.

Purpose: Validate relationships and ages, prefill child-related fields, or trigger age-based logic in the form (e.g., determining eligibility for certain services). The count of children can inform the user or trigger logic based on family size.

Retrieve partner
This scenario lists the partner(s) of the authenticated individual. Filters include:

• Address-based filters (e.g., only show a partner if they live at the same address).
• Upon selection of the partner, the component returns the core variables.

Purpose: Facilitate auto-filling partner details for joint applications, verify relationship-based eligibility criteria, or streamline subsequent queries in the form.

Retrieve housemates
This scenario focuses on retrieving individuals who share the same address (housemates). The component filters based on address data and can return a count of how many housemates are present (e.g., “6 housemates found”). Once a housemate is selected, the component provides the core variables.

Purpose: Validate shared occupancy details, support applications that require information about co-residents, or enable conditional logic based on household composition. The count can inform whether the user must provide additional information or documentation.

Retrieve person
Description: This scenario allows an administrator to retrieve a specific individual by BSN. In addition to the default core variables, administrators can select from the full range of attributes offered by HaalCentraal’s fields tool. No additional count is required here. This flexible configuration enables advanced customization of the returned data.

Purpose: Handle complex form logic where detailed person attributes are required without additional steps or manual API calls. This scenario supports richer data retrieval for more complex workflows.

Added value / Toegevoegde waarde

• Default mappings and scenario-based filtering lower the barrier to entry. The “Haal Persoon Op” scenario provides the option to go deeper by customizing the retrieval of extended attributes when needed.
• Administrators can enrich the retrieved data using HaalCentraal’s fields tool, selecting additional attributes that serve the form’s specific requirements.
• Age, address, and deceased-status filters, along with the ability to present counts, ensure the displayed individuals are directly relevant and informative to the user’s context.

Aanvullende opmerkingen / Additional context

For the initial MVP, each instance of the “personen” component can be limited to a single selection. This design choice simplifies both development and the user experience. By starting small, we ensure that when one individual is selected, Open Forms reliably creates the specified core variables (e.g., eigenschapsnaam.fullname, eigenschapsnaam.BSN, eigenschapsnaam.birthdate) without additional complexity. These variables can be referenced in the form’s logic even before the user makes a selection, enabling a smooth “happy flow.” For example, administrators can write logic anticipating personen.fullname or personen.BSN and apply conditions or display fields once these variables become populated.

But the end goal is to allow dynamic variable creation for multiple selections. Advice on the feasibility of this is desired.

As a future-proof perspective, there are two possible approaches. The first is a static model with a predefined maximum number of options, where you establish an upper limit (e.g., five children) and set up corresponding variables and repeating groups in advance. This makes development simpler and predictable, but can feel constrained if real-world data often exceeds these limits. The second approach is a truly dynamic model that treats arrays and loops as first-class citizens, allowing the form to expand or contract in real-time without predefined boundaries. This approach provides maximum flexibility and future-proof scalability, but demands a more complex implementation and a steeper learning curve for administrators.