Defining and validating database schemas with proper typing, index configuration, optional fields, unions, and migration strategies for schema changes

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 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 v.optional means the key may be missing from the document. v.union(t, v.null()) means the key is always present and may hold null . They are different at validation time. Use v.optional for fields added after the table had data. Use v.union(..., v.null()) when "explicitly cleared" carries meaning. Discriminated unions For a table whose documents come in several shapes, pass a v.union of v.object validators to defineTable . Each member has the same literal key so TypeScript narrows on it. Put the discriminant ( kind ) first in any index on a union table so queries can scope to one shape. Prefer this over one wide object full of v.optional fields. Indexes Naming and field order Name the index after its fields in order: by field1 and field2 . Querying must follow the same order: equality on a prefix of the fields, then at most one range on the next field. You cannot skip channelId and filter on sentAt alone with that index. Add by sentAt if that query exists. creationTime is appended to every index automatically, so results within an equal prefix sort by creation time. Reserved names: by id and by creation time . Limits: 32 indexes per table, 16 fields per index. When to add one Any field a function passes to withIndex , .eq , or a range comparison Every foreign key ( userId , channelId , orgId ) on the child table The sort field for a paginated list, prefixed by the scoping field Not for fields you only read after fetching the document Not for tiny tables where a .collect() then in memory filter is fine If a query uses .filter() , that is the signal to add an index and switch to withIndex . Relationships Link documents with v.id("table") on the child. Do not nest growing arrays of objects inside the parent. Embed with v.object or a small v.array only when the data is bounded, always loaded with the parent, and updated together. A user's settings object is a good embed. A user's posts array is not: it hits the 8192 item cap and every post edit rewrites the user document. System fields id: Id<"table" and creationTime: number (ms since epoch) exist on every document. Include them in return validators when a function returns whole documents: Do not add your own createdAt unless you need a value that differs from insertion time. Search and vector indexes Declared on the table like regular indexes. filterFields must be top level fields. Query search indexes with withSearchIndex in queries. Vector search runs only in actions via ctx.vectorSearch . Common mistakes Mistake Why it breaks Do instead withIndex("by userId") with no matching .index() Deploy fails Declare the index in the schema first Index named by user on ["userId", "status"] Hides what it covers, easy to misuse by userId and status Querying status on by userId and status without userId Index prefix rule Add by status or include userId Adding newField: v.string() to a table with rows Existing documents fail validation v.optional , backfill, then require posts: v.array(v.object(...)) on users 8192 cap, write conflicts on every edit Separate posts table with by authorId v.bigint() Deprecated v.int64() Declaring id or creationTime in defineTable Rejected They are automatic v.any() to move fast No validation, no types Model the shape, or a v.union of the real cases v.union(v.string(), v.null()) for a new field Old documents lack the key entirely v.optional(v.string()) Storing a Date Not a Convex value v.number() ms timestamp Checklist [ ] Schema lives in convex/schema.ts and exports defineSchema(...) as default [ ] Every table has explicit field validators, no v.any() unless justified [ ] Every withIndex call in convex/ has a matching .index() with fields in the name [ ] Foreign keys are v.id("table") with an index on the child table [ ] No unbounded arrays of objects embedded in a parent document [ ] Fields added to tables with data are v.optional [ ] Enums and polymorphic shapes use v.union of v.literal or v.object members [ ] Return validators include id and creationTime when returning whole documents [ ] npx convex dev pushes without a schema validation error Docs https://docs.convex.dev/llms.txt https://docs.convex.dev/database/schemas https://docs.convex.dev/database/indexes https://docs.convex.dev/database/types https://docs.convex.dev/database/reading data

convex-schema-validator