Distribution Specs (v3) - Builder Distribution Spec

distribution.md

@@ -48,6 +48,8 @@ Each buildpack layer blob MUST contain a single [buildpack](./buildpack.md) at t
 /cnb/buildpacks/<buildpack ID>/<buildpack version>/
 ```
 
+If the buildpack ID contains a `/`, it must be replaced with `_` in the directory name.
+
 A buildpack MUST contain a `buildpack.toml` file at its root directory.
 
 #### Labels
@@ -228,3 +230,89 @@ The Run Image SHOULD contain the following Labels on the image configuration:
 Where,
 
 `<Target ID>` is an identifier specified on the runtime image that MAY be used to apply target-specific logic.
+
+### Builder
+
+The following specifies the artifact format for a buildpacks builder.
+
+A Builder is an OCI Image that provides a distributable build environment.
+
+A platform supporting builders SHOULD allow users to configure the build environment for a provided builder.
+
+#### General Requirements
+
+The Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and a [build-time](#build-image) environment, and MAY contain [buildpacks](#buildpackage). Platforms SHOULD use builders to ease the build process.
+
+#### Filesystem
+
+A builder MUST have the following directories/files:
+
+* `/cnb/order.toml` &rarr; As defined in the [platform specification](https://github.com/buildpacks/spec/blob/main/platform.md#ordertoml-toml)
+
+#### Environment Variables
+
+A Builder MUST be an extension of a Build Image, and MUST retain all the specified environment variables set on the original build image, as specified in the Build Image specifications.
+
+The following environment variables MAY be set on the builder (through the image config's `Env` field):
+
+| Env Variable             | Description                                                                       | Default
+| --------                 | --------                                                                          |-----------
+| `CNB_APP_DIR`            | Application directory of the build environment                                    | `/workspace`
+| `CNB_LAYERS_DIR`         | The directory to create and store `layers` in the build environment               | `/layers`
+| `CNB_PLATFORM_DIR`       | The directory to create and store platform focused files in the build environment | `/platform`
+| `SERVICE_BINDING_ROOT`   | The directory where services are bound                                            | -
+
+
+#### Labels
+
+A Builder MUST be an extension of a Build Image, and MUST retain all the specified Labels set on the original build image, as specified in the Build Image specifications.
+
+A Builder image MUST contain an implementation of the [lifecycle](#lifecycle), and MUST retain all the specified Labels set on the original Lifecycle image, as specified in the lifecycle distribution specifications.
+
+A Builder image MAY contain [buildpacks](#buildpackage), and MAY retain all the specified Labels set on the original buildpackage, as specified in the buildpackage specifications.
+
+The following labels MUST be set in the builder environment (through the image config's `Labels` field):
+
+| Label             | Description
+| --------          | --------
+| `io.buildpacks.builder.metadata`     | A JSON object representing Builder metadata
+| `io.buildpacks.buildpack.order`      | A JSON object representing the order of the buildpacks stored on the builder
+
+`io.buildpacks.builder.metadata` (JSON)
+
+```json
+{
+  "description": "<description>",
+  "buildpacks": [
+    {
+      "id": "<buildpack ID>",
+      "version": "<buildpack version>",
+      "homepage": "<buildpack homepage>",
+    }
+  ],
+  "createdBy": {
+    "name": "<tool name>",
+    "version": "<tool version>",
+  }
+}
+```
+
+The `createdBy` metadata is meant to contain the name and version of the tool that created the builder.
+
+`io.buildpacks.buildpack.order` (JSON)
+
+```json
+[
+  {
+    "group":
+      [
+        {
+          "id": "<buildpack ID>",
+          "version": "<buildpack version>",
+          "optional": false
+        }
+      ]
+  }
+]
+
+```