| 1 |
# Predicate type: <name> |
| 2 |
|
| 3 |
Type URI: |
| 4 |
|
| 5 |
Version: |
| 6 |
|
| 7 |
Predicate Name: |
| 8 |
|
| 9 |
## Purpose |
| 10 |
|
| 11 |
This section must discuss at a high level the reason for creating the new |
| 12 |
predicate type. Essentially, it describes the problems that can be solved using |
| 13 |
the new predicate. |
| 14 |
|
| 15 |
## Use Cases |
| 16 |
|
| 17 |
This section must discuss at least one concrete use case that will be covered by |
| 18 |
this predicate and how the current predicate types (if any) do not solve this. |
| 19 |
|
| 20 |
## Prerequisites |
| 21 |
|
| 22 |
New predicate types may be very specific to a particular technology or |
| 23 |
specification, which must be detailed in the prerequisites section. The in-toto |
| 24 |
Attestation Framework may be a necessary prerequisite for all predicate types, |
| 25 |
if so it SHOULD be explicitly mentioned to err on the side of caution. |
| 26 |
|
| 27 |
## Model |
| 28 |
|
| 29 |
The in-toto Attestation Framework was designed with software supply chain |
| 30 |
specific metadata in mind. However, supply chains are vast and composed of many |
| 31 |
different components and phases. Therefore, it is important for the predicate |
| 32 |
type to declare at a high level the steps and functionaries (in the generic) it |
| 33 |
is relevant to. |
| 34 |
|
| 35 |
## Schema |
| 36 |
|
| 37 |
The schema of the predicate type is the core part of the document. It defines |
| 38 |
the fields included in an instantiation of the predicate, as well as rules to |
| 39 |
parse them. |
| 40 |
|
| 41 |
```jsonc |
| 42 |
{ |
| 43 |
// Standard attestation fields: |
| 44 |
"_type": "https://in-toto.io/Statement/v1", |
| 45 |
"subject": [{ ... }], |
| 46 |
|
| 47 |
// Predicate: |
| 48 |
"predicateType": "<Type URI>", |
| 49 |
"predicate": { ... } |
| 50 |
} |
| 51 |
``` |
| 52 |
|
| 53 |
### Parsing Rules |
| 54 |
|
| 55 |
Parsing rules are important to define explicitly to ensure implementations can |
| 56 |
handle example attestations correctly. For example, this section can discuss how |
| 57 |
the predicate type is versioned, how non-specified fields must be handled, and |
| 58 |
so on. Attestations definitions MUST use this section to define how the parsing |
| 59 |
rules differ from the frameworkâs |
| 60 |
[standard parsing rules](/spec/v1/README.md#parsing-rules). |
| 61 |
|
| 62 |
### Fields |
| 63 |
|
| 64 |
This subsection defines the fields that make up the new predicate type. In |
| 65 |
addition to the predicate's fields, this subsection can be used to specify |
| 66 |
additional constraints at the statement layer. |
| 67 |
|
| 68 |
The fields must be listed with their names, the type of information they can |
| 69 |
hold, whether they are required or not, and a textual description of their |
| 70 |
expected contents. If the legal values for a field are known, or belong in a |
| 71 |
range, this must be specified in the description. |
| 72 |
|
| 73 |
## Example |
| 74 |
|
| 75 |
A new predicate type MUST include one or more examples. It is recommended that |
| 76 |
this example corresponds to the Purpose defined at the start of the document. |
| 77 |
|
| 78 |
The example included MUST be an entire in-toto attestation statement, and not |
| 79 |
just the predicate type. This will allow adopters and implementers to work with |
| 80 |
examples more easily. |
| 81 |
|
| 82 |
## Changelog and Migrations |
| 83 |
|
| 84 |
For predicate definitions, it is important to be able to clearly map the changes |
| 85 |
made to the schema of the predicate to its different versions. These changes and |
| 86 |
the steps to migrate from one to another must be detailed where appropriate. |
| 87 |
This section MAY be skipped for the initial version of a predicate type. |