• ADR: 0014
  • Proposal Author(s): @jpower
  • Status: Accepted

Context

The schema supports inline cross-artifact mappings (e.g., external-mappings) on entry types alongside self-referential fields (e.g., see-also). Inline mapping fields intended for documentation causes unbounded growth of the artifact resulting in a less than ideal artifact editing experience. Some inline fields serve as design justifications rather than cross-framework mappings, and should remain on the entry.

Decision

We will establish two distinct mechanisms for expressing relationships, separated by ownership and scope:

  1. 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. Technology-specific relationships (e.g., control-to-threat, threat-to-capability) are always inline.
  2. #MappingDocument is a dedicated artifact for users to express alignment between independently-authored artifacts in a specific direction. Each mapping captures the author’s assertion of relationship and strength.

Consequences

  • Existing inline *-mappings fields are removed or renamed to target nouns; this is a breaking change
  • Schema documentation must distinguish owner-authored (inline) from non-owner (MappingDocument)
  • MappingArtifacts describing mapping quality so strength is removed from inline mappings

Alternatives Considered

Keep all mappings inline

Retains current schema shape but does not scale for catalogs with many cross-framework mappings.

Move all mappings to MappingDocument

Catalogs become pure definitions, but a control without its threats loses its design rationale.