How to Define Collection Schema in Astro for Content Collections

In Astro, you define a collection schema by creating a schema object using zod or another validation library and then registering it with defineCollection. This schema describes the shape and rules for your content files in the collection, ensuring consistent data structure.

Syntax

To define a collection schema in Astro, you use the defineCollection function and pass a schema object created with zod. The schema defines the expected fields and their types for content files.

Key parts:

• defineCollection({ schema }): Registers the schema for a collection.
• z.object({ ... }): Creates a schema object describing fields.
• Field types like z.string(), z.number(), z.boolean() define expected data types.

typescript

import { z, defineCollection } from 'astro:content';

const blogSchema = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.string(),
    draft: z.boolean().optional(),
  }),
});

Example

This example shows how to define a blog post collection schema with title, date, and optional draft status. It ensures all blog posts have a title and date, and optionally a draft flag.

typescript

import { z, defineCollection } from 'astro:content';

// Define the blog collection schema
const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.string(),
    draft: z.boolean().optional(),
  }),
});

export const collections = {
  blog: blogCollection,
};

Output

No runtime output; this code sets up validation for content files in the 'blog' collection.

Common Pitfalls

Common mistakes when defining collection schemas in Astro include:

• Not importing z and defineCollection from astro:content.
• Using incorrect field types that don't match the content data.
• Forgetting to export the collections object so Astro can find the schemas.
• Not marking optional fields with .optional(), causing validation errors.

Always test your schema with sample content files to catch mismatches early.

typescript

/* Wrong way: missing optional for draft */
import { z, defineCollection } from 'astro:content';

const wrongSchema = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.string(),
    draft: z.boolean(), // draft is required here
  }),
});

/* Right way: draft is optional */
const correctSchema = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.string(),
    draft: z.boolean().optional(),
  }),
});

Quick Reference

• Import: import { z, defineCollection } from 'astro:content';
• Define schema: Use z.object({ field: z.type() }) to describe fields.
• Optional fields: Use .optional() to allow missing fields.
• Register collection: Pass schema to defineCollection.
• Export collections: Export an object with collection names and schemas.

Key Takeaways

Use zod schemas with defineCollection to enforce content structure in Astro.

Always mark optional fields with .optional() to avoid validation errors.

Export your collections object so Astro can apply the schemas.

Test your schema with sample content to ensure correctness.

Import z and defineCollection from 'astro:content' to access schema tools.