editorial: state predicateType explicitly

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>

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

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

docs/provenance/v1-rc1.md

@@ -15,6 +15,22 @@ 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 +42,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

docs/provenance/v1-rc2.md

@@ -15,6 +15,22 @@ 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 +42,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

docs/provenance/v1.md

@@ -15,6 +15,22 @@ 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 +42,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

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

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

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

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