Setting JSON field value in document action causes validation error

I can see you're running into a tricky issue! The "Name contains invalid characters" error is cryptic, but I can help you troubleshoot this based on how document actions and patches work in Sanity.

Understanding the Error

The "Name contains invalid characters" validation error from Sanity's mutation API is typically related to the structure of your patch operation itself, not necessarily the content you're trying to save. This error often appears when there's an issue with how the patch is being constructed or when field names in the patch contain unexpected characters.

The Correct Patch Syntax

When using the patch operation from useDocumentOperation, you need to use the builder pattern, not pass objects directly to execute():

// ✅ Correct syntax with builder pattern
patch.set({frankenCode: jsonData})
patch.execute()

// ❌ Wrong - don't pass arguments to execute()
patch.execute([{set: {frankenCode: jsonData}}])

The patch object returned by useDocumentOperation has methods like .set(), .unset(), .setIfMissing(), etc., that you chain before calling .execute() with no arguments.

Common Causes & Solutions

1. Field Name Issues

The error might occur if your field name contains characters that aren't valid in Sanity's patch path syntax. Field names should be simple identifiers. Double-check that:

• The field name matches your schema exactly (case-sensitive)
• There are no special characters, spaces, or unusual formatting
• You're not accidentally including dots or brackets in the field name itself

// Make sure this matches your schema definition exactly
defineField({
  name: 'frankenCode', // Simple, clean field name
  type: 'json',
  readOnly: true,
})

2. JSON Field Value Format

For the sanity-plugin-json-input plugin, you should pass a plain JavaScript object (not a stringified JSON). You were right to avoid JSON.stringify():

// ✅ Correct - plain object
const jsonData = {
  someKey: "value",
  nested: {
    data: "here"
  }
}
patch.set({frankenCode: jsonData})
patch.execute()

// ❌ Wrong - stringified
patch.set({frankenCode: JSON.stringify(jsonData)})

3. Check for Nested Path Issues

If frankenCode is nested within another object in your schema, you might need to set the full path or the parent object:

// If frankenCode is nested
patch.set({'parentObject.frankenCode': jsonData})
patch.execute()

// Or set the entire parent object
patch.set({parentObject: {...existingData, frankenCode: jsonData}})
patch.execute()

4. Verify Draft vs Published Document

The useDocumentOperation hook should handle this automatically, but verify you're working with the correct document version:

const {patch, publish} = useDocumentOperation(id, type)

// The patch automatically targets the draft if it exists
// But you can log to verify
console.log('Document ID:', id)

Debugging Approach

Add logging to see exactly what's being sent:

const handlePublish = () => {
  const jsonData = processYourData()
  
  console.log('Field name:', 'frankenCode')
  console.log('JSON data:', jsonData)
  console.log('JSON data type:', typeof jsonData)
  console.log('Is plain object:', jsonData?.constructor === Object)
  
  patch.set({frankenCode: jsonData})
  patch.execute()
  publish.execute()
}

The Flash You're Seeing

The fact that the data "flashes" in the UI suggests the patch is being applied locally in the Studio first (optimistic update), but then the mutation API rejects it when trying to persist to the Content Lake. This timing confirms the issue is with the mutation itself.

Alternative Approach: Use the Sanity Client

If the issue persists, you could try using the Sanity client directly to get more detailed error information:

import {useClient} from 'sanity'

// In your document action
const client = useClient({apiVersion: '2024-01-01'})

const handlePublish = async () => {
  const jsonData = processYourData()
  
  try {
    await client
      .patch(id.replace('drafts.', ''))
      .set({frankenCode: jsonData})
      .commit()
    
    publish.execute()
  } catch (error) {
    console.error('Detailed patch error:', error)
    // This might give you more specific information
  }
}

Key Takeaway

The most likely issue is the patch syntax—make sure you're using patch.set({field: value}) followed by patch.execute() with no arguments, not passing patch objects to execute(). Also verify that your field name is a simple identifier without special characters, and that you're passing a plain JavaScript object (not stringified JSON) to the json field.

If none of these solve it, I'd recommend inspecting the exact structure of your jsonData object—sometimes deeply nested or circular structures can cause unexpected validation errors at the API level.