Global document reference
Reference documentation for the `globalDocumentReference` schema type.
Global document references (GDR) expand the concept of the reference type to support referencing documents in other resources. See the GlobalDocumentReferenceDefinition reference for the full type definition.
Global document references are limited to Media Library
Global document references are currently supported only by Media Library's aspects feature.
Mutations and actions on a document that contains a global document reference require an API version of 2025-02-19 or later. Earlier versions reject the write with transaction failed: global document references are not supported: <resourceType>:<resourceId>.
Like standard references, global document references can be either strong (default) or weak. A strong reference ensures that the document it points to exists, and prevents deletion of any document that another document refers to. A weak reference can point to documents that don't exist yet or that have been deleted.
Global document reference properties
Requiredtype
string
Value must be set to
globalDocumentReference.Requiredname
string
The field name. This is the key in the data record.
RequiredresourceType
string
Either
datasetormedia-library. Media Library aspects currently reference thedatasetresource type.RequiredresourceId
string
The ID of the target resource. A
resourceIdis made up of theprojectIdand the dataset name, connected by a.. AresourceIdhas the formatprojectId.datasetName. For example:w3dbef.productionwm2efj.staging
Requiredto
array
An array of objects naming the document types that can be referenced. Each object accepts:
type(required): The name of the document type in the target resource.preview(required): Preview configuration for the referenced type, for example{select: {title: 'name'}}. The referencing studio has no schema for the target resource, so it needs this to render search results and previews.title(optional): A label shown for this type.icon(optional): A React component shown for this type.
For example:
[{type: 'person', preview: {select: {title: 'name'}}}]. For a complete example, see "Global document reference example".studioUrl
string | function
Builds a link from the reference preview to the referenced document in its own studio. Pass a string with the base URL of that studio, or a function that receives
{id, type}for the referenced document and returns the URL of its editing pane. The function can returnnullto show no link.weak
boolean
If set to
true, the reference is weak. A weak reference can point to documents that may or may not exist, such as a document that hasn't been published yet or one that has been deleted. Defaults tofalse.title
string
Human-readable label for the field.
description
string
A short text shown to editors that explains how to use the field.
boolean | function
Set to
trueto hide this field in the studio. Pass a callback function to make it conditional. Defaults tofalse.readOnly
boolean | function
Set to
trueto make this field read-only in the studio. Pass a callback function to make it conditional. Defaults tofalse.initialValue
any
The initial value used when you create new values from this type. Pass a literal value, or a resolver function that returns the value or a promise that resolves to it.
deprecated
object
Marks the field as deprecated. Requires a single
reasonproperty with a message shown to editors. With GraphQL, this becomes a@deprecateddirective. For example:{reason: 'no longer used'}.options
object
Further configure the schema type. See "Global document reference options".
Global document reference options
filter
string
A GROQ filter string (the contents between the square brackets), such as
language == "en-US".filterParams
object
Object of parameters for the GROQ-filter specified in
filter.
Global document reference example
This example defines a global document reference as a Media Library aspect. The document example shows a simplified sanity.asset document from Media Library that contains this aspect:
import { defineAssetAspect } from 'sanity'
export default defineAssetAspect({
name: 'photographer',
title: 'Photographer',
type: 'globalDocumentReference',
description: 'Select the photographer.',
resourceType: 'dataset',
resourceId: 'YOUR_PROJECT_ID.DATASET_NAME',
weak: true,
to: [
{
type: 'photographer',
preview: {
select: {
title: 'name'
}
}
}
]
}){
_createdAt: '2025-10-27T21:21:41Z',
_id: '34fMJaofTI5ptNBZFOYoBNfy6NM',
_rev: 'eefe4de2-7ec8-4307-aecc-1b0e890fa4e6',
_system: { createdBy: 'gvRshKueQ' },
_type: 'sanity.asset',
_updatedAt: '2025-11-05T19:19:24Z',
aspects: {
photographer: {
_ref: 'dataset:YOUR_PROJECT_ID.DATASET_NAME:200e44f2-14a9-4c7a-a621-a4ca4d9b559c',
_type: 'globalDocumentReference',
_weak: true
}
},
assetType: 'sanity.imageAsset',
cdnAccessPolicy: 'public',
currentVersion: {...},
title: 'example-image.png',
versions: [...]
}Global document references use a compound reference ID
Global document references use a more complex _ref than standard reference types. In the asset document example, the _ref value follows this structure: resourceType:projectId.datasetName:documentId.
For more details on creating aspects that use global document references and querying Media Library assets, see the Media Library documentation.