editorial: state predicateType explicitly (slsa-framework#935)

In the top of the Provenance and VSA specification pages, explicitly state the `predicateType` and instruct the reader to use this string rather than the URL. Also move the link to in-toto and the RFC 2119 blurb (if present) up there as well. Motivation: 1. Remove ambiguity, particularly around trailing slashes. 2. Open the path to move provenance and VSA underneath the spec directory, so that everything is versioned together. If that happens, we'll redirect the `predicateType` URI to the latest minor version. Signed-off-by: Mark Lodato <lodato@google.com>
joshuagl · Aug 7, 2023 · 42b51dc · 42b51dc
1 parent 99e2756
commit 42b51dc
Show file tree

Hide file tree

Showing 9 changed files with 121 additions and 67 deletions.
diff --git a/docs/provenance/v0.1.md b/docs/provenance/v0.1.md
@@ -11,6 +11,18 @@ something was produced. For higher SLSA levels and more resilient integrity
 guarantees, provenance requirements are stricter and need a deeper, more
 technical understanding of the predicate.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/provenance/v0.1"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
 ## Purpose
 
 Describe how an artifact or set of artifacts was produced.
@@ -488,5 +500,6 @@ Execution of arbitrary commands:
 [Statement]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#statement
 [Timestamp]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#Timestamp
 [TypeURI]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/field_types.md#TypeURI
+[in-toto attestation]: https://github.com/in-toto/attestation
 [parsing rules]: https://github.com/in-toto/attestation/blob/main/spec/v0.1.0/README.md#parsing-rules
 [provenance requirements]: ../spec/v0.1/requirements#provenance-requirements
diff --git a/docs/provenance/v0.2.md b/docs/provenance/v0.2.md
@@ -11,18 +11,25 @@ something was produced. For higher SLSA levels and more resilient integrity
 guarantees, provenance requirements are stricter and need a deeper, more
 technical understanding of the predicate.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/provenance/v0.2"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
 ## Purpose
 
 Describe how an artifact or set of artifacts was produced.
 
 This predicate is the recommended way to satisfy the SLSA [provenance
 requirements].
 
-## Prerequisite
-
-Understanding of SLSA [Software Attestations](/attestation-model)
-and the larger [in-toto attestation] framework.
-
 ## Model
 
 Provenance is an attestation that some entity (`builder`) produced one or more

diff --git a/docs/provenance/v1-rc1.md b/docs/provenance/v1-rc1.md
@@ -3,18 +3,29 @@ title: Provenance
 description: Description of SLSA provenance specification for verifying where, when, and how something was produced.
 layout: standard
 ---
-<!-- Note: We only include the major version in the URL, e.g. "v1" instead of
-"v1.0", because minor versions are guaranteed to be backwards compatible. We
-still include the minor version number in the selector (_data/versions.yml) so
-that readers can easily find the current minor version number. -->
-
 To trace software back to the source and define the moving parts in a complex
 supply chain, provenance needs to be there from the very beginning. It's the
 verifiable information about software artifacts describing where, when and how
 something was produced. For higher SLSA levels and more resilient integrity
 guarantees, provenance requirements are stricter and need a deeper, more
 technical understanding of the predicate.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/provenance/v1-rc1"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
 ## Purpose
 
 Describe how an artifact or set of artifacts was produced so that:
@@ -26,15 +37,6 @@ Describe how an artifact or set of artifacts was produced so that:
 This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance
 requirements](/spec/v1.0-rc1/requirements#provenance-generation).
 
-## Prerequisite
-
-Understanding of SLSA [Software Attestations](/attestation-model)
-and the larger [in-toto attestation] framework.
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
-"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
-interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
-
 ## Model
 
 Provenance is an attestation that the `builder` produced the `subject` software

diff --git a/docs/provenance/v1-rc2.md b/docs/provenance/v1-rc2.md
@@ -3,18 +3,29 @@ title: Provenance
 description: Description of SLSA provenance specification for verifying where, when, and how something was produced.
 layout: standard
 ---
-<!-- Note: We only include the major version in the URL, e.g. "v1" instead of
-"v1.0", because minor versions are guaranteed to be backwards compatible. We
-still include the minor version number in the selector (_data/versions.yml) so
-that readers can easily find the current minor version number. -->
-
 To trace software back to the source and define the moving parts in a complex
 supply chain, provenance needs to be there from the very beginning. It's the
 verifiable information about software artifacts describing where, when and how
 something was produced. For higher SLSA levels and more resilient integrity
 guarantees, provenance requirements are stricter and need a deeper, more
 technical understanding of the predicate.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/provenance/v1-rc2"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
 ## Purpose
 
 Describe how an artifact or set of artifacts was produced so that:
@@ -26,15 +37,6 @@ Describe how an artifact or set of artifacts was produced so that:
 This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance
 requirements](/spec/v1.0-rc2/requirements#provenance-generation).
 
-## Prerequisite
-
-Understanding of SLSA [Software Attestations](/attestation-model)
-and the larger [in-toto attestation] framework.
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
-"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
-interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
-
 ## Model
 
 Provenance is an attestation that a particular build platform produced a set of

diff --git a/docs/provenance/v1.md b/docs/provenance/v1.md
@@ -3,18 +3,29 @@ title: Provenance
 description: Description of SLSA provenance specification for verifying where, when, and how something was produced.
 layout: standard
 ---
-<!-- Note: We only include the major version in the URL, e.g. "v1" instead of
-"v1.0", because minor versions are guaranteed to be backwards compatible. We
-still include the minor version number in the selector (_data/versions.yml) so
-that readers can easily find the current minor version number. -->
-
 To trace software back to the source and define the moving parts in a complex
 supply chain, provenance needs to be there from the very beginning. It's the
 verifiable information about software artifacts describing where, when and how
 something was produced. For higher SLSA levels and more resilient integrity
 guarantees, provenance requirements are stricter and need a deeper, more
 technical understanding of the predicate.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/provenance/v1"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
 ## Purpose
 
 Describe how an artifact or set of artifacts was produced so that:
@@ -26,15 +37,6 @@ Describe how an artifact or set of artifacts was produced so that:
 This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 [provenance
 requirements](/spec/v1.0/requirements#provenance-generation).
 
-## Prerequisite
-
-Understanding of SLSA [Software Attestations](/attestation-model)
-and the larger [in-toto attestation] framework.
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
-"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
-interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
-
 ## Model
 
 Provenance is an attestation that a particular build platform produced a set of

diff --git a/docs/verification_summary/v0.1.md b/docs/verification_summary/v0.1.md
@@ -7,6 +7,18 @@ layout: standard
 Verification summary attestations communicate that an artifact has been verified
 at a specific SLSA level and details about that verification.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/verification_summary/v0.1"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
 ## Purpose
 
 Describe what SLSA level an artifact or set of artifacts was verified at
@@ -25,11 +37,6 @@ This might be necessary for legal reasons (keeping a software supplier
 confidential) or for security reasons (not revealing that an embargoed patch has
 been included).
 
-## Prerequisite
-
-Understanding of SLSA [Software Attestations](/attestation-model),
-[SLSA Provenance](/provenance), and the larger [in-toto attestation] framework.
-
 ## Model
 
 A Verification Summary Attestation (VSA) is an attestation that some entity

diff --git a/docs/verification_summary/v0.2.md b/docs/verification_summary/v0.2.md
@@ -7,6 +7,18 @@ layout: standard
 Verification summary attestations communicate that an artifact has been verified
 at a specific SLSA level and details about that verification.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/verification_summary/v0.2"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
 ## Purpose
 
 Describe what SLSA level an artifact or set of artifacts was verified at
@@ -25,11 +37,6 @@ This might be necessary for legal reasons (keeping a software supplier
 confidential) or for security reasons (not revealing that an embargoed patch has
 been included).
 
-## Prerequisite
-
-Understanding of SLSA [Software Attestations](/attestation-model),
-[SLSA Provenance](/provenance), and the larger [in-toto attestation] framework.
-
 ## Model
 
 A Verification Summary Attestation (VSA) is an attestation that some entity

diff --git a/docs/verification_summary/v1-rc2.md b/docs/verification_summary/v1-rc2.md
@@ -7,6 +7,18 @@ layout: standard
 Verification summary attestations communicate that an artifact has been verified
 at a specific SLSA level and details about that verification.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/verification_summary/v1-rc2"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
 ## Purpose
 
 Describe what SLSA level an artifact or set of artifacts was verified at
@@ -25,11 +37,6 @@ This might be necessary for legal reasons (keeping a software supplier
 confidential) or for security reasons (not revealing that an embargoed patch has
 been included).
 
-## Prerequisite
-
-Understanding of SLSA [Software Attestations](/attestation-model),
-[SLSA Provenance], and the larger [in-toto attestation] framework.
-
 ## Model
 
 A Verification Summary Attestation (VSA) is an attestation that some entity

diff --git a/docs/verification_summary/v1.md b/docs/verification_summary/v1.md
@@ -7,6 +7,18 @@ layout: standard
 Verification summary attestations communicate that an artifact has been verified
 at a specific SLSA level and details about that verification.
 
+This document defines the following predicate type within the [in-toto
+attestation] framework:
+
+```json
+"predicateType": "https://slsa.dev/verification_summary/v1"
+```
+
+> Important: Always use the above string for `predicateType` rather than what is
+> in the URL bar. The `predicateType` URI will always resolve to the latest
+> minor version of this specification. See [parsing rules](#parsing-rules) for
+> more information.
+
 ## Purpose
 
 Describe what SLSA level an artifact or set of artifacts was verified at
@@ -25,11 +37,6 @@ This might be necessary for legal reasons (keeping a software supplier
 confidential) or for security reasons (not revealing that an embargoed patch has
 been included).
 
-## Prerequisite
-
-Understanding of SLSA [Software Attestations](/attestation-model),
-[SLSA Provenance], and the larger [in-toto attestation] framework.
-
 ## Model
 
 A Verification Summary Attestation (VSA) is an attestation that some entity