convex-schema-validator

Name: convex-schema-validator - Agent Skill
Rating: 3.4 (190 reviews)
Author: waynesutton

190

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

Download Folder View on GitHub

CLI Install

Recommended

Use the skills CLI to install this skill with one command. Auto-detects all installed AI assistants.

Method 1 - skills CLI

npx skills i waynesutton/convexskills/skills/convex-schema-validator

Method 2 - openskills (supports sync & update)

npx openskills install waynesutton/convexskills

Auto-detects Claude Code, Cursor, Codex CLI, Gemini CLI, and more. One install, works everywhere.

Installation Path

Download and extract to one of the following locations:

~/.claude/skills/convex-schema-validator/

SKILL.md

agents

assets

Skill Instructions

Back

Run with Cloud Agent

No setup needed. Let our cloud agents run this skill for you.

Select Provider

Select Model

Claude Sonnet 4.5

$0.20/task

Best for coding tasks

Environment setup included

Convex Schema Validator

Define and validate database schemas in Convex with proper typing, index configuration, optional fields, unions, and strategies for schema migrations.

Documentation Sources

Before implementing, do not assume; fetch the latest documentation:

Primary: https://docs.convex.dev/database/schemas
Indexes: https://docs.convex.dev/database/indexes
Data Types: https://docs.convex.dev/database/types
For broader context: https://docs.convex.dev/llms.txt

Instructions

Basic Schema Definition

// 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()),
    createdAt: v.number(),
  }),
  
  tasks: defineTable({
    title: v.

Validator Types

Validator	TypeScript Type	Example
`v.string()`	`string`	`"hello"`
`v.number()`	`number`	`42`, `3.14`
`v.boolean()`	`boolean`	`true`,

Index Configuration

export default defineSchema({
  messages: defineTable({
    channelId: v.id("channels"),
    authorId: v.id("users"),
    content: v.string(),
    sentAt: v.number(),
  })
    // Single field index
    .index(

Complex Types

export default defineSchema({
  // Nested objects
  profiles: defineTable({
    userId: v.id("users"),
    settings: v.object({
      theme: v.union(v.literal("light"), v.literal("dark")),

Discriminated Unions

export default defineSchema({
  events: defineTable(
    v.union(
      v.object({
        type: v.literal("user_signup"),
        userId: v.id("users"),
        email: v.string(),
      }),
      v.object({

Optional vs Nullable Fields

export default defineSchema({
  items: defineTable({
    // Optional: field may not exist
    description: v.optional(v.string()),
    
    // Nullable: field exists but can be null
    deletedAt: v.union(v.number(), v.null()),
    
    // Optional and nullable
    notes: v.optional(v.union(v.string(), v.

Index Naming Convention

Always include all indexed fields in the index name:

export default defineSchema({
  posts: defineTable({
    authorId: v.id("users"),
    categoryId: v.id("categories"),
    publishedAt: v.number(),
    status: v.string(),
  })
    // Good: descriptive names
    .index("by_author", ["authorId"

Schema Migration Strategies

Adding New Fields

// Before
users: defineTable({
  name: v.string(),
  email: v.string(),
})
 
// After - add as optional first
users: defineTable({
  name: v.string(),
  email: v.string(),
  avatarUrl: v.optional(v.string()), // New optional field
})

Backfilling Data

// convex/migrations.ts
import { internalMutation } from "./_generated/server";
import { v } from "convex/values";
 
export const backfillAvatars = internalMutation({
  args: {},
  returns: v.number(),
  handler: async (ctx) => {

Making Optional Fields Required

// Step 1: Backfill all null values
// Step 2: Update schema to required
users: defineTable({
  name: v.string(),
  email: v.string(),
  avatarUrl: v.string(), // Now required after backfill
})

Examples

Complete E-commerce Schema

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

Using Schema Types in Functions

// convex/products.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { Doc, Id } from "./_generated/dataModel";
 
// Use Doc type for full documents
type Product = Doc<"products">;
 
// Use Id type for references

Best Practices

Never run npx convex deploy unless explicitly instructed
Never run any git commands unless explicitly instructed
Always define explicit schemas rather than relying on inference
Use descriptive index names that include all indexed fields
Start with optional fields when adding new columns
Use discriminated unions for polymorphic data
Validate data at the schema level, not just in functions
Plan index strategy based on query patterns

Common Pitfalls

Missing indexes for queries - Every withIndex needs a corresponding schema index
Wrong index field order - Fields must be queried in order defined
Using v.any() excessively - Lose type safety benefits
Not making new fields optional - Breaks existing data
Forgetting system fields - _id and _creationTime are automatic

References

Convex Documentation: https://docs.convex.dev/
Convex LLMs.txt: https://docs.convex.dev/llms.txt
Schemas: https://docs.convex.dev/database/schemas
Indexes: https://docs.convex.dev/database/indexes
Data Types: https://docs.convex.dev/database/types

description: v.optional(v.string()),

completed: v.boolean(),

userId: v.id("users"),

v.literal("medium"),

.index("by_channel_and_author", ["channelId", "authorId"])

// Index for sorting

.index("by_channel_and_time", ["channelId", "sentAt"]),

// Full-text search index

articles: defineTable({

category: v.string(),

.searchIndex("search_content", {

searchField: "body",

filterFields: ["category"],

notifications: v.object({

// Arrays of objects

orders: defineTable({

customerId: v.id("users"),

items: v.array(v.object({

productId: v.id("products"),

quantity: v.number(),

v.literal("pending"),

v.literal("processing"),

v.literal("shipped"),

v.literal("delivered")

// Record type for dynamic keys

analytics: defineTable({

metrics: v.record(v.string(), v.number()),

type: v.literal("purchase"),

userId: v.id("users"),

orderId: v.id("orders"),

type: v.literal("page_view"),

sessionId: v.string(),

).index("by_type", ["type"]),

.index("by_author_and_category", ["authorId", "categoryId"])

.index("by_category_and_status", ["categoryId", "status"])

.index("by_status_and_published", ["status", "publishedAt"]),

const users = await ctx.db

.filter((q) => q.eq(q.field("avatarUrl"), undefined))

for (const user of users) {

await ctx.db.patch(user._id, {

avatarUrl: `https://api.dicebear.com/7.x/initials/svg?seed=${user.name}`,

return users.length;

users: defineTable({

role: v.union(v.literal("customer"), v.literal("admin")),

createdAt: v.number(),

.index("by_email", ["email"])

.index("by_role", ["role"]),

products: defineTable({

description: v.string(),

category: v.string(),

inventory: v.number(),

isActive: v.boolean(),

.index("by_category", ["category"])

.index("by_active_and_category", ["isActive", "category"])

.searchIndex("search_products", {

searchField: "name",

filterFields: ["category", "isActive"],

orders: defineTable({

userId: v.id("users"),

items: v.array(v.object({

productId: v.id("products"),

quantity: v.number(),

priceAtPurchase: v.number(),

v.literal("pending"),

v.literal("shipped"),

v.literal("delivered"),

v.literal("cancelled")

shippingAddress: v.object({

country: v.string(),

createdAt: v.number(),

updatedAt: v.number(),

.index("by_user", ["userId"])

.index("by_user_and_status", ["userId", "status"])

.index("by_status", ["status"]),

reviews: defineTable({

productId: v.id("products"),

userId: v.id("users"),

comment: v.optional(v.string()),

createdAt: v.number(),

.index("by_product", ["productId"])

.index("by_user", ["userId"]),

type ProductId = Id<"products">;

export const get = query({

args: { productId: v.id("products") },

_id: v.id("products"),

_creationTime: v.number(),

description: v.string(),

category: v.string(),

inventory: v.number(),

isActive: v.boolean(),

handler: async (ctx, args): Promise<Product | null> => {

return await ctx.db.get(args.productId);