1---
 2layout: page
 3title: Merge Family and Category into Group
 4---
 5
 6- **ADR:** 0020
 7- **Proposal Author(s):** @eddie-knight, @jpower432
 8- **Status:** Proposed
 9
10## Context
11
12Across the schema and documentation we currently use multiple terms to describe the same underlying concept: **a named classification used to organize entries within an artifact**.
13
14Examples:
15
16- Control catalogs use **families** (`families` list; each control references `family`).
17- Risk catalogs use **categories** (`categories` list; each risk references `category`).
18- Metadata already defines a generic `#Group` type (used by `metadata.applicability-categories`), but the terminology still varies in YAML and in docs.
19
20This terminology split increases cognitive load and invites inconsistent modeling:
21
22- Readers must learn whether a given artifact uses “family” vs “category” despite the same structural role (an in-document grouping keyed by `id`).
23- Tooling must special-case field names for what is effectively the same relationship (“entry belongs to a group defined in the same artifact”).
24- ADR-0018’s rejection feedback reinforced that these organizational groupings should generally live **within the documents that use them**, rather than as standalone catalogs (see [ADR 0018](./0018-promote-nested-concepts-to-catalogs.md)).
25
26## Decision
27
28Adopt **Group** as the single, consistent term for organizational groupings across the schema and documentation.
29
30### Schema and field name changes
31
32Wherever “family” or “category” is used to mean “an organizational grouping with an `id`, `title`, and `description`”, rename the fields to **group**:
33
34- **Control and guidance grouping**
35  - Rename top-level `families` → `groups`
36  - Rename per-entry `family` → `group`
37- **Risk grouping**
38  - Rename top-level `categories` (risk catalog groupings) → `groups`
39  - Rename per-entry `category` → `group`
40- **Metadata applicability grouping**
41  - Rename `metadata.applicability-categories` → `metadata.applicability-groups`
42
43The grouping entry shape remains `#Group` (already defined in `base.cue`), and the semantics remain unchanged.
44
45## Consequences
46
47- Schema becomes easier to understand and document: one concept, one name.
48- Tooling can treat “belongs-to-group” uniformly across artifact types.
49- This is a breaking change for serialized YAML/JSON field names and requires a migration step for existing examples and test data.
50
51### Keep “family” and “category” per artifact
52
53Retain existing per-domain vocabulary (controls have families; risks have categories). This preserves current YAML shapes, but keeps conceptual duplication and complicates docs/tooling.
54
55### Introduce “group” only as a shared type, not a field name
56
57Standardize on `#Group` for the entry shape but keep `families`/`categories` as field names. This reduces some implementation duplication but does not address user-facing inconsistency in schema usage and documentation.