Convex Schema Validator
Define and validate Convex database schemas with correct types, indexes, optional fields, and unions before shipping backend logic.
Overview
convex-schema-validator is an agent skill for the Build phase that defines and validates Convex database schemas with typing, indexes, optional fields, and unions.
Install
npx skills add https://github.com/waynesutton/convexskills --skill convex-schema-validatorWhat is this skill?
- Guides defining Convex tables with proper typing and validator alignment
- Covers index configuration for query performance on Convex
- Documents optional fields, unions, and nested object patterns in schema
- Validates schema choices against Convex conventions before codegen and deploy
- Pairs with other convexskills for queries, mutations, and deployment flow
Adoption & trust: 2.4k installs on skills.sh; 402 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Convex schema.ts is easy to get wrong—indexes missing, optional fields mistyped, or unions that fail validation at deploy time.
Who is it for?
Solo developers adding or refactoring Convex tables before writing queries, mutations, or auth rules.
Skip if: Projects not on Convex, pure frontend-only work, or teams that already have a frozen schema with no planned changes.
When should I use this skill?
User is defining, changing, or reviewing Convex schema.ts, indexes, or field validators.
What do I get? / Deliverables
You get a reviewed Convex schema aligned with validator rules and index strategy, ready for functions and deployment.
- Validated Convex schema definitions with indexes and field types
Recommended Skills
Journey fit
Schema design is core backend build work on Convex-backed apps before queries and mutations are considered production-ready. Focuses on schema.ts structure, validators, and indexing—directly on the data layer in backend subphase.
How it compares
Convex-specific schema guidance—not generic Prisma or raw SQL migration authoring.
Common Questions / FAQ
Who is convex-schema-validator for?
Indie builders and small teams using Convex who want their agent to shape schema.ts correctly before backend features land.
When should I use convex-schema-validator?
Use in Build while designing or changing Convex tables, when adding indexes for new access patterns, or before first deploy of a new data model.
Is convex-schema-validator safe to install?
It is documentation-driven schema guidance; review the Security Audits panel on this page and avoid pasting production secrets into chat while editing schema.
SKILL.md
READMESKILL.md - Convex Schema Validator
interface: icon_small: "./assets/small-logo.svg" icon_large: "./assets/large-logo.png" <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"> <g clip-path="url(#clip0_3_23)"> <g clip-path="url(#clip1_3_23)"> <path d="M10.0643 12.5735C12.3769 12.3166 14.5572 11.0843 15.7577 9.02756C15.1892 14.1148 9.62646 17.3302 5.08583 15.356C4.66743 15.1746 4.30728 14.8728 4.06013 14.4848C3.03973 12.8825 2.7043 10.8437 3.18626 8.99344C4.56327 11.37 7.3632 12.8267 10.0643 12.5735Z" fill="#F3B01C"/> <path d="M3.1018 7.50072C2.16436 9.66714 2.12376 12.2034 3.27303 14.2907C-0.771507 11.2479 -0.72737 4.7362 3.2236 1.72378C3.58904 1.44535 4.02333 1.2801 4.47881 1.25494C6.3519 1.15614 8.25501 1.88006 9.58963 3.22909C6.87799 3.25604 4.23695 4.99308 3.1018 7.50072Z" fill="#8D2676"/> <path d="M10.8974 3.89562C9.52924 1.98794 7.38779 0.68921 5.04156 0.649695C9.57686 -1.40888 15.1555 1.92867 15.7629 6.86314C15.8194 7.32119 15.7452 7.78824 15.5421 8.20138C14.6948 9.92223 13.1236 11.2569 11.2876 11.7508C12.6328 9.25579 12.4668 6.20748 10.8974 3.89562Z" fill="#EE342F"/> </g> </g> <defs> <clipPath id="clip0_3_23"> <rect width="16" height="16" fill="white"/> </clipPath> <clipPath id="clip1_3_23"> <rect width="16" height="16" fill="white"/> </clipPath> </defs> </svg> --- name: convex-schema-validator displayName: Convex Schema Validator description: Defining and validating database schemas with proper typing, index configuration, optional fields, unions, and migration strategies for schema changes version: 1.0.0 author: Convex tags: [convex, schema, validation, typescript, indexes, migrations] --- # 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 ```typescript // 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.string(), description: v.optional(v.string()), completed: v.boolean(), userId: v.id("users"), priority: v.union( v.literal("low"), v.literal("medium"), v.literal("high") ), }), }); ``` ### Validator Types | Validator | TypeScript Type | Example | |-----------|----------------|---------| | `v.string()` | `string` | `"hello"` | | `v.number()` | `number` | `42`, `3.14` | | `v.boolean()` | `boolean` | `true`, `false` | | `v.null()` | `null` | `null` | | `v.int64()` | `bigint` | `9007199254740993n` | | `v.bytes()` | `ArrayBuffer` | Binary data | | `v.id("table")` | `Id<"table">` | Document reference | | `v.array(v)` | `T[]` | `[1, 2, 3]` | | `v.object({})` | `{ ... }` | `{ name: "..." }` | | `v.optional(v)` | `T \| undefined` | Optional field | | `v.union(...)` | `T1 \| T2` | Multiple types | | `v.literal(x)` | `"x"` | Exact value | | `v.any()` | `any` | Any value | | `v.record(k, v)` | `Record<K, V>` | Dynamic keys | ### Index Configuration ```typescript export default defineSchema({ messages: defineTable({ channelId: v.id("channels"), authorId: v.id("users"), content: v.string(), sentAt: v.number(), }) // Single field index .index("by_channel", ["channelId"]) // Compound index .index("by_channel_and_author", ["channelId", "authorId"]) // Index for sorting .index("by_channel_and_time", ["channelId", "sentAt"]), // Full-text search index articles: defineTable({ title: