How to Validate CMS Content Against a TypeScript Schema at Build Time

Imagine a marketing team uses Sanity to manage a product landing page. The page has a hero section with a required headline, a CTA button label, and a background image. A developer builds the frontend expecting all three fields to always be present.

One day an editor accidentally clears the CTA button label while editing a draft and then publishes. Without build-time validation, the next deployment silently renders a button with no text — a broken experience that reaches users.

With build-time validation in place, the CI pipeline catches the problem immediately:

// lib/validators/landingPage.ts
import { z } from 'zod';

export const HeroSchema = z.object({
  headline: z.string().min(1, 'Hero headline is required'),
  ctaLabel: z.string().min(1, 'CTA button label must not be empty'),
  backgroundImage: z.object({
    asset: z.object({ _ref: z.string() }),
  }),
});

export const LandingPageSchema = z.object({
  _id: z.string(),
  _type: z.literal('landingPage'),
  hero: HeroSchema,
});

When the validation script runs during the prebuild step, it outputs a clear error and exits with code 1:

$ npm run validate-content

Validating CMS content...
LandingPage "homepage" failed validation:
  [hero.ctaLabel] CTA button label must not be empty

Content validation failed: Build aborted: one or more documents failed schema validation.
npm error code 1

The deployment is blocked. The CI system notifies the team via Slack or email. The editor fixes the CTA label in Sanity, triggers a new deployment, and this time validation passes. The broken page never reaches production.

This pattern scales to any content type. You can write a single validation runner that imports all your schemas and validates all document types in one pass:

// scripts/validateContent.ts
import { client } from '../lib/sanity/client';
import { PostSchema } from '../lib/validators/post';
import { LandingPageSchema } from '../lib/validators/landingPage';
import { z } from 'zod';

const validators: Record<string, z.ZodTypeAny> = {
  post: PostSchema,
  landingPage: LandingPageSchema,
};

async function validateAll() {
  let hasErrors = false;

  for (const [docType, schema] of Object.entries(validators)) {
    const docs = await client.fetch(`*[_type == $type]`, { type: docType });
    for (const doc of docs) {
      const result = schema.safeParse(doc);
      if (!result.success) {
        hasErrors = true;
        console.error(`\n[${docType}] "${doc._id}" failed validation:`);
        result.error.issues.forEach((issue) => {
          console.error(`  [${issue.path.join('.')}] ${issue.message}`);
        });
      }
    }
  }

  if (hasErrors) {
    throw new Error('Build aborted: content validation errors found above.');
  }

  console.log('All content validated successfully.');
}

validateAll().catch((err) => {
  console.error(err.message);
  process.exit(1);
});

"TypeScript types are enough — I don't need runtime validation"

TypeScript types are compile-time constructs. They are completely erased when your code is compiled to JavaScript. When your application fetches data from Sanity's API at build time or runtime, TypeScript has no way to verify that the response matches your type annotations. You can cast any value to any type with as, and TypeScript will not complain. Runtime validation with Zod (or a similar library) is the only way to actually verify the shape of external data.

"Sanity's required field validation prevents missing data"

Sanity's validation rules are enforced in the Studio UI, but they are warnings by default — editors can still publish documents that fail validation if they choose to. Additionally, content imported via the API, migrated from another system, or created before a required field was added will not be retroactively validated. Build-time validation in your frontend is the authoritative check that runs against the actual data your application will consume.

"@sanity/codegen generates validators, not just types"

@sanity/codegen generates TypeScript type definitions and typed query helpers. It does not generate Zod schemas or any other runtime validators. You still need to write Zod schemas by hand (or use a tool like sanity-zod-types if one exists for your version). The generated types are useful as a reference and for compile-time compatibility checks, but they do not replace runtime validation.

"Build-time validation is too slow for large content sets"

Zod validation is extremely fast — parsing thousands of documents takes milliseconds. The bottleneck is the network round-trip to fetch content from Sanity's API, which you are already paying during the build. Validation adds negligible overhead on top of the fetch. For very large datasets (tens of thousands of documents), you can validate in parallel using Promise.all or stream results in batches, but for most projects this is not necessary.

"I should validate in the frontend component, not at build time"

Validating inside a React component means the validation runs after the page has already been rendered or is in the process of rendering. By that point, a missing required field may have already caused a crash or a broken layout. Build-time validation catches the problem before any rendering happens, giving you a clean failure with a descriptive error message rather than a cryptic runtime exception in production.