# Family

## Overview

A Family is a template that defines the data structure for a group of similar products. Families specify which
attributes and categories apply to products, along with requirement levels that are enforced at publish time.

Think of families as product types: "Electronics", "Clothing", "Furniture"—each with different relevant attributes and
categorization rules.

## Basics

### Core fields

**name** — Display name for the family (e.g., "Consumer Electronics", "Winter Apparel").

**description** — Optional explanation of what products belong in this family.

**parentUuid** — Optional parent family for hierarchical organization.

### Hierarchy

Families can be organized hierarchically. A parent family might be "Clothing" with children like "T-Shirts", "Pants", "
Outerwear".

Child families inherit all attribute and category associations from their parent, and from their parent's parent, and so
on up the chain. This allows you to define common requirements at a high level and add specifics as you go deeper.

For example:

- "Clothing" family requires `brand` attribute
- "T-Shirts" child family adds `size` and `color` attributes
- Products in "T-Shirts" must satisfy requirements from both families


Inherited associations cannot be overridden at the child level—they accumulate.

## Attributes

Associate attributes with a family to define what product characteristics are tracked. Each association includes:

**requirementLevel** — Controls validation at publish time:

| Level | Meaning |
|  --- | --- |
| `must` | Attribute is required—product cannot publish without it |
| `should` | Attribute is recommended but not blocking |
| `may` | Attribute is optional |
| `mustNot` | Attribute must not be present |


**isAutoPopulated** — When true, new products created in this family automatically receive this attribute association.

## Categories

Associate categories with a family to define classification rules. Uses the same configuration as attributes:

**requirementLevel** — Same levels as attributes (`must`, `should`, `may`, `mustNot`).

**isAutoPopulated** — When true, new products in this family are automatically assigned to this category.

## Lifecycle

Families use activation rather than publishing.

### Status values

| Status | Description |
|  --- | --- |
| `draft` | Initial state, not available for products |
| `active` | Available for assigning to products |
| `inactive` | Temporarily disabled, existing products unaffected |
| `removed` | Soft-deleted |


### Transitions

| Transition | Valid from | Results in |
|  --- | --- | --- |
| `activate` | draft, inactive | active |
| `deactivate` | active | inactive |
| `remove` | draft, active, inactive | removed |
| `restore` | removed | inactive |


## Error codes

| Code | Description |
|  --- | --- |
| `FAMILY_NOT_FOUND` | Family does not exist |
| `FAMILY_INVALID_TRANSITION` | Lifecycle transition not allowed |
| `FAMILY_REMOVED` | Cannot modify a removed family |
| `FAMILY_NAME_REQUIRED` | Name field is required |
| `FAMILY_NAME_EMPTY` | Name cannot be empty |