Type URI:
Version:
Predicate Name:
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.
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.
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.
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.
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.
{
// Standard attestation fields:
"_type": "https://in-toto.io/Statement/v1",
"subject": [{ ... }],
// Predicate:
"predicateType": "<Type URI>",
"predicate": { ... }
}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.
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.
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.
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.