Global Schema

The global schema file (global.schema.json) is validated with for all buildspecs and this schema defines the top-level structure of the buildspec file. In particular this will validate the buildspecs keyword which is a JSON object that defines one or more tests (buildspecs). Each test must be unique name.

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": ["buildspecs"],
  "additionalProperties": false,

This schema requires that every buildspec should have buildspecs which is the start of test declaration and each test will contain a type field to look for appropriate sub-schema.

Example Buildspec

buildspecs:
  hello_world:
    executor: generic.local.bash
    type: script
    tags: tutorials
    description: "hello world example"
    run: echo "hello world!"
maintainers:
- "@shahzebsiddiqui"

The field 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.

Every sub-schema requires type field in this case, type: script informs buildtest to validate with the Script Schema which will use schema script.schema.json

To learn more about how buildtest validates the buildspec, please see parsing buildspecs.

Defining Maintainers

The maintainers is an optional field that can be used to specify a list of test maintainers for a given buildspec. The maintainers property is used by buildtest to report buildspecs by maintainers when querying buildspec cache. You can also filter buildspecs by maintainers during building via buildtest build --filter maintainers=<NAME> if one wants to filter tests

In this example, we have two maintainers @johndoe and @bobsmith. The maintainers is a list of strings but must be unique names, generally this can be your name or preferably a github or gitlab handle.

buildspecs:
  foo_bar:
    type: script
    executor: generic.local.sh
    tags: tutorials
    description: "prints variable $FOO"
    vars:
      FOO: BAR
    run: echo $FOO

maintainers:
  - "@johndoe"
  - "@bobsmith"

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": 48
  }
}

The test names are limited to 48 characters and follow the regular expression defined in pattern property. 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.

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 How to configure buildtest for more details. The description field is used to document the test and limited to 80 characters.

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.