Skip to content

docs: Update $schema recommendation to use versioned subdomain #11519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
anthonyshew merged 2 commits into from
Jan 20, 2026
Merged

docs: Update $schema recommendation to use versioned subdomain #11519

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e73ee90
docs: Update $schema recommendation to use versioned subdomain
anthonyshew Jan 19, 2026
7852102
WIP 1e768
anthonyshew Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 10 additions & 11 deletions docs/site/content/docs/getting-started/editor-integration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,26 +8,25 @@ To get the best experience with `turbo`, Turborepo provides a few utilities for
## JSON Schema for `turbo.json`

Turborepo uses [JSON Schema](https://json-schema.org/) to give you auto-complete in your
`turbo.json` file. By including the `$schema` key in your `turbo.json`, your editor is able to
provide full documentation and linting in case you have invalid shapes or missing keys.
`turbo.json` files. By including the `$schema` key in your `turbo.json`, your editor is able to
provide full documentation and linting for invalid configuration.

### Sourcing from the web
### Sourcing from web

A `schema.json` is accessible at the URL shown below. This has the advantage of not needing to run your package manager's install command to see in-editor validation.
Starting with Turborepo 2.5.7, versioned schemas are available via subdomain, following the format `https://v<version>.turborepo.dev/schema.json`. The version uses a dash separator.

```json title="./turbo.json"
{
"$schema": "https://turborepo.dev/schema.json"
"$schema": "https://v2-5-7.turborepo.dev/schema.json"
}
```

There is also a major versioned `schema.json` available, following the format of `https://turborepo.dev/schema.<version>.json`.
This has the advantage of not needing to run your package manager's install command to see in-editor validation, while also ensuring you're using the schema that matches your installed version of `turbo`.

```json title="./turbo.json"
{
"$schema": "https://turborepo.dev/schema.v1.json"
}
```
<Callout type="info" title="Unversioned schema">
If you're using a version of Turborepo older than 2.5.7 or prefer an
Comment on lines +20 to +27
Copy link
Contributor

@vercel vercel bot Jan 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documentation states versioned subdomain schemas are available from v2.5.7+ but the feature was actually introduced in v2.7.5+

Fix on Vercel

unversioned schema, you can use `https://turborepo.dev/schema.json` instead.
</Callout>

### Sourcing from `node_modules`

Expand Down