> 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 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. ### 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 tests: - test_source: bugbugio-simple-test - test_source: bugbug-ifs ``` *** ### 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.