convex-schema-validator

Convex schema validator

Produces a convex/schema.ts that types every document, indexes every query path, and passes validation against the data already in the database. The one rule: every withIndex in a function needs a matching .index() here, named after its fields, queried in field order.

When to reach for this

• Creating a new table or adding a field to an existing one
• A query uses .filter() and needs an index instead
• Deciding whether to embed an object or link with v.id
• Modeling a document that comes in several shapes
• npx convex dev fails with a schema validation error

Schema skeleton

// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  users: defineTable({
    name: v.string(),
    email: v.string(),
    avatarUrl: v.optional(v.string()),
  }).index("by_email", ["email"]),

  tasks: defineTable({
    userId: v.id("users"),
    title: v.string(),
    completed: v.boolean(),
    priority: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
  })
    .index("by_userId", ["userId"])
    .index("by_userId_and_completed", ["userId", "completed"]),
});

defineTable takes either an object of field validators or a single v.union of v.object validators (see discriminated unions). Every table gets _id and _creationTime for free. Do not declare them.

Validators

Validator	TypeScript type	Note
v.string()	string	UTF-8, under 1 MB
v.number()	number	Float64. Use for timestamps and counts
v.boolean()	boolean
v.null()	null	undefined is not a Convex value. Return null instead
v.int64()	bigint	Not v.bigint(), which is deprecated
v.bytes()	ArrayBuffer	Under 1 MB
v.id("table")	Id<"table">	Typed reference. Convex does not enforce that the target exists
v.array(t)	T[]	At most 8192 items
v.object({...})	{...}	At most 1024 entries. Keys cannot start with $ or _
v.record(k, t)	Record<K, T>	Dynamic ASCII keys. No v.map or v.set
v.union(a, b)	A | B	Use v.literal members for enums
v.literal("x")	"x"
v.optional(t)	T | undefined	Field may be absent
v.any()	any	Last resort. Loses type safety and validation

Optional versus nullable