1---
 2layout: page
 3title: Promote Nested Concepts to First-class Catalogs
 4---
 5
 6- **ADR:** 0018
 7- **Proposal Author(s):** @eddie-knight
 8- **Status:** Rejected
 9
10## Context
11
12Historically, the schema treated some concepts as *sub-structures* of other catalogs rather than as standalone artifacts. In particular, Families, Categories, and Capabilities were represented only as nested lists within other catalogs.
13
14This caused recurring problems:
15
16- These concepts could not be referenced, extended, imported, or versioned as independent artifacts.
17- Different contributors often maintained the different asset types
18- As the number of catalog types grows, keeping ad hoc nested representations consistent becomes harder and encourages drift between similar concepts.
19
20We want these entries to be composable and version controlled independently of other assets.
21
22## Decision
23
24A proposal was made along with proposed changes, and subsequently rejected. This is the log of that decision.
25
26### Rejected proposal
27
28Promote Groups, Capabilities, and Risk Categories to **first-class catalog artifacts** with dedicated top-level catalog types:
29
30- `#GroupCatalog`
31- `#CapabilityCatalog`
32- `#RiskCategoryCatalog`
33
34Each new catalog type embeds the shared `#Catalog` base and defines a typed `entries` list for its concept.
35
36### Rejection reason
37
38This proposal was rejected because we do not anticipate strong cross-document reuse (or a desire to maintain additional standalone artifacts) to document group descriptions.
39
40- **Groups (e.g. Family) and Risk Categories** are primarily organizational and should live within the document that uses them.
41- **Capabilities** are agreed to be domain content and should have a standalone proposal in a subsequent ADR.
42
43## Consequences
44
45- **No new top-level catalog types** are introduced for Groups and Risk Categories; these organizational groupings remain defined within the documents that use them.
46- **Capabilities** as a new catalog will be considered in a follow-up proposal.
47
48## Alternatives Considered
49
50### Keep concepts nested within other catalogs
51
52Continue representing Groups, Capabilities, and Risk Categories only as lists inside other catalogs. This avoids introducing new top-level artifacts, but prevents independent reuse and composition.