1---
2layout: page
3title: Mapping Document Guide
4description: Step-by-step guide to creating Gemara-compatible mapping documents
5---
6
7## What This Is
8
9This guide walks through creating a **Mapping Document** using the [Gemara](https://gemara.openssf.org/) project, building on the guidance catalog you created in the [Guidance Catalog Guide](../guidance/guidance-guide). Examples use `gemara-version: "1.2.0"` to match the [v1.2.0](https://github.com/gemaraproj/gemara/releases/tag/v1.2.0) specification release candidate; adjust if you target a different Gemara version.
10
11A mapping document captures the user's intent for how entries in a **source** artifact relate to entries in a **target** artifact. It is the place to express alignment between independently authored catalogs (e.g., your guidance to OWASP, or controls to regulations) in a single, directed way.
12
13### Using a Mapping Document vs Inline Mappings
14
15* **Mapping Documents** are for rich descriptions of relationships between two or more artifacts.
16* **Inline Mappings** are relationships that capture the author's intent or structured design rationale at the time of creating that entry.
17
18> **Note:** See the FAQ for additional context on the Mapping Documents.
19
20
21In technical terms:
22* **Source reference** is the artifact you map *from* (e.g., your guidance catalog). Its `reference-id` must match an id in `metadata.mapping-references`. **`entry-type`** on `source-reference` applies to every **source** entry id in `mappings` (see `#TypedMapping` in [mappingdocument.cue](https://github.com/gemaraproj/gemara/blob/main/mappingdocument.cue)).
23* **Target reference** is the artifact you map *to* (e.g., OWASP Top 10). Its `reference-id` must also match an id in `metadata.mapping-references`. **`entry-type`** on `target-reference` applies to every **target** row in `targets`.
24* **Mappings** are one or more atomic relationships: each links a **source** entry id (string) to one or more **targets** (`#MappingTarget` objects with `entry-id` and optional per-target fields). For `no-match`, the source has no counterpart in the target and **`targets` must be omitted**.
25* **Relationship types** (see `#RelationshipType` in [mappingdocument.cue](https://github.com/gemaraproj/gemara/blob/main/mappingdocument.cue)): `implements`, `implemented-by`, `supports`, `supported-by`, `equivalent`, `subsumes`, `no-match`, `relates-to`.
26* **Entry type** for both sides is declared once on **`source-reference`** and **`target-reference`** via `#TypedMapping`. Allowed values are `#EntryType` in [mappingdocument.cue](https://github.com/gemaraproj/gemara/blob/main/mappingdocument.cue): `Guideline`, `Statement`, `Control`, `AssessmentRequirement`, `Capability`, `Threat`, `Risk`, or `Vector`.
27* **Mapping references** in metadata use `#MappingReference` from [mapping_inline.cue](https://github.com/gemaraproj/gemara/blob/main/mapping_inline.cue) (shared with other layers); see also [metadata.cue](https://github.com/gemaraproj/gemara/blob/main/metadata.cue) for `#Metadata`.
28
29This exercise produces a mapping document that downstream tools and policies can use to understand how two artifacts align.
30
31## Optional Workflow
32
33Complete the [Guidance Catalog Guide](../guidance/guidance-guide) and have a guidance catalog (e.g., [guidance-example.yaml](../guidance/guidance-example.yaml)) with `mapping-references` that include the target framework you want to map to (e.g., OWASP). You will reference that guidance catalog as the source and the external framework as the target.
34
35## Walkthrough
36
37We use the **Secure Software Development Guidance** (`ORG.SSD.001`) from the guidance tutorial and map its guidelines to **OWASP Top 10**. The same pattern applies when mapping controls to regulations or other frameworks.
38
39### Step 0: Define Scope and References
40
41Decide which two artifacts you are mapping: **source** (the one you map *from*) and **target** (the one you map *to*). Reuse the same catalog ids as in your guidance catalog’s `mapping-references` so the mapping document can refer to them.
42
43**Leverage existing resources:** Your guidance catalog already declares `mapping-references` (e.g., OWASP). The mapping document must declare **both** the source and target in its own `metadata.mapping-references`; the source is your guidance catalog (same id as `metadata.id` in that catalog, e.g. `ORG.SSD.001`) and the target is the external framework (e.g., OWASP).
44
45We continue with the Secure Software Development Guidance as source and OWASP Top 10 as target.
46
47### Step 1: Setting Up Metadata
48
49Declare your mapping document and mapping references. Key fields:
50
51| Field | What It Is | Why |
52|-------------------------------------|--------------------------------------------------------------|-------------------------------------------------------------------------------------------|
53| `title` | Display name for the mapping document (top-level) | Human-readable label in reports and tooling |
54| `metadata.id` | Unique identifier for this mapping document | Used when other documents or tools reference this mapping |
55| `metadata.type` | `MappingDocument` | Required by schema; identifies the Gemara artifact type |
56| `metadata.description` | High-level summary of what is being mapped and why | Required by schema; clarifies intent |
57| `metadata.mapping-references` | List of source and target artifacts (by id) | **Required** for MappingDocument; `source-reference` and `target-reference` must match ids here |
58
59> **Note:** Both `source-reference.reference-id` and `target-reference.reference-id` must appear in `metadata.mapping-references`.
60
61**Example (YAML):**
62
63```yaml
64title: Secure Software Development Guidance to OWASP Top 10
65metadata:
66 id: SSD-OWASP-MAP-001
67 version: "1.0.0"
68 type: MappingDocument
69 gemara-version: "1.2.0"
70 description: >
71 Maps Secure Software Development Guidance guidelines to OWASP Top 10
72 categories. Minimal example for tutorials; relationship types are relates-to.
73 author:
74 id: gemara-example
75 name: Gemara Example Author
76 type: Human
77 mapping-references:
78 - id: ORG.SSD.001
79 title: Secure Software Development Guidance
80 version: "1.0.0"
81 url: "file://../guidance/guidance-example.yaml"
82 - id: OWASP
83 title: OWASP Top 10
84 version: "2021"
85 url: "https://owasp.org/Top10"
86```
87
88### Step 2: Source and Target References (`#TypedMapping`)
89
90Set **`source-reference`** and **`target-reference`**. Each is a **typed mapping**: `reference-id` (must match `metadata.mapping-references`) plus **`entry-type`** for all entries on that side of the document. Optionally add top-level **remarks** to describe the mapping.
91
92| Field | What It Is |
93|---------------------|----------------------------------------------------------------------------|
94| `source-reference` | Artifact you map *from*; `reference-id` and required `entry-type` |
95| `target-reference` | Artifact you map *to*; `reference-id` and required `entry-type` |
96| `remarks` | Optional prose about this mapping document as a whole |
97
98**Example (YAML):**
99
100```yaml
101source-reference:
102 reference-id: ORG.SSD.001
103 entry-type: Guideline
104target-reference:
105 reference-id: OWASP
106 entry-type: Guideline
107remarks: Guidance guidelines ORG.SSD.GL01–GL03 mapped to OWASP for tutorial use.
108```
109
110### Step 3: Define Mappings
111
112Define one or more **mappings**. Each mapping has a **source** string (the source entry’s id) and, unless `relationship` is `no-match`, a non-empty **`targets`** list. Each list element is a **`#MappingTarget`**: at minimum `entry-id`, plus optional `strength`, `confidence-level`, `applicability`, `rationale`, and `remarks` for that target (see [mappingdocument.cue](https://github.com/gemaraproj/gemara/blob/main/mappingdocument.cue)).
113
114| Field | Required | Description |
115|-----------------------|----------|-----------------------------------------------------------------------------|
116| `id` | Yes | Unique identifier for this mapping |
117| `source` | Yes | Source entry id (string), matching an entry in the source artifact |
118| `targets` | Yes* | Non-empty list of `{ entry-id: ... }` (and optional per-target fields). Omit only when `relationship` is `no-match` |
119| `relationship` | Yes | One of `implements`, `implemented-by`, `supports`, `supported-by`, `equivalent`, `subsumes`, `no-match`, `relates-to` |
120| `remarks` | No | General prose regarding this mapping |
121
122**Example (YAML):** Map the three guidelines from the Secure Software Development Guidance (`ORG.SSD.GL01`, `GL02`, `GL03`) to OWASP Top 10 categories (`A06`, `A01`, `A02`):
123
124```yaml
125mappings:
126 - id: GL01-A06
127 source: ORG.SSD.GL01
128 relationship: relates-to
129 targets:
130 - entry-id: "A06"
131 strength: 7
132 rationale: Immutable image references support supply chain integrity; OWASP A06 covers vulnerable and outdated components.
133
134 - id: GL02-A01
135 source: ORG.SSD.GL02
136 relationship: relates-to
137 targets:
138 - entry-id: "A01"
139 strength: 6
140 rationale: Branch protection reduces unauthorized code changes; OWASP A01 covers broken access control.
141
142 - id: GL03-A02
143 source: ORG.SSD.GL03
144 relationship: relates-to
145 targets:
146 - entry-id: "A02"
147 strength: 6
148 rationale: VPN on untrusted networks protects data in transit; OWASP A02 covers cryptographic failures.
149```
150
151For **`no-match`**, omit **`targets`** entirely (the source entry has no counterpart in the target artifact).
152
153### Step 4: Validate against the Mapping Document Schema
154
155Validate with CUE:
156
157**Validation commands:**
158
159```bash
160go install cuelang.org/go/cmd/cue@latest
161cue vet -c -d '#MappingDocument' github.com/gemaraproj/gemara@latest your-mapping-document-example.yaml
162```
163
164From a **clone of this repository** (run from the repo root; replace the placeholder with your file path):
165
166```bash
167cue vet -c -d '#MappingDocument' . your-mapping-document-example.yaml
168```
169
170A reference copy is [mapping-document.yaml](mapping-document.yaml) in this directory.
171
172### Step 5: Assemble the Full Document and Validate
173
174Combine metadata, source-reference, target-reference, remarks, and mappings into a single YAML document. The following is the full tutorial example (kept in sync with [mapping-document.yaml](mapping-document.yaml) in this directory):
175
176```yaml
177# Secure Software Development Guidance to OWASP Top 10 (tutorial example)
178# Conforms to Gemara #MappingDocument (mappingdocument.cue).
179# gemara-version: v1.2.0 — https://github.com/gemaraproj/gemara/releases/tag/v1.2.0
180# Source guidance catalog: ../guidance/guidance-example.yaml (metadata.id ORG.SSD.001)
181# entry-type on source-reference / target-reference applies to all entries on that side (#TypedMapping).
182title: Secure Software Development Guidance to OWASP Top 10
183metadata:
184 id: SSD-OWASP-MAP-001
185 version: "1.0.0"
186 type: MappingDocument
187 gemara-version: "1.2.0"
188 description: >
189 Maps Secure Software Development Guidance guidelines to OWASP Top 10
190 categories. Minimal example for tutorials; relationship types are relates-to.
191 author:
192 id: gemara-example
193 name: Gemara Example Author
194 type: Human
195 mapping-references:
196 - id: ORG.SSD.001
197 title: Secure Software Development Guidance
198 version: "1.0.0"
199 url: "file://../guidance/guidance-example.yaml"
200 - id: OWASP
201 title: OWASP Top 10
202 version: "2021"
203 url: "https://owasp.org/Top10"
204
205source-reference:
206 reference-id: ORG.SSD.001
207 entry-type: Guideline
208target-reference:
209 reference-id: OWASP
210 entry-type: Guideline
211remarks: Guidance guidelines ORG.SSD.GL01–GL03 mapped to OWASP for tutorial use.
212
213mappings:
214 - id: GL01-A06
215 source: ORG.SSD.GL01
216 relationship: relates-to
217 targets:
218 - entry-id: "A06"
219 strength: 7
220 rationale: Immutable image references support supply chain integrity; OWASP A06 covers vulnerable and outdated components.
221
222 - id: GL02-A01
223 source: ORG.SSD.GL02
224 relationship: relates-to
225 targets:
226 - entry-id: "A01"
227 strength: 6
228 rationale: Branch protection reduces unauthorized code changes; OWASP A01 covers broken access control.
229
230 - id: GL03-A02
231 source: ORG.SSD.GL03
232 relationship: relates-to
233 targets:
234 - entry-id: "A02"
235 strength: 6
236 rationale: VPN on untrusted networks protects data in transit; OWASP A02 covers cryptographic failures.
237```
238
239**Validate** from the repo root against the checked-in example:
240
241```bash
242cue vet -c -d '#MappingDocument' . docs/tutorials/mapping/mapping-document.yaml
243```
244
245Fix any errors (e.g. missing `mapping-references`, invalid relationship type, missing **`targets`** when relationship is not `no-match`, missing **`entry-type`** on `source-reference` / `target-reference`, or `entry-type` not in the allowed set) so the document is schema-valid.
246
247## Summary: From Guidance Catalog to Mapping Document
248
249| From guidance catalog | Use in mapping document |
250|------------------------------|----------------------------------------------------------------|
251| Catalog id (e.g. `ORG.SSD.001` in mapping-references) | Same id as `source-reference.reference-id` and in `metadata.mapping-references` |
252| Guideline ids (e.g. ORG.SSD.GL01) | `source` string in each mapping |
253| External framework in mapping-references (e.g. OWASP) | Same id as `target-reference.reference-id` and in `metadata.mapping-references` |
254| Target framework entry ids (e.g. A06, A01) | `entry-id` under `targets` in each mapping |
255| Kind of entries (e.g. guidelines on both sides) | `entry-type` on `source-reference` and `target-reference` (`#TypedMapping`) |
256
257## What's Next
258
259- Use this mapping in **Layer 2** or **Layer 3** workflows to show how your guidance or controls align to external frameworks.
260- Use **multiple targets** in one mapping when one source row aligns to several target entries (each target is a `#MappingTarget` with its own optional metadata).
261- Add **applicability-groups** in metadata and use `applicability` on mappings or on individual `#MappingTarget` rows when the relationship holds only in certain contexts
262
263See the [Mapping Document schema](https://gemara.openssf.org/schema/mappingdocument.html) and the CUE module: [mappingdocument.cue](https://github.com/gemaraproj/gemara/blob/main/mappingdocument.cue) (`#MappingDocument`, `#TypedMapping`, `#Mapping`, `#MappingTarget`, relationships, entry types) and [mapping_inline.cue](https://github.com/gemaraproj/gemara/blob/main/mapping_inline.cue) (`#MappingReference`, `#ArtifactMapping`, and related shared types).