How to set document type with sub-path prefix in document ID?

Based on the documentation I reviewed, I need to give you an important heads-up about using dots in document IDs like private.document-xxxxx:

Documents with dots in their IDs become private and only accessible via authenticated requests. This is a critical limitation that fundamentally changes how your content works in Sanity.

The Reality of Custom Document IDs

While you can technically create documents with custom IDs like private.document-xxxxx, the official documentation actually recommends against using custom IDs for most use cases. Instead, they suggest creating a custom field in your schema to store identifiers.

Here's why: once you set a document ID with a dot pattern, that document won't be publicly queryable without authentication. This might be what you want, but it's often an unexpected side effect.

If You Still Need Custom IDs

If you genuinely need custom document IDs with dots, here are the legitimate ways to create them:

1. Via the API (Most Common)

import {createClient} from '@sanity/client'

const client = createClient({
  projectId: 'your-project-id',
  dataset: 'your-dataset',
  token: 'your-token', // Required for write operations
  apiVersion: '2025-01-01'
})

await client.create({
  _id: 'private.document-xxxxx',
  _type: 'yourDocumentType',
  // ... other fields
})

2. Via the CLI

sanity documents create --id 'private.document-xxxxx'

3. In Studio URL (When Creating New Documents)

Append ;desiredId to the Studio URL when creating a new document:

http://localhost:3333/structure/yourDocumentType;private.document-xxxxx

What About Initial Value Templates?

Initial Value Templates are configured in sanity.config.ts using document.newDocumentOptions, and while the documentation shows they can set initial values, they cannot reliably set custom _id values with dots because:

1. The Studio's auto-generation may override your custom ID
2. The privacy implications of dot-prefixed IDs aren't surfaced to editors
3. It's not the intended use case for templates

Initial Value Templates are better suited for setting field values, not document IDs.

Better Alternatives

Instead of custom IDs with dots, consider:

Option 1: Use a custom field

defineField({
  name: 'customIdentifier',
  type: 'string',
  validation: Rule => Rule.required()
})

Then query by this field instead of _id.

Option 2: Use a naming convention without dots Use underscores or hyphens instead: private_document-xxxxx or private-document-xxxxx. These won't trigger the privacy behavior.

Option 3: Use proper access control If you need private documents, use Sanity's access control features rather than relying on ID patterns.

Important Notes About Document IDs

• Valid characters: a-zA-Z0-9._- (up to 128 characters)
• Once set, _id never changes
• The drafts. prefix is reserved by Sanity
• Dots in IDs make documents private - this is not just a naming convention, it's a security boundary

The bottom line: if you're just looking for a way to organize or identify documents, use a custom field instead. Custom IDs with dots should only be used when you specifically need the privacy behavior they provide.