A project descriptor is a file that MAY contain configuration for apps, services, functions, and buildpacks. By default, the file SHOULD be named project.toml
and located in the root directory of a project's repository. A platform SHOULD read the file to enrich the build process.
This document specifies Project Descriptor Schema Version 0.2
.
The Schema Version format follows the form of the Buildpack API Version:
- MUST be in form . or , where is equivalent to .0
- When is greater than 0 increments to SHALL exclusively indicate additive changes
schema-version
- A string that follows the format of Buildpack API Version.uri
- A string that follows the format of RFC3986.
All other tables besides _
will use reverse domains, i.e. buildpacks.io will be [io.buildpacks]
. These tables can be optionally versioned with a schema version number using the schema-version
field. All these tables are optional.
The TOML schema of the project section of the project descriptor:
[_]
schema-version = "<schema-version>"
id = "<string>" # machine readable
name = "<string>" # human readable
version = "<string>"
authors = ["<string>"]
documentation-url = "<uri>"
source-url = "<uri>"
[[_.licenses]]
type = "<string>"
uri = "<uri>"
[_.metadata]
# additional arbitrary keys allowed
The top-level _
table MAY contain configuration about the repository, including id
and version
. It MAY also include metadata about how it is authored, documented, and version controlled. It MUST contain schema-version
to denote which schema version the descriptor is using.
[_]
schema-version = "<string>"
id = "<string>"
name = "<string>"
version = "<string>"
authors = ["<string>"]
documentation-url = "<uri>"
source-url = "<uri>"
schema-version
- version identifier for the schema of the_
table and structure of the project descriptor file.id
- (optional) the machine readable identifier of the project (ex. "com.example.myservice")name
- (optional) the human readable name of the project (ex. "My Example Service")version
- (optional) and arbitrary string representing the version of the projectauthors
- (optional) the names and/or email addresses of the project's authorsdocumentation-url
- (optional) a URL to the documentation for the project.source-url
- (optional) a URL to the source code for the project
This table MAY contain project licenses.
[[_.licenses]]
type = "<string>"
uri = "<uri>"
type
- This MAY use the SPDX 2.1 license expression, but is not limited to identifiers in the SPDX Licenses List.uri
- If this project is using a nonstandard license, then this key MAY be specified in lieu of or in addition totype
to point to the license.
This is a free form table for users to use as they see fit. The keys in this table are not validated.
[_.metadata.foo]
checksum = "a28a0d7772df1f918da2b1102da4ff35"
This is the Cloud Native Buildpacks' section of the project descriptor. The TOML schema is the following:
[io.buildpacks]
builder = "<string>"
include = ["<string>"]
exclude = ["<string>"]
[[io.buildpacks.group]]
id = "<string>"
version = "<string>"
uri = "<string>"
[[io.buildpacks.build.env]]
name = "<string>"
value = "<string>"
This is the builder image to use (ex. "cnbs/sample-builder:bionic").
An optional list of files to include in the build (while excluding everything else): This MAY contain a list of files to include in the build (while excluding everything else):
[io.buildpacks]
include = [
"cmd/",
"go.mod",
"go.sum",
"*.go"
]
A list of files to exclude from the build (while including everything else):
[io.buildpacks]
exclude = [
"spec/"
]
The .gitignore
pattern is used in both cases. The exclude
and include
keys are mutually exclusive, and if both are present the Lifecycle will error out.
Any files that are excluded (either via include
or exclude
) MUST BE excluded before the build (i.e. not only excluded from the final image).
If both exclude
and include
are defined, the build process MUST result in an error.
This table MAY contain an array of buildpacks. The schema for this table is:
[[io.buildpacks.group]]
id = "<buildpack ID (optional)>"
version = "<buildpack version (optional default=latest)>"
uri = "<url or path to the buildpack (optional default=urn:buildpack:<id>)"
This defines the buildpacks that a platform should use on the repo.
Either an id
or a uri
MUST be included, but MUST NOT include both. If uri
is provided, version
MUST NOT be allowed.
This table MAY be used to set environment variables at build time, for example:
[[io.buildpacks.env.build]]
name = "JAVA_OPTS"
value = "-Xmx1g"
[_]
id = "io.buildpacks.my-app"
version = "0.1"
[_.metadata]
cdn = "https://cdn.example.com"
[[_.metadata.assets]]
url = "https://cdn.example.com/assets/foo.jar"
checksum = "3b1b39893d8e34a6d0bd44095afcd5c4"
buzz = ["a", "b", "c"]
[io.buildpacks]
builder = "cnbs/sample-builder:bionic"
include = [
"cmd/",
"go.mod",
"go.sum",
"*.go"
]
[[io.buildpacks.group]]
id = "io.buildpacks/java"
version = "1.0"
[[io.buildpacks.gruop]]
id = "io.buildpacks/nodejs"
version = "1.0"