Debian Codegraph @

spec/predicates/template/template.md

raw
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.