> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/export-import-and-backup/yaml-schema.md). # 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](/export-import-and-backup/import-export.md#project-zip-contents)). ### What a file looks like BugBug writes a short header comment, then three top-level keys: ```yaml # 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: ```yaml 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](/organizing-tests/suites.md#before-all-after-all-tests). *** Project YAML can include `data.settings.initial_run_profile`, referencing a profile by its slug. Omitting it uses the base profile. *** ### Tags A project document lists every tag defined in the project, with its color, under `data.tags`: ```yaml schema_version: '1.0' schema_type: project data: tags: - name: flaky color: '#D1242F' - name: 'Version:1.23' color: '#2684FF' ``` A `test` or `suite` document only lists the names of its own tags: ```yaml schema_version: '1.0' schema_type: test data: tags: - flaky - 'Version:1.23' ``` Importing a project ZIP creates tag definitions from `project.bugbug.yaml` before it applies any test or suite assignments, so an assignment always resolves. A standalone test or suite YAML works too: a tag name that doesn't already exist in the target project is created with a default color, which you can change afterward in Project Settings. See [Tags](/organizing-tests/tags.md). Files exported before tags existed don't have a `tags` key, and still import normally. *** ### The JSON Schema The schema is available without authentication at: ``` https://api.bugbug.io/v2/schema/yaml/v1/ ``` It is a [draft-07](https://json-schema.org/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 # 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`](https://github.com/python-jsonschema/check-jsonschema) before importing files: ```bash 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](/export-import-and-backup/import-export.md) 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 `.bugbug.yaml`. A downloaded single-test YAML file is named `test_.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`. {% hint style="warning" %} **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. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.bugbug.io/export-import-and-backup/yaml-schema.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.