Merge pull request #328 from adityasaky/predicate-format

Add ITE-9 predicate template

docs/new_predicate_guidelines.md

@@ -49,9 +49,10 @@ specification for you.
 
 ## Vetting process
 
-Our vetting process is simple.
+Our vetting process is simple, and is based on the process specified in [ITE-9].
 
-1.  Open a PR following [ITE-9] formatting guidelines.
+1.  Open a PR following the formatting guidelines specified in the
+    [predicate template].
     -   Add the new predicate to the list of [existing predicates].
     -   To generate Go/Python/Java language bindings for the new predicate,
         include a [protobuf definition].
@@ -74,3 +75,4 @@ Our vetting process is simple.
 [predicateType]: ../spec/v1/predicate.md#fields
 [protobuf definition]: ../protos/README.md
 [vetting process]: #vetting-process
+[predicate template]: /spec/predicates/template/template.md

spec/predicates/template/template.md

@@ -0,0 +1,87 @@
+# Predicate type: <name>
+
+Type URI:
+
+Version:
+
+Predicate Name:
+
+## Purpose
+
+This section must discuss at a high level the reason for creating the new
+predicate type. Essentially, it describes the problems that can be solved using
+the new predicate.
+
+## Use Cases
+
+This section must discuss at least one concrete use case that will be covered by
+this predicate and how the current predicate types (if any) do not solve this.
+
+## Prerequisites
+
+New predicate types may be very specific to a particular technology or
+specification, which must be detailed in the prerequisites section. The in-toto
+Attestation Framework may be a necessary prerequisite for all predicate types,
+if so it SHOULD be explicitly mentioned to err on the side of caution.
+
+## Model
+
+The in-toto Attestation Framework was designed with software supply chain
+specific metadata in mind. However, supply chains are vast and composed of many
+different components and phases. Therefore, it is important for the predicate
+type to declare at a high level the steps and functionaries (in the generic) it
+is relevant to.
+
+## Schema
+
+The schema of the predicate type is the core part of the document. It defines
+the fields included in an instantiation of the predicate, as well as rules to
+parse them.
+
+```jsonc
+{
+  // Standard attestation fields:
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [{ ... }],
+
+  // Predicate:
+  "predicateType": "<Type URI>",
+  "predicate": { ... }
+}
+```
+
+### Parsing Rules
+
+Parsing rules are important to define explicitly to ensure implementations can
+handle example attestations correctly. For example, this section can discuss how
+the predicate type is versioned, how non-specified fields must be handled, and
+so on. Attestations definitions MUST use this section to define how the parsing
+rules differ from the framework’s
+[standard parsing rules](/spec/v1/README.md#parsing-rules).
+
+### Fields
+
+This subsection defines the fields that make up the new predicate type. In
+addition to the predicate's fields, this subsection can be used to specify
+additional constraints at the statement layer.
+
+The fields must be listed with their names, the type of information they can
+hold, whether they are required or not, and a textual description of their
+expected contents. If the legal values for a field are known, or belong in a
+range, this must be specified in the description.
+
+## Example
+
+A new predicate type MUST include one or more examples. It is recommended that
+this example corresponds to the Purpose defined at the start of the document.
+
+The example included MUST be an entire in-toto attestation statement, and not
+just the predicate type. This will allow adopters and implementers to work with
+examples more easily.
+
+## Changelog and Migrations
+
+For predicate definitions, it is important to be able to clearly map the changes
+made to the schema of the predicate to its different versions. These changes and
+the steps to migrate from one to another must be detailed where appropriate.
+This section MAY be skipped for the initial version of a predicate type.