1---
 2layout: page
 3title: Mapping Boundaries
 4---
 5
 6- **ADR:** 0014
 7- **Proposal Author(s):** @jpower
 8- **Status:** Accepted
 9
10## Context
11
12The schema supports inline cross-artifact mappings (e.g., `external-mappings`) on entry types alongside self-referential fields (e.g., `see-also`).
13Inline mapping fields intended for documentation causes unbounded growth of the artifact resulting in a less than ideal artifact editing experience.
14Some inline fields serve as design justifications rather than cross-framework mappings, and should remain on the entry.
15
16## Decision
17
18We will establish two distinct mechanisms for expressing relationships, separated by ownership and scope:
19
201. Catalog owners declare design rationale directly on entries. These fields are renamed from `*-mappings` to their target nouns (`vectors`, `guidelines`, `threats`); the parent type disambiguates them from definition lists on catalogs.
21Technology-specific relationships (e.g., control-to-threat, threat-to-capability) are always inline.
222. `#MappingDocument` is a dedicated artifact for users to express alignment between independently-authored artifacts in a specific direction.
23Each mapping captures the author's assertion of relationship and strength.
24
25## Consequences
26
27- Existing inline `*-mappings` fields are removed or renamed to target nouns; this is a breaking change
28- Schema documentation must distinguish owner-authored (inline) from non-owner (MappingDocument)
29- MappingArtifacts describing mapping quality so strength is removed from inline mappings
30
31## Alternatives Considered
32
33### Keep all mappings inline
34
35Retains current schema shape but does not scale for catalogs with many cross-framework mappings.
36
37### Move all mappings to MappingDocument
38
39Catalogs become pure definitions, but a control without its threats loses its design rationale.