When to and when not to use return validators in Convex

Convex recently updated its guidance on return validators. The old rule was "always add a returns validator." The new guidance is: prefer simple TypeScript types and inference by default. Use returns: when you actually want Convex to enforce an exact runtime contract.

Return validators aren't bad. The word "always" was doing damage.

What is a return validator?

Convex lets you validate arguments coming into a function using args and return values going out using returns. A return validator declares the return shape, and Convex checks it at runtime.

import { query } from "./_generated/server";
import { v } from "convex/values";