Is it possible to set a weak reference through a mutation in Sanity.io?

Yes, it's definitely possible to set a weak reference through a mutation! The issue you're encountering is that you're using the wrong property name.

When defining weak references in your schema, you use weak: true. However, when creating weak references in mutations (through the API/client), you need to use _weak: true (with an underscore) instead.

Here's your corrected mutation:

mutation = {
    mutations: [
        {
            create: {
                _id: crypto.randomUUID(),
                _type: "team",
                title: team.name,
                badgeUrl: team.logo,
                footballApiId: team.id,
                isNationalTeam: team.national,
                country: {
                    _type: 'reference',
                    _weak: true,  // Changed from 'weak' to '_weak'
                    _ref: sanityCountry._id
                },
                slug: {
                    type: '_slug',
                    current: slugify(`${team.id}-${team.name}`)
                }
            }
        }
    ]
}

This naming convention difference is documented in the Sanity weak references documentation. The _weak property tells Sanity that this reference doesn't require the referenced document to exist and allows linking to unpublished/draft documents, which can be really helpful for flexible content workflows.

The underscore prefix follows Sanity's convention for system-level properties in the actual document data, while the schema uses the more readable weak property name for configuration. So remember: weak: true in schemas, _weak: true in mutations and document data!