How to create a document with a weak reference using Sanity client?

Perfect! I found the answer. The issue is with the property name when creating documents programmatically.

When defining a weak reference in your schema, you use weak: true, but when creating or updating documents through the Sanity client (via mutations), you need to use _weak: true (with an underscore) instead:

const author = {
  _type: 'reference',
  _ref: id,
  _weak: true,  // Note the underscore!
};

This is a naming convention difference between schema definitions and the actual document format. The weak references documentation specifically covers this distinction.

So your corrected code should look like:

// When creating via Sanity client
const doc = {
  _type: 'myDocument',
  author: {
    _type: 'reference',
    _ref: id,
    _weak: true  // Use _weak, not weak
  }
};

client.create(doc);

The _weak property tells Sanity that this reference doesn't require the referenced document to exist and allows it to point to draft documents. This is particularly useful when referencing documents that are still in draft mode or when you need more flexible content workflows where documents can be created in any order.