Perspectives for Content Lake

This release introduces new features and changes to support Content Releases. For more details on Content Releases, see the Studio release notes.

The following items may break behavior in your applications. See the details below for further explanations and migration paths.

• The default perspective has changed to only display published content.
• Raw perspective requests now include versions. prefixed documents in addition to drafts. and published documents.
• A bug in GROQ queries that caused empty keys to expand has been fixed. If you are relying on this behavior, see the details below.

versions.** documents are not returned in API versions prior to 2025-02-19. You must opt-in to this version to query versions-prefixed documents.

The default perspective has changed from raw to published. This includes:

• /query now uses perspective=published by default.
• GraphQL now uses perspective=published by default.

To return to the previous behavior, set perspective to raw.

In addition to the existing named perspective values, you can also pass one or more release IDs to the query endpoint's perspective parameter. For example: perspective=release-a,release-b,release-c. This will give you a view on your dataset as if release-c had been published, followed by release-b and finally release-a. This is generalisation of the existing previewDrafts functionality to support Content Releases.

Learn more in the Content Releases API documentation.

The following endpoints now include a boolean includeAllVersions parameter. Set it to true and use an authenticated request to include all versions.

• /listen
• /doc

Prior to 2025-02-19, queries on /query and similar APIs returned published documents and drafts.** documents when using the raw or previewDrafts perspectives. In 2025-02-19 and later, a versions.** path is introduced for Content Release document versions.

If you rely on path prefixes alone, you'll want to use perspectives instead to control which documents are returned by queries.

The Actions API now includes actions for managing Content Releases. Along with this, actions such as sanity.action.document.discard and sanity.action.document.replaceDraft have been deprecated in favor of sanity.action.document.version.discard and sanity.action.document.version.replace.

See the Actions API reference for more details.

• sanity::versionOf(documentID): Checks for versions of a provided document ID. Use inside a filter to return matching documents. For example: *[sanity::versionOf("abc123")].
• sanity::partOfRelease(releaseID): Checks whether a document is part of a given release. For example, fetch all the version documents in release rel-summer using *[sanity::partOfReleases("rel-summer").
• releases::all(): Returns all releases.

Learn more about these in the GROQ functions reference documentation.

The document history API now accepts a lastRevision parameter, which returns the current data for an existing document, or the last state before deletion for a deleted document.

This version also introduces a fix to a GROQ bug whereby empty keys in projections would expand into the object.

For example:

Input

{
  "": {
    "a": "b"
  }
}

response

{
  "a": "b"
}

This is corrected in 2025-02-19, and instead the query will return the following:

{
  "": {
    "a": "b"
  }
}

To replicate the older behavior in the new API version, update the empty string with the ellipsis operator (...). For example:

{
  ... {
    "a": "b"
  }
}

Say goodbye to late-night content deployments and "DO NOT PUBLISH" in titles. Content Releases introduces a better way to plan, preview, and coordinate content changes – working the way your code deployments do. Available for Growth plans and above. Read the launch post to learn how teams use it to transform their content workflows.

npm i sanity@latest @sanity/assist@latest @sanity/vision@latest

Content Releases is enabled by default in this version of Studio and beyond. You can disable it by adding the following to your studio configuration:

// sanity.config.ts|js
// ...
export default defineConfig({
  // ...
  releases: {
    enabled: false
  }
})

To ensure compatibility, we suggest upgrading all official Sanity plugins and tools, such as Presentation and AI Assist, to the latest versions.

This release pairs with the release of API version 2025-02-19. The two involve some breaking changes that affect highly customized studios, and potentially third party libraries. Here are areas to look out for when evaluating your codebase.

• API version 2025-02-19 includes changes to the perspective system. Starting with this version, the majority of APIs and official clients now use published as the default perspective.
• The raw perspective, previously the default, now returns published, draft, and version documents.
• If your codebase relies on checking paths for drafts.**, this could cause unexpected behaviors.
  • Content Releases and API version 2025-02-19 and above introduce the versions.** ID prefix. We suggest relying on perspectives instead of path matching whenever possible.
  • We've introduced a utility library, @sanity/id-utils, to help handle multiple ID formats.
  • You can opt in or out of receiving versions.** documents as needed by adjusting your API version, either in the client or within Structure Builder's DocumentList.
• If using client.listen, you'll need to forward includeAllVersions=true in order to listen for version and draft document changes.
• Plugin authors that wish to support Content Releases will need to use 2025-02-19 or later as the API version. See the plugin migration guide for additional details.
• Ensure any custom implementations of the client in Studio that make use of useClient set the correct apiVersion and perspective (2025-02-19 and raw respectively) as needed to support releases and version documents.
• Support for versions in webhooks is coming in the future, but not yet supported. Webhooks can query release state, but not the version documents themselves.

Many APIs that rely on perspective have been updated. See the API v2025-02-19 changelog for additional details and suggestions.

• Some success toast messages have been removed to streamline the Studio UI. These removals have been made where there is a reasonable expectation the operation will succeed immediately and reliably (for example, when copying a value to the clipboard). Error toast messages remain as they were before.
• Adds the v2025-02-19 API version to Vision's dropdown
• It's now possible to drag and drop inline objects in the Portable Text Input
• Improved document header for documents with many versions