> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/reference/schemas/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# Schemas

> A documentation content testing framework that simplifies the process of keeping your docs accurate and up-to-date.

## Docs

- [annotate](https://docs.doc-detective.com/reference/schemas/annotate.md): Reference for the `annotate` schema.
- [Annotate fields](https://docs.doc-detective.com/reference/schemas/annotate-fields.md): Reference for the `Annotate fields` schema.
- [annotation](https://docs.doc-detective.com/reference/schemas/annotation.md): A visual annotation drawn onto a screenshot or recording. Each annotation names exactly one type (`outline`, `arrow`, `badge`, `callout`, `blur`, or `text`), and the type's value is the target it points at: an element (a selector/display-text string or a detailed find object) or a fixed `position` in the capture. `id`, `track`, `transition`, and `duration` describe behavior over time — they apply to recordings and are inert in still screenshots, so the same annotation means the same thing in both.
- [Annotation defaults](https://docs.doc-detective.com/reference/schemas/annotation-defaults.md): Default visual theme for screenshot and recording annotations. Specs and tests can override this value with their own `annotationDefaults` fields (test level wins over spec level, which wins over config level), and an individual annotation's `style` wins over all of them. Fields left unset fall back to Doc Detective's built-in theme. Setting a theme here keeps every annotated image in a doc set visually consistent.
- [Annotation fields](https://docs.doc-detective.com/reference/schemas/annotation-fields.md): Reference for the `Annotation fields` schema.
- [Annotation offset](https://docs.doc-detective.com/reference/schemas/annotation-offset.md): A nudge in pixels from the annotation's default placement.
- [Annotation point](https://docs.doc-detective.com/reference/schemas/annotation-point.md): An absolute coordinate in the capture, in pixels from the top-left.
- [Annotation style](https://docs.doc-detective.com/reference/schemas/annotation-style.md): Visual overrides for this annotation. Anything unset falls back to the resolved `annotationDefaults` theme (test, then spec, then config), then to the built-in theme.
- [Annotation transition](https://docs.doc-detective.com/reference/schemas/annotation-transition.md): How the annotation enters and leaves. Applies to recordings; inert in still screenshots, which render the settled state.
- [App descriptor](https://docs.doc-detective.com/reference/schemas/app-descriptor.md): Reference for the `App descriptor` schema.
- [App readiness](https://docs.doc-detective.com/reference/schemas/app-readiness.md): Reference for the `App readiness` schema.
- [App surface](https://docs.doc-detective.com/reference/schemas/app-surface.md): Reference for the `App surface` schema.
- [assertion](https://docs.doc-detective.com/reference/schemas/assertion.md): An articulated assertion record produced by the runner for a step result. Each record names a single verification check, whether it passed, and the values it compared. The step's result is the roll-up of its assertion results (FAIL > WARNING > all-SKIPPED > PASS). System-populated; appears in test results, not in authored specs.
- [Browser](https://docs.doc-detective.com/reference/schemas/browser.md): Browser configuration.
- [Browser descriptor](https://docs.doc-detective.com/reference/schemas/browser-descriptor.md): Reference for the `Browser descriptor` schema.
- [Browser readiness](https://docs.doc-detective.com/reference/schemas/browser-readiness.md): Reference for the `Browser readiness` schema.
- [Browser surface](https://docs.doc-detective.com/reference/schemas/browser-surface.md): Reference for the `Browser surface` schema.
- [Browser Viewport](https://docs.doc-detective.com/reference/schemas/browser-viewport.md): Viewport dimensions.
- [Browser viewport size](https://docs.doc-detective.com/reference/schemas/browser-viewport-size.md): Viewport (page-content) dimensions for this session; the window is resized so the content area matches. Takes precedence over `size` when both are set.
- [Browser Window](https://docs.doc-detective.com/reference/schemas/browser-window.md): Browser dimensions.
- [Browser window size](https://docs.doc-detective.com/reference/schemas/browser-window-size.md): Outer window dimensions for this session. Default: the context's browser window size.
- [By criteria](https://docs.doc-detective.com/reference/schemas/by-criteria.md): Reference for the `By criteria` schema.
- [Capture screenshot (detailed)](https://docs.doc-detective.com/reference/schemas/capture-screenshot-detailed.md): Reference for the `Capture screenshot (detailed)` schema.
- [Capture screenshot fields](https://docs.doc-detective.com/reference/schemas/capture-screenshot-fields.md): Reference for the `Capture screenshot fields` schema.
- [Check link (detailed)](https://docs.doc-detective.com/reference/schemas/check-link-detailed.md): Check if an HTTP or HTTPS URL returns an acceptable status code from a GET request.
- [checkLink](https://docs.doc-detective.com/reference/schemas/checklink.md): Reference for the `checkLink` schema.
- [click](https://docs.doc-detective.com/reference/schemas/click.md): Reference for the `click` schema.
- [Click element (detailed)](https://docs.doc-detective.com/reference/schemas/click-element-detailed.md): Reference for the `Click element (detailed)` schema.
- [closeSurface](https://docs.doc-detective.com/reference/schemas/closesurface.md): Reference for the `closeSurface` schema.
- [Common](https://docs.doc-detective.com/reference/schemas/common.md): Reference for the `Common` schema.
- [config](https://docs.doc-detective.com/reference/schemas/config.md): Configuration options for Doc Detective operations.
- [context](https://docs.doc-detective.com/reference/schemas/context.md): A context in which to perform tests. If no contexts are specified but a context is required by one or more tests, Doc Detective attempts to identify a supported context in the current environment and run tests against it. For example, if a browser isn't specified but is required by steps in the test, Doc Detective will search for and use a supported browser available in the current environment.
- [Crop by element (detailed)](https://docs.doc-detective.com/reference/schemas/crop-by-element-detailed.md): Crop the screenshot to a specific element.
- [Device descriptor](https://docs.doc-detective.com/reference/schemas/device-descriptor.md): Reference for the `Device descriptor` schema.
- [Doc Detective Orchestration API](https://docs.doc-detective.com/reference/schemas/doc-detective-orchestration-api.md): Configuration for Doc Detective Orchestration API integration.
- [dragAndDrop](https://docs.doc-detective.com/reference/schemas/draganddrop.md): Reference for the `dragAndDrop` schema.
- [Element criteria](https://docs.doc-detective.com/reference/schemas/element-criteria.md): Wait for a specific element to be present. At least one finding field must be specified.
- [Element (detailed)](https://docs.doc-detective.com/reference/schemas/element-detailed.md): Reference for the `Element (detailed)` schema.
- [Element-finding fields](https://docs.doc-detective.com/reference/schemas/element-finding-fields.md): Reference for the `Element-finding fields` schema.
- [Environment details](https://docs.doc-detective.com/reference/schemas/environment-details.md): Environment information for the system running Doc Detective.
- [File type (custom)](https://docs.doc-detective.com/reference/schemas/file-type-custom.md): Reference for the `File type (custom)` schema.
- [File type (executable)](https://docs.doc-detective.com/reference/schemas/file-type-executable.md): Reference for the `File type (executable)` schema.
- [find](https://docs.doc-detective.com/reference/schemas/find.md): Reference for the `find` schema.
- [Find element and click](https://docs.doc-detective.com/reference/schemas/find-element-and-click.md): Reference for the `Find element and click` schema.
- [Find element (detailed)](https://docs.doc-detective.com/reference/schemas/find-element-detailed.md): Reference for the `Find element (detailed)` schema.
- [Go to URL (detailed)](https://docs.doc-detective.com/reference/schemas/go-to-url-detailed.md): Navigate to an HTTP or HTTPS URL.
- [goTo](https://docs.doc-detective.com/reference/schemas/goto.md): Reference for the `goTo` schema.
- [Heretto CMS integration](https://docs.doc-detective.com/reference/schemas/heretto-cms-integration.md): Reference for the `Heretto CMS integration` schema.
- [Hints options](https://docs.doc-detective.com/reference/schemas/hints-options.md): Options for the post-run hints feature. After a test run, Doc Detective may print one short, contextual hint with code samples and links to encourage further engagement (for example, suggesting a CI workflow when none is detected). Doc Detective displays hints only in an interactive terminal (TTY) and only at the default `info` log level.
- [HTTP request (detailed)](https://docs.doc-detective.com/reference/schemas/http-request-detailed.md): Reference for the `HTTP request (detailed)` schema.
- [httpRequest](https://docs.doc-detective.com/reference/schemas/httprequest.md): Reference for the `httpRequest` schema.
- [Identified annotation](https://docs.doc-detective.com/reference/schemas/identified-annotation.md): An annotation that names the `id` of the annotation to replace.
- [Inline statement definition](https://docs.doc-detective.com/reference/schemas/inline-statement-definition.md): Statements to include tests and steps inside the content of the file, such as within Markdown.
- [Integrations options](https://docs.doc-detective.com/reference/schemas/integrations-options.md): Options for connecting to external services.
- [Load cookie (detailed)](https://docs.doc-detective.com/reference/schemas/load-cookie-detailed.md): Reference for the `Load cookie (detailed)` schema.
- [loadCookie](https://docs.doc-detective.com/reference/schemas/loadcookie.md): Reference for the `loadCookie` schema.
- [loadVariables](https://docs.doc-detective.com/reference/schemas/loadvariables.md): Reference for the `loadVariables` schema.
- [Markup definition](https://docs.doc-detective.com/reference/schemas/markup-definition.md): Reference for the `Markup definition` schema.
- [openApi](https://docs.doc-detective.com/reference/schemas/openapi.md): OpenAPI description and configuration.
- [Padding (detailed)](https://docs.doc-detective.com/reference/schemas/padding-detailed.md): Padding in pixels to add to the bounds of the element.
- [Point](https://docs.doc-detective.com/reference/schemas/point.md): A pixel coordinate on the surface, measured from its top-left corner (0, 0).
- [Process descriptor](https://docs.doc-detective.com/reference/schemas/process-descriptor.md): Reference for the `Process descriptor` schema.
- [Process readiness](https://docs.doc-detective.com/reference/schemas/process-readiness.md): Reference for the `Process readiness` schema.
- [Process surface](https://docs.doc-detective.com/reference/schemas/process-surface.md): Reference for the `Process surface` schema.
- [record](https://docs.doc-detective.com/reference/schemas/record.md): Reference for the `record` schema.
- [Record (detailed)](https://docs.doc-detective.com/reference/schemas/record-detailed.md): Reference for the `Record (detailed)` schema.
- [Recording checkpoints (detailed)](https://docs.doc-detective.com/reference/schemas/recording-checkpoints-detailed.md): Reference for the `Recording checkpoints (detailed)` schema.
- [Recording engine (detailed)](https://docs.doc-detective.com/reference/schemas/recording-engine-detailed.md): Reference for the `Recording engine (detailed)` schema.
- [Recording verify guards](https://docs.doc-detective.com/reference/schemas/recording-verify-guards.md): Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.
- [Request](https://docs.doc-detective.com/reference/schemas/request.md): Reference for the `Request` schema.
- [Request body (object)](https://docs.doc-detective.com/reference/schemas/request-body-object.md): JSON object to include as the body of the HTTP request.
- [Request headers (object)](https://docs.doc-detective.com/reference/schemas/request-headers-object.md): Headers to include in the HTTP request, in key/value format. Values must be strings.
- [Request parameters](https://docs.doc-detective.com/reference/schemas/request-parameters.md): URL parameters to include in the HTTP request, in key/value format.
- [Requirements](https://docs.doc-detective.com/reference/schemas/requirements.md): Reference for the `Requirements` schema.
- [Resolved context](https://docs.doc-detective.com/reference/schemas/resolved-context.md): Reference for the `Resolved context` schema.
- [Response](https://docs.doc-detective.com/reference/schemas/response.md): Reference for the `Response` schema.
- [Response body object](https://docs.doc-detective.com/reference/schemas/response-body-object.md): JSON key/value pairs expected in the response.
- [Response headers](https://docs.doc-detective.com/reference/schemas/response-headers.md): Headers expected in the response, in key/value format. If one or more `responseHeaders` entries aren't present in the response, the step fails.
- [Retry](https://docs.doc-detective.com/reference/schemas/retry.md): Retry the current step.
- [routing](https://docs.doc-detective.com/reference/schemas/routing.md): A single dynamic-routing entry: an optional condition (`if`) plus exactly one routing action. Attached to a step or test handler (`onPass`, `onFail`, `onWarning`, `onSkip`). For step-level handlers, `continue`, `stop`, `retry`, and `goToStep` are evaluated at runtime; `goToTest` is validated but not yet executed (deferred at step scope). For test-level handlers, `continue`, `stop`, and `goToTest` are evaluated at runtime (test scope; `goToTest` jumps to a test within the spec), while `retry` and `goToStep` are not applicable at test scope.
- [Run browser script (detailed)](https://docs.doc-detective.com/reference/schemas/run-browser-script-detailed.md): Reference for the `Run browser script (detailed)` schema.
- [Run code (detailed)](https://docs.doc-detective.com/reference/schemas/run-code-detailed.md): Reference for the `Run code (detailed)` schema.
- [Run shell command (detailed)](https://docs.doc-detective.com/reference/schemas/run-shell-command-detailed.md): Reference for the `Run shell command (detailed)` schema.
- [runBrowserScript](https://docs.doc-detective.com/reference/schemas/runbrowserscript.md): Reference for the `runBrowserScript` schema.
- [runCode](https://docs.doc-detective.com/reference/schemas/runcode.md): Reference for the `runCode` schema.
- [runShell](https://docs.doc-detective.com/reference/schemas/runshell.md): Reference for the `runShell` schema.
- [Save cookie (detailed)](https://docs.doc-detective.com/reference/schemas/save-cookie-detailed.md): Reference for the `Save cookie (detailed)` schema.
- [saveCookie](https://docs.doc-detective.com/reference/schemas/savecookie.md): Reference for the `saveCookie` schema.
- [screenshot](https://docs.doc-detective.com/reference/schemas/screenshot.md): Reference for the `screenshot` schema.
- [Source Location](https://docs.doc-detective.com/reference/schemas/source-location.md): Source location where this step was detected in the original file. This is system-populated metadata and should not be set manually.
- [sourceIntegration](https://docs.doc-detective.com/reference/schemas/sourceintegration.md): Information about the source integration for this screenshot, enabling upload of changed files back to the source CMS. Set automatically during test resolution for files from integrations.
- [specification](https://docs.doc-detective.com/reference/schemas/specification.md): Reference for the `specification` schema.
- [startSurface](https://docs.doc-detective.com/reference/schemas/startsurface.md): Reference for the `startSurface` schema.
- [stopRecord](https://docs.doc-detective.com/reference/schemas/stoprecord.md): Reference for the `stopRecord` schema.
- [stopRecord (detailed)](https://docs.doc-detective.com/reference/schemas/stoprecord-detailed.md): Reference for the `stopRecord (detailed)` schema.
- [swipe](https://docs.doc-detective.com/reference/schemas/swipe.md): Reference for the `swipe` schema.
- [Swipe (directional)](https://docs.doc-detective.com/reference/schemas/swipe-directional.md): Reference for the `Swipe (directional)` schema.
- [Swipe (point-to-point)](https://docs.doc-detective.com/reference/schemas/swipe-point-to-point.md): Reference for the `Swipe (point-to-point)` schema.
- [Target by element (detailed)](https://docs.doc-detective.com/reference/schemas/target-by-element-detailed.md): Element to annotate. Mirrors the element-finding fields used elsewhere. On app surfaces only the natively-mappable fields are supported (`elementText`, `elementId`, `elementTestId`, `elementAria`); `selector`, `elementClass`, and `elementAttribute` have no native equivalent.
- [Target by position](https://docs.doc-detective.com/reference/schemas/target-by-position.md): A fixed spot in the capture, for annotations that aren't anchored to an element.
- [Telemetry options](https://docs.doc-detective.com/reference/schemas/telemetry-options.md): Options around sending telemetry for Doc Detective usage.
- [test](https://docs.doc-detective.com/reference/schemas/test.md): A Doc Detective test.
- [type](https://docs.doc-detective.com/reference/schemas/type.md): Reference for the `type` schema.
- [Type keys (detailed)](https://docs.doc-detective.com/reference/schemas/type-keys-detailed.md): Reference for the `Type keys (detailed)` schema.
- [Verify resolution (detailed)](https://docs.doc-detective.com/reference/schemas/verify-resolution-detailed.md): Reference for the `Verify resolution (detailed)` schema.
- [wait](https://docs.doc-detective.com/reference/schemas/wait.md): Reference for the `wait` schema.