1---
 2layout: page
 3title: Promote Capabilities to a First-class Catalog
 4---
 5
 6- **ADR:** 0019
 7- **Proposal Author(s):** @eddie-knight, @jpower432
 8- **Status:** Accepted
 9
10## Context
11
12Threats and other artifacts often need to reference system “capabilities” (features, components, or objects) as domain content.
13
14Historically, capabilities were treated as nested/ad hoc lists inside other documents, which made them hard to:
15
16- Reference consistently across artifacts
17- Extend/import and version as shared domain content
18- Maintain as their own area of ownership (distinct from threats/controls)
19
20During review of [ADR 0018](./0018-promote-nested-concepts-to-catalogs.md), we agreed that **Capabilities should stand alone** as domain content, while organizational groupings (e.g., families) should generally live in the documents that use them.
21
22## Decision
23
24Define Capabilities as a **first-class catalog artifact** with a dedicated catalog type, `#CapabilityCatalog`.
25
26### Schema shape
27
28`#CapabilityCatalog` embeds the shared `#Catalog` base and defines a typed list of capability entries.
29
30In CUE, the shape is:
31
32```cue
33#CapabilityCatalog: {
34    #Catalog
35    capabilities?: [...#Capability]
36}
37
38#Capability: {
39    id:          string
40    title:       string
41    description: string
42}
43```
44
45Threats (and other artifacts) reference capabilities using existing mapping mechanisms (e.g., `#MultiEntryMapping`) rather than duplicating capability definitions inline.
46
47## Consequences
48
49- Capabilities become reusable domain content that can be authored, versioned, imported, and extended independently of threat catalogs.
50- Tooling can validate capability references uniformly (by id) and avoid special-casing nested capability lists.
51- This introduces (or formalizes) an additional artifact type in the ecosystem (`CapabilityCatalog`) that producers/consumers may need to support.
52
53## Migration plan
54
55- Prefer capability references from threats/other catalogs via mappings to a `CapabilityCatalog`.
56- Update examples, fixtures, and documentation that currently define capabilities inline to instead:
57  - Define capabilities in a `CapabilityCatalog`
58  - Reference them from `Threat.capabilities` using mappings
59
60## Alternatives Considered
61
62### Keep capabilities nested within threat catalogs
63
64Continue defining capabilities inline in the same document as threats. Simpler for single-document use, but prevents independent lifecycle management and reuse of capability definitions across documents and teams.
65