Get help on Discord

Custom validation messages for specific fields in document-level validation

2 replies
Last updated: Dec 1, 2025
Hello everyone, I have a question regarding validation at document level.While reading the doc (
https://www.sanity.io/docs/validation ), I realized there’s no info about custom validation messages when you want to address a specific field in the document, when validation triggers an error.I tried to implement the Validating children code as return value, but first I don’t have to validate an array, and second it’s not working (
https://www.sanity.io/docs/validation#9e69d5db6f72 ).At the moment, my return condition look like this and I can see the validation error on a document level (top bar) and not on the desired field.

...
return myCondition
      ? ({ message, paths: [{ name: 'name-of-the-field' }] })
      : true;
Does someone have experience with this scenario?
AI Update

I apologize for the confusion in my previous answer! You're absolutely right that the syntax wasn't working. The correct property is path (singular), not paths, and it takes a single array of path segments, not a nested array.

Here's the correct syntax for document-level validation that targets a specific field:

validation: (rule) => rule.custom((document) => {
  return myCondition
    ? { message: 'Your error message', path: ['name-of-the-field'] }
    : true;
})

Notice it's path: ['fieldName'] with a single array, not paths: [['fieldName']].

For nested fields, you'd structure the path array with multiple segments:

// For a nested field like document.author.name
path: ['author', 'name']

// For an array item with a specific _key
path: ['items', { _key: 'abc123' }, 'title']

Here's a complete working example from the official documentation:

export default defineType({
  name: 'post',
  type: 'document',
  title: 'Blog Post',
  validation: (rule) =>
    rule.custom((fields) => {
      if (
        fields.authors.length > 0 &&
        Object.keys(fields.guest).length > 0
      )
        return {
          message: "You can't have an author AND guest author",
          path: ['guest'], // Error appears on the guest field
        }
      return true
    }),
  fields: [
    defineField({
      name: 'authors',
      title: 'Authors',
      type: 'array',
      of: [{ type: 'authorReference' }],
    }),
    defineField({
      name: 'guest',
      title: 'Guest Author',
      type: 'object',
      fields: [
        defineField({ name: 'name', type: 'string', title: 'Guest Author Name' }),
        defineField({ name: 'site', type: 'string', title: 'Guest Author Site' }),
      ],
    }),
  ],
})

Key points:

  1. Use path (singular), not paths (plural)
  2. The value is a single array of path segments: ['fieldName']
  3. For nested fields, add more segments: ['parent', 'child']
  4. This validation goes on the document type itself, not on individual fields
  5. The path must exactly match your field names (case-sensitive)

The validation documentation section on "Marking nested fields as invalid" shows this pattern clearly. The confusion comes from the "Validating children" section which uses paths (plural) for array validation, but for document-level validation targeting specific fields, you need path (singular).

This should make your validation error appear directly on the targeted field instead of just in the document-level top bar!

Show original thread
2 replies

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?