Family-Scoped Attributes
A family-scoped attribute is a custom user attribute that holds a separate value for each family a user belongs to. A regular custom attribute has one value per user. A family-scoped attribute has one value per user per family.
Some user details depend on the household. A child of separated parents might have a different nickname, bedtime, or daily screen-time limit in each parent's home. A regular attribute can store only one of those values. With a family-scoped attribute, each family keeps its own value for the same user.
Family-scoped attributes vs. custom family attributes
A custom family attribute describes the family itself, such as the family's plan, and has one value per family. A family-scoped attribute describes a user, and has one value for each of that user's families.
Creating a Family-Scoped Attribute
You create family-scoped attributes on the Custom Attributes tab of the Users page, the same place as regular custom user attributes. The option appears only when families are on.
Open the create dialog
On the Custom Attributes tab of the Users page, start a new custom attribute.
Set the name and type
Enter the attribute's name and choose a type.
Turn on family mapping
Turn on Allow mapping to Families, and then save the attribute.
A family-scoped attribute supports the same types as other custom attributes: text, numeric, boolean, single select, multi select, date, and month-day. The Family Scoped column in the attributes table shows which attributes are family-scoped.
You choose family mapping only when you create the attribute. The edit dialog does not offer the switch, so to change an attribute between regular and family-scoped, delete it and create it again.
Setting Values
You set a user's values in the Family Settings section of the invite or edit user dialog. In the edit dialog, the fields are under the Family-Scoped Attributes header. Each row pairs a family with the user's values for the family-scoped attributes in that family.
You can choose only families that you selected for the user in the same dialog's family and role rows. You can add the user to a family and set the family's values in one save. Descope drops any value for a family that the user does not belong to.
On a family's Family Members page, each family-scoped attribute appears as a column that shows the members' values for that family. The main users table does not show family-scoped attributes, because a user can have a different value in each family.
You can also set values from your backend. Pass them in the family associations of a user create, invite, or update call, or when you add a user to families or create a dependent. For code samples, see Families with SDKs.
Descope stores family-scoped values on the user, keyed by family ID. Descope ignores a value for a family that the user does not belong to. Family-scoped values do not appear in the session token by default. To read them, load the user with the management SDK, which returns them under each entry in userFamilies.
Next Steps
To manage family-scoped attribute definitions from code, see Manage Family-Scoped Attribute Definitions. To learn how members join a family, see Configuring a Family.