+| Field | Type | Description
+
+ |
|---|
buildType
+ | string (TypeURI) |
+
+Identifies the template for how to perform the build and interpret the
+parameters and dependencies.
+
+The URI SHOULD resolve to a human-readable specification that includes: overall
+description of the build type; a list of all parameters (name, description,
+external vs system, artifact vs scalar vs..., required vs optional, etc.);
+unambiguous instructions for how to initiate the build given this
+BuildDefinition, and a complete example. Example:
+https://slsa.dev/github-actions-workflow/v0.1
+
+ |
externalParameters
+ | map (string→ParameterValue) |
+
+The parameters that are under external control, such as those set by a user or
+tenant of the build system. They MUST be complete at SLSA Build L3, meaning that
+that there is no additional mechanism for an external party to influence the
+build. (At lower SLSA Build levels, the completeness MAY be best effort.)
+
+The build system SHOULD be designed to minimize the size and complexity of
+`externalParameters`, in order to reduce fragility and ease [verification].
+Consumers SHOULD have an expectation of what "good" looks like; the more
+information that they need to check, the harder that task becomes.
+
+ |
systemParameters
+ | map (string→ParameterValue) |
+
+The parameters that are under the control of the `builder`. The primary
+intention of this field is for debugging, incident response, and vulnerability
+management. The values here MAY be necessary for reproducing the build. There is
+no need to [verify][Verification] these parameters because the build system is
+already trusted, and in many cases it is not practical to do so.
+
+ |
resolvedDependencies
+ | array (ArtifactReference) |
+
+Collection of artifacts needed at build time, aside from those listed in
+`externalParameters` or `systemParameters`. For example, if the build script
+fetches and executes "example.com/foo.sh", which in turn fetches
+"example.com/bar.tar.gz", then both "foo.sh" and "bar.tar.gz" should be listed
+here.
+
+ |
+
+The BuildDefinition describes all of the inputs to the build. It SHOULD contain
+all the information necessary and sufficient to initialize the build and begin
+execution.
+
+The `externalParameters` and `systemParameters` are the top-level inputs to the
+template, meaning inputs not derived from another input. Each field is a map
+from parameter name to [parameter value][ParameterValue]. The each parameter
+name MUST be unique across `externalParameters` and `systemParameters`. The
+following conventional names are RECOMMENDED when appropriate:
+
+- `source`: The primary input to the build.
+- `config`: The build configuration, if different from `source`.
+
+Guidelines:
+
+- Maximize the amount of information that is implicit from the meaning of
+ `buildType`. In particular, any value that is boilerplate and the same
+ for every build SHOULD be implicit.
+
+- Reduce parameters by moving configuration to input artifacts whenever
+ possible. For example, instead of passing in compiler flags via an external
+ parameter that has to be [verified][Verification] separately, require the
+ flags to live next to the source code or build configuration so that
+ verifying the latter automatically verifies the compiler flags.
+
+- If possible, architect the build system to use this definition as its
+ sole top-level input, in order to guarantee that the information is
+ sufficient to run the build.
+
+- In some cases, the build configuration is evaluated client-side and
+ sent over the wire, such that the build system cannot determine its
+ origin. In those cases, the build system SHOULD serialize the
+ configuration in a deterministic way and record the `digest` without a
+ `uri`. This allows one to consider the client-side evaluation as a
+ separate "build" with its own provenance, such that the verifier can
+ chain the two provenance attestations together to determine the origin
+ of the configuration.
+
+**TODO:** Explain the purpose of `resolvedDependencies`. Why do we need it? What
+goes in it? Is it OK for it to be incomplete? If a dependency is already pinned,
+does it need to be listed? How does one choose between `resolvedDependencies`
+and `builderDependencies`?
+
+### ParameterValue
+
+[ParameterValue]: #parametervalue
+
+REQUIRED: exactly one of the fields MUST be set.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `artifactRef` | [ArtifactReference] | Reference to an artifact. |
+| `scalarValue` | string | Scalar value. |
+| `mapValue` | map (string→string) | Unordered collection of name/value pairs. |
+| `arrayValue` | array (string) | Ordered collection of values. |
+
+For simplicity, only string values or collections of string values are
+supported.
+
+> ⚠ **RFC:** The design of parameters is still not settled. We welcome feedback
+> on this particular design and suggestions for alternatives. In particular:
+>
+> - How restrictive should we be? This is somewhat of a balance between making
+> it easier for the builder vs [verifier][Verification]. A very restrictive
+> type, such as only strings, makes it easier to set expectations but harder
+> for a builder to describe reality. A very open type, such as an arbitrary
+> JSON object, provides a lot of freedom to builders but possibly at the
+> cost of complexity in terms of expectations.
+> - Is there a better way to express types than using field names?
+> - Do we need [ArtifactReference]? Would it instead make sense to just have
+> the raw parameter here and then represent the digest in
+> `resolvedDependencies`? What is the specific use case?
+>
+> Alternatives considered so far:
+>
+> - Only allow strings (difficult for many builders)
+> - Allow strings, maps of strings, or arrays of strings (current design)
+> - Allow arbitrary JSON (challenge: how do we do [ArtifactReference]?)
+
+### ArtifactReference
+
+[ArtifactReference]: #artifactreference
+
+REQUIRED: at least one of `uri` or `digest`
+
+
+| Field | Type | Description
+
+ |
|---|
id
+ | string (TypeURI) |
+
+URI indicating the transitive closure of the trusted builder.
+
+**TODO:** In most cases this is implicit from the envelope layer (e.g. the
+public key or x.509 certificate), which is just one more thing to mess up. Can
+we rescope this to avoid the duplication and thus the security concern? For
+example, if the envelope identifies the build system, this might identify the
+tenant project?
+
+**TODO:** Provide guidance on how to choose a URI, what scope it should have,
+stability, how [verification] works, etc.
+
+ |
version
+ | map (string→string) |
+
+Version numbers of components of the builder.
+
+ |
builderDependencies
+ | array (ArtifactReference) |
+
+Dependencies used by the orchestrator that are not run within the workload and
+that should not affect the build, but may affect the provenance generation or
+security guarantees.
+
+**TODO:** Flesh out this model more.
+
+ |
+
+The builder represents the transitive closure of all the entities that are, by
+necessity, [trusted] to faithfully run the build and record the provenance.
+
+The `id` MUST reflect the trust base that consumers care about. How detailed to
+be is a judgement call. For example, GitHub Actions supports both GitHub-hosted
+runners and self-hosted runners. The GitHub-hosted runner might be a single
+identity because it's all GitHub from the consumer's perspective. Meanwhile,
+each self-hosted runner might have its own identity because not all runners are
+trusted by all consumers.
+
+Consumers MUST accept only specific signer-builder pairs. For example, "GitHub"
+can sign provenance for the "GitHub Actions" builder, and "Google" can sign
+provenance for the "Google Cloud Build" builder, but "GitHub" cannot sign for
+the "Google Cloud Build" builder.
+
+Design rationale: The builder is distinct from the signer because one signer
+may generate attestations for more than one builder, as in the GitHub Actions
+example above. The field is required, even if it is implicit from the signer,
+to aid readability and debugging. It is an object to allow additional fields
+in the future, in case one URI is not sufficient.
+
+> ⚠ **RFC:** Should we just allow builders to set arbitrary properties, rather
+> than calling out `version` and `builderDependencies`? We don't expect
+> verifiers to use any of them, so maybe that's the simpler approach? Or have a
+> `properties` that is an arbitrary object? (#319)
+
+> ⚠ **RFC:** Do we want/need to identify the tenant of the build system,
+> separately from the build system itself? If so, should it be a single `id`
+> that combines both (e.g.
+> `https://builder.example/tenants/company1.example/project1`), or two separate
+> fields (e.g. `{"id": "https://builder.example", "tenant":
+> "https://company1.example/project1"}`)? What would the use case be for this?
+> How should [verification] work?
+
+### BuildMetadata
+
+[BuildMetadata]: #buildmetadata
+
+REQUIRED: (none)
+
+