Global Schema¶
The global schema is validated with for all buildspecs is the top-level schema when defining a buildspec file.
Please refer to Global Schema Documentation that provides a summary .
Schema Definition¶
Shown below is the start of the schema definition for global.schema.json
"$id": "global.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "global schema",
"description": "buildtest global schema is validated for all buildspecs. The global schema defines top-level structure of buildspec and defintions that are inherited for sub-schemas",
"type": "object",
"required": ["version","buildspecs"],
This schema requires that every buildspec should have version
and buildspecs
fields. The
version key is required to lookup an a sub-schema using the type
field.
The buildspecs
is the start of test declaration.
Shown below is an example buildspec.
version: "1.0"
buildspecs:
hello_world:
executor: generic.local.bash
type: script
tags: tutorials
description: "hello world example"
run: echo "hello world!"
maintainers:
- "@shahzebsiddiqui"
The maintainers
is an optional field that is an array test maintainers. To understand
how buildtest validates the buildspec see parsing buildspecs.
In this example, the global schema validates the following section:
version: "1.0"
buildspecs:
hello_world:
maintainers:
- "@shahzebsiddiqui"
The field version
buildspecs
and maintainers
are validated with global.schema.json
using jsonschema.validate
method. The test section within hello_world
is validated by sub-schema by looking up schema based
on type
field:
hello_world:
executor: generic.local.bash
type: script
description: "hello world example"
run: echo "hello world!"
Every sub-schema requires type field in this case, type: script
directs
buildtest to validate with the script schema. All type schemas have a version,
currently buildtest supports 1.0 version for all type schemas. The
version: "1.0"
is used to select the version of the sub-schema,
in this example we validate with the schema script-v1.0.schema.json.
Test Names¶
The buildspecs property is a JSON object that defines one or more test. This is defined in JSON as follows:
"buildspecs": {
"type": "object",
"description": "This section is used to define one or more tests (buildspecs). Each test must be unique name",
"propertyNames": {
"pattern": "^[A-Za-z_.][A-Za-z0-9_.]*$",
"maxLength": 32
}
}
The test names take the following pattern "^[A-Za-z_.][A-Za-z0-9_.]*$"
and limited
to 32 characters. In previous example, the test name is hello_world. You must have unique
testname in your buildspecs section, otherwise you will have an invalid buildspec
file. The description
field is used to document the test and limited to 80 characters.
Note
We refer to the entire YAML content as buildspec file, this is not to be confused with the buildspecs field.
Buildspec Structure¶
Shown below is an overview of buildspec file. In this diagram we define one test within
buildspecs
property named systemd_default_target
. This test is using the
script schema defined by type: script
. The executor
property is a required
property that determines how test is run. The executors are defined in buildtest configuration
see Configuring buildtest for more details.
The run
property is used for defining content of script, this can a shell-script
(bash,csh) or python script.
Please proceed to Buildspec Overview to learn more about buildspecs.