YAML schema

The BugBug YAML file format: the envelope, the published JSON Schema, and how to get validation and autocomplete in your editor.

Every YAML document BugBug exports has the same envelope. You can use the published JSON Schema in your editor or CI. ZIP exports also contain non-YAML files such as upload attachments and visual regression baselines, plus a top-level bugbug-export.json describing the archive itself (see Overview).

What a file looks like

BugBug writes a short header comment, then three top-level keys:

# yaml-language-server: $schema=https://api.bugbug.io/v2/schema/yaml/v1/
# BugBug YAML Format
# Schema Version: 1.0
# Documentation: https://docs.bugbug.io/yaml-schema
schema_version: '1.0'
schema_type: component
data:
  component_name: GOTO BugBug.io
  slug: goto-bugbugio
  steps:
  - action: goto
    action_details:
      url: https://bugbug.io/

Key	Meaning
schema_version	Which version of the format this file follows.
schema_type	What kind of thing the file describes.
data	The thing itself. Its shape depends on schema_type.

The header comment is informational. The importer uses the three top-level keys.

The document types

schema_type	Describes
test	A test: its steps, groups, screen size, and settings.
component	A reusable group of steps.
suite	A set of tests to run together, and how to run them.
profile	A named set of variables, typically one per environment.
project	Project-level settings: selectors, waiting conditions, screen sizes, timeouts.
folder	A folder description, carried in a .folder.yaml marker inside a ZIP.

A test document references components by slug, and a suite document references tests by slug:

schema_version: '1.0'
schema_type: suite
data:
  suite_name: Selected Staging Parallel
  suite_settings:
    run_in_parallel: true
    auto_retry: 0
    auto_add_new_tests: false
    before_after_all_enabled: false
  before_all_tests: []
  tests:
  - test_source: bugbugio-simple-test
  - test_source: bugbug-ifs
  after_all_tests: []

before_all_tests and after_all_tests are optional, shaped like tests (a list of test_source references). They only run when before_after_all_enabled is true. See Before all / After all tests.

---

The JSON Schema

The schema is available without authentication at:

https://api.bugbug.io/v2/schema/yaml/v1/

It is a draft-07 document covering every document type. The schema_type field selects the relevant variant for validation and editor autocomplete.

---

Validation and autocomplete in your editor

Every exported YAML file points at the schema on its first line:

# yaml-language-server: $schema=https://api.bugbug.io/v2/schema/yaml/v1/

Most IDEs detect this line automatically. Exported files then provide autocomplete for step actions and flag invalid values as you type. Add the same line to a file you write yourself.

---

Validating in CI

The schema works with standard JSON Schema validators. For example, you can use check-jsonschema before importing files:

check-jsonschema \
  --schemafile https://api.bugbug.io/v2/schema/yaml/v1/ \
  tests/**/*.yaml

This moves schema errors into your CI pipeline instead of finding them during import.

---

Writing BugBug YAML yourself

You can generate BugBug YAML yourself. Schema validation is necessary, but the import route also checks the document type and format. A test document can be imported as standalone YAML or as a test ZIP. Component documents are imported when they are included in a test or project ZIP. Suites, profiles, project settings, and folder markers are imported as part of a project ZIP.

When you write a file, remember:

• Slugs identify items. They determine whether an import creates a new item or updates an existing one. The overview explains how matching works.

• A component_source or test_source has to resolve, either against something already in the target project or against something arriving in the same ZIP.

• Inside a project ZIP, BugBug names entity files <slug>.bugbug.yaml. A downloaded single-test YAML file is named test_<slug>.bugbug.yaml. The .bugbug.yaml suffix helps tools recognise BugBug files, but import accepts either filename extension.

---

Versioning

The current version is 1.0, and it is the only version accepted today. Files declare the version in schema_version.

Schema v1 may change. Re-export files after a BugBug update and fetch the schema again instead of relying on an older export or a pinned copy.