editorial: Clarify DependencyLevels, SlsaResult, and quote level keys.

Signed-off-by: Zhenyu Wu <[email protected]>
slsa-framework · Oct 13, 2023 · 5a76d99 · 5a76d99
1 parent 88dfad6
commit 5a76d99
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 35 deletions.
diff --git a/docs/spec/v1.0/verification_summary.md b/docs/spec/v1.0/verification_summary.md
@@ -180,8 +180,8 @@ of the other top-level fields, such as `subject`, see [Statement]._
 > its dependencies), or "FAILED" if policy verification failed.
 >
 > Users MUST NOT include more than one level per SLSA track. Note that each SLSA
-> level implies all levels below it (e.g. SLSA_BUILD_LEVEL_3 implies
-> SLSA_BUILD_LEVEL_2 and SLSA_BUILD_LEVEL_1), so there is no need to
+> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies
+> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to
 > include more than one level per track.
 
 <a id="dependencyLevels"></a>
@@ -191,12 +191,15 @@ of the other top-level fields, such as `subject`, see [Statement]._
 >
 > Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies
 > that were verified at the indicated level. Absence of a given level of
-> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level.
+> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level,
+> e.g. an empty `dependencyLevels` object means that the artifact has **no**
+> dependency at all (vs. a non-present, i.e. "null", `dependencyLevels` means
+> that the verifier does not disclose the dependency stats).
 >
 > Users MUST count each dependency only once per SLSA track, at the highest
-> level verified. For example, if a dependency meets SLSA_BUILD_LEVEL_2,
-> you include it with the count for SLSA_BUILD_LEVEL_2 but not the count for
->SLSA_BUILD_LEVEL_1.
+> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`,
+> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for
+> the other `SLSA_BUILD` levels.
 
 <a id="slsaVersion"></a>
 `slsaVersion` _string, optional_
@@ -252,17 +255,19 @@ WARNING: This is just for demonstration purposes.
 </div>
 
 The result of evaluating an artifact (or set of artifacts) against SLSA.
-SHOULD be one of these values:
-
--   SLSA_BUILD_LEVEL_0
--   SLSA_BUILD_LEVEL_1
--   SLSA_BUILD_LEVEL_2
--   SLSA_BUILD_LEVEL_3
--   FAILED (Indicates policy evaluation failed)
-
-Note that each SLSA level implies the levels below it. For example,
-SLSA_BUILD_LEVEL_3 means (SLSA_BUILD_LEVEL_1 + SLSA_BUILD_LEVEL_2 +
-SLSA_BUILD_LEVEL_3).
+SHOULD contain one value per SLSA track:
+
+-   SLSA BUILD track:
+    -   `SLSA_BUILD_LEVEL_UNEVALUATED`
+    -   `SLSA_BUILD_LEVEL_0`
+    -   `SLSA_BUILD_LEVEL_1`
+    -   `SLSA_BUILD_LEVEL_2`
+    -   `SLSA_BUILD_LEVEL_3`
+-   FAILED (Indicates policy evaluation failed, optional)
+
+Note that each SLSA level implies the levels below it in the same track.
+For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` +
+`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`).
 
 Users MAY use custom values here but MUST NOT use custom values starting with
 `SLSA_`.

diff --git a/docs/spec/v1.1/verification_summary.md b/docs/spec/v1.1/verification_summary.md
@@ -180,8 +180,8 @@ of the other top-level fields, such as `subject`, see [Statement]._
 > its dependencies), or "FAILED" if policy verification failed.
 >
 > Users MUST NOT include more than one level per SLSA track. Note that each SLSA
-> level implies all levels below it (e.g. SLSA_BUILD_LEVEL_3 implies
-> SLSA_BUILD_LEVEL_2 and SLSA_BUILD_LEVEL_1), so there is no need to
+> level implies all levels below it (e.g. `SLSA_BUILD_LEVEL_3` implies
+> `SLSA_BUILD_LEVEL_2` and `SLSA_BUILD_LEVEL_1`), so there is no need to
 > include more than one level per track.
 
 <a id="dependencyLevels"></a>
@@ -191,12 +191,15 @@ of the other top-level fields, such as `subject`, see [Statement]._
 >
 > Map from [SlsaResult] to the number of the artifact's _transitive_ dependencies
 > that were verified at the indicated level. Absence of a given level of
-> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level.
+> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level,
+> e.g. an empty `dependencyLevels` object means that the artifact has **no**
+> dependency at all (vs. a non-present, i.e. "null", `dependencyLevels` means
+> that the verifier does not disclose the dependency stats).
 >
 > Users MUST count each dependency only once per SLSA track, at the highest
-> level verified. For example, if a dependency meets SLSA_BUILD_LEVEL_2,
-> you include it with the count for SLSA_BUILD_LEVEL_2 but not the count for
->SLSA_BUILD_LEVEL_1.
+> level verified. For example, if a dependency meets `SLSA_BUILD_LEVEL_2`,
+> you include it with the count for `SLSA_BUILD_LEVEL_2` but not the count for
+> the other `SLSA_BUILD` levels.
 
 <a id="slsaVersion"></a>
 `slsaVersion` _string, optional_
@@ -349,18 +352,19 @@ verifiers they add to their roots of trust.
 </div>
 
 The result of evaluating an artifact (or set of artifacts) against SLSA.
-SHOULD be one of these values:
-
--   SLSA_BUILD_LEVEL_UNEVALUATED
--   SLSA_BUILD_LEVEL_0
--   SLSA_BUILD_LEVEL_1
--   SLSA_BUILD_LEVEL_2
--   SLSA_BUILD_LEVEL_3
--   FAILED (Indicates policy evaluation failed)
-
-Note that each SLSA level implies the levels below it. For example,
-SLSA_BUILD_LEVEL_3 means (SLSA_BUILD_LEVEL_1 + SLSA_BUILD_LEVEL_2 +
-SLSA_BUILD_LEVEL_3).
+SHOULD contain one value per SLSA track:
+
+-   SLSA BUILD track:
+    -   `SLSA_BUILD_LEVEL_UNEVALUATED`
+    -   `SLSA_BUILD_LEVEL_0`
+    -   `SLSA_BUILD_LEVEL_1`
+    -   `SLSA_BUILD_LEVEL_2`
+    -   `SLSA_BUILD_LEVEL_3`
+-   FAILED (Indicates policy evaluation failed, optional)
+
+Note that each SLSA level implies the levels below it in the same track.
+For example, `SLSA_BUILD_LEVEL_3` means (`SLSA_BUILD_LEVEL_1` +
+`SLSA_BUILD_LEVEL_2` + `SLSA_BUILD_LEVEL_3`).
 
 Users MAY use custom values here but MUST NOT use custom values starting with
 `SLSA_`.