IDs and Paths
How document IDs work, and what you can do with them
Every document in a Sanity dataset must have an ID that identifies it, an arbitrary string of maximum 128 characters made up of the characters a-zA-Z0-9._-. Note that an ID cannot start with a - (dash) character, and must not have more than one consecutive . character. E.g. -abcde-12345 would be an invalid ID, as would -a..bcde-12345.
The ID is specified in the document’s _id property, and must be unique within the dataset. The ID cannot be modified once a document is created, since it is used to track the document’s history and relations.
The Sanity Studio automatically generates a random UUID for new documents (e.g. 189bc292-e41b-42a0-91b5-bfaa33a34af2), and does not allow you to specify an ID yourself, but you are free to use your own ID scheme for documents that you create using the HTTP API.
IDs with multiple segments separated by periods must not include the segment versions unless it is the first segment. When the first segment is versions the ID must have at least three segments. For example, versions.abc.xyz is permitted, but versions.abc and abc.versions.bar are not. These restrictions are due to internal implementation requirements.
Gotcha
We advise against using our APIs to create document IDs prefixed with versions.. Such documents may react with platform functionality in unexpected ways.
Gotcha
For technical reasons, every document ID ever written to a dataset will be retained in our systems until the dataset is deleted, even if the document itself is deleted. For this reason, we strongly recommend you never put personal data or other sensitive data in document IDs.
IDs are also considered paths, separated by periods. You can use this to organize documents into namespaces by using IDs like animal.mammal.dog – kind of like folders on your computer. Note that path segments cannot start with the - (dash) character. E.g. a dog.-abcde-12345 would be an invalid ID.
GROQ provides a path() function that allows you to filter documents by path, such as fetching all mammals with _id in path("animal.mammal.*") or fetching all animals with _id in path("animal.**"). In path expressions, * is taken to mean “anything up to the next period”, while ** means “anything including periods”. The path() function currently only works with the _id attribute, since it requires special indexing.
Sanity also uses paths for storing various internal data in your datasets. For example, internal objects like groups are stored under the _. path, and the content studio stores draft documents under the drafts. path.
Gotcha
The default, fixed access control rules give unauthenticated users read access to documents under the root path only, which means that it is not possible to make documents under a sub-path (i.e. containing a . in the ID) publicly available. This currently cannot be changed unless you have custom access controls enabled on your plan.