build: Clarify buildType (#875)

Clarifies the meaning of buildType, as it was unclear. The actual intent
was to "namespace" the meaning of a Build element so that the rest of
the properties can be interpreted. This matches the SLSA definition of
buildType.

model/Build/Properties/buildId.md

@@ -10,7 +10,7 @@ instance of a build produced by it.
 ## Description
 
 A buildId is a locally unique identifier to identify a unique instance of a
-build.
+build, according to the buildType.
 
 This identifier differs based on build toolchain, platform, or naming
 convention used by an organization or standard.

model/Build/Properties/buildType.md

@@ -9,13 +9,30 @@ infrastructure that the build was invoked on.
 
 ## Description
 
-A buildType is a URI expressing the toolchain, platform, or infrastructure that
+A buildType is a IRI expressing the toolchain, platform, or infrastructure that
 the build was invoked on.
 
-For example, if the build was invoked on GitHub's CI platform using GitHub
-Actions, the buildType can be expressed as `https://github.com/actions`.
-In contrast, if the build was invoked on a local machine, the buildType can be
-expressed as `file://username@host/path/to/build`.
+The buildType is used to interpret the meaning of other build parameters by
+defining the "type" of build; if the same buildType is seen in different Build
+elements, it means they are the same kind of build, but difference instances
+and possible with different configurations.
+
+If you are not using a well-known buildType, it should be namespaced to a
+domain you own to prevent conflicts with other builtType IRIs.
+
+Examples of a buildType might be:
+* A GitHub action workflow
+* A step in a GitHub actions pipeline
+* An invocation of a compiler or other tool
+* A script that orchestrates builds at a higher level
+
+Keep in mind that builds can be "nested" using the `ancestorOf` relationship
+
+If the buildType IRI is not recognized, it is still possible to inspect other
+properties of the build, but it may not be possible to derive deeper meaning
+from them
+
+For more information, see the SLSA definition of buildType
 
 ## Metadata
 

model/Build/Properties/configSourceDigest.md

@@ -10,7 +10,7 @@ invoke a build.
 ## Description
 
 configSourceDigest is the checksum of the build configuration file used by a
-builder to execute a build.
+builder to execute a build, according to the buildType.
 
 This Property uses the Core model's [Hash](../../Core/Classes/Hash.md) class.
 

model/Build/Properties/configSourceEntrypoint.md

@@ -9,7 +9,7 @@ Property describes the invocation entrypoint of a build.
 ## Description
 
 A build entrypoint is the invoked executable of a build which always runs when
-the build is triggered.
+the build is triggered, according to the buildType.
 
 For example, when a build is triggered by running a shell script, the
 entrypoint is `script.sh`.

model/Build/Properties/configSourceUri.md

@@ -9,7 +9,8 @@ Property that describes the URI of the build configuration source file.
 ## Description
 
 If a build configuration exists for the toolchain or platform performing the
-build, the configSourceUri of a build is the URI of that build configuration.
+build, the configSourceUri of a build is the URI of that build configuration,
+according to the buildType.
 
 For example, a build triggered by a GitHub Action is defined by a build
 configuration YAML file. In this case, the configSourceUri is the URL of that

model/Build/Properties/environment.md

@@ -9,7 +9,7 @@ Property describing the session in which a build is invoked.
 ## Description
 
 environment is a map of environment variables and values that are set during a
-build session.
+build session, according to the buildType.
 
 This is different from the [parameter](parameter.md) property in that it
 describes the environment variables set before a build is invoked rather than

model/Build/Properties/parameter.md

@@ -9,7 +9,7 @@ Property describing a parameter used in an instance of a build.
 ## Description
 
 parameter is a key-value of a build parameter and its value that
-was provided to the builder for a build instance.
+was provided to the builder for a build instance, according to the buildType.
 
 This is different from the [environment](environment.md) property in that
 the key and value are provided as command line arguments or