convex-schema-validator_skill

Overview

This skill helps define and validate Convex database schemas with correct typing, index configuration, optional fields, unions, and migration strategies. It focuses on producing explicit, production-ready schemas that prevent runtime errors and support predictable queries and migrations. The skill includes patterns for indexes, complex types, discriminated unions, and safe field changes.

How this skill works

The skill inspects schema definitions built with Convex validators (v.string(), v.id(), v.object(), v.union(), etc.) and checks typing, index declarations, and search indexes for consistency with query patterns. It flags common mistakes like missing or misordered indexes, overuse of v.any(), and unsafe nullable/required transitions. It also recommends migration steps (add optional fields, backfill, then require) and provides examples for backfill mutations and index naming.

When to use it

• When designing new Convex tables to ensure types and indexes match query needs
• Before deploying schema changes that add, remove, or make fields required
• When modeling polymorphic data using discriminated unions
• When adding full-text search or compound indexes for sorting/filtering
• When auditing existing schemas to catch missing indexes or type gaps

Best practices

• Always define explicit schemas; avoid relying on inference or v.any() except when necessary
• Name indexes to include all indexed fields and maintain field order in queries
• Add new fields as optional first, backfill existing rows, then switch to required
• Use discriminated unions for polymorphic tables and include a type literal for indexing
• Validate complex nested objects and arrays at the schema level, not only in functions

Example use cases

• Create an e-commerce schema with users, products, orders, reviews and indexes for common queries
• Define a messages table with channel/author/time indexes and a search index for articles
• Model events as a discriminated union to support signup, purchase, and page_view records
• Migrate a users table to add avatarUrl: add as optional, run a backfill mutation, then require it
• Audit an analytics table to replace v.any() with v.record(v.string(), v.number()) for safety