Astro Content Collections: How to Validate Content With Schemas

Filter Draft Articles

Many websites store drafts alongside published articles. A schema can define a draft field, but the query must also use it to control which entries appear.

For example:

---
import { getCollection } from "astro:content";

const posts = await getCollection(
  "blog",
  ({ data }) => data.draft === false
);
---

<ul>
  {
    posts.map((post) => (
      <li>
        <a href={`/blog/${post.id}/`}>
          {post.data.title}
        </a>
      </li>
    ))
  }
</ul>

This example includes only entries where draft is explicitly false.

Because the schema defaults draft to false, entries that omit the field receive that value after validation.

For production sites, confirm that the draft policy matches the deployment process. Some teams prefer to exclude drafts explicitly, while others maintain separate collections or build environments for unpublished content.

If draft content must never reach a public deployment, do not rely solely on hiding it in the user interface. Ensure the routing and build process exclude it from public output as required.

Sort Articles by Publication Date

A blog index commonly displays the newest articles first.

Because pubDate is validated as a date, entries can be sorted using the JavaScript date value.

---
import { getCollection } from "astro:content";

const posts = await getCollection(
  "blog",
  ({ data }) => data.draft === false
);

posts.sort(
  (a, b) =>
    b.data.pubDate.getTime() - a.data.pubDate.getTime()
);
---

The subtraction compares the timestamps of the two dates.

The entry with the later publication date appears first. This approach is more reliable than sorting dates as arbitrary strings, especially when the content includes different date formats.

If the website supports scheduled publishing, filtering should also consider the current time and the project's intended publication rules.

Use Strict Schemas for Consistent Content

A basic schema validates data types, but production websites often need more precise rules.

For example, a blog may allow only a fixed set of categories.

Restrict Categories to Known Values

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

const blog = defineCollection({
  schema: z.object({
    title: z.string().min(1),
    description: z.string().min(20),
    pubDate: z.coerce.date(),
    category: z.enum([
      "TypeScript",
      "JavaScript",
      "Web Development",
      "Cloud"
    ]),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false)
  })
});

export const collections = {
  blog
};

This schema introduces two additional constraints.

First, title must contain at least one character. Second, description must contain at least 20 characters.

The category must also match one of the supported values.

These checks can prevent inconsistent category names such as WebDev, Web Development, and web-development from appearing in different entries when the site expects one standard value.

The description length is only an example. Choose a minimum that reflects your editorial requirements rather than assuming that every website needs the same limit.

Validate Tags

A tag array can be refined to reject empty strings:

tags: z.array(
  z.string().trim().min(1)
).default([])

This validation trims whitespace and requires every tag to contain at least one character after trimming.

It helps prevent values such as an empty string or a whitespace-only tag from entering the collection.

For more advanced projects, you can also normalize tag casing or enforce a predefined set of tags. Keep the validation rules aligned with how tags are displayed, searched, and stored.

Organize Different Content Types

A website may contain both blog articles and documentation pages. These content types often require different metadata.

Astro allows each collection to define its own schema.

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

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    author: z.string(),
    draft: z.boolean().default(false)
  })
});

const documentation = defineCollection({
  schema: z.object({
    title: z.string(),
    section: z.string(),
    order: z.number().int().nonnegative()
  })
});

export const collections = {
  blog,
  documentation
};

The blog collection requires publication information and an author. The documentation collection requires a section and an ordering value.

This separation avoids forcing every content type to use the same fields.

It also makes content queries easier to understand. A documentation page can be sorted by order, while blog articles can be sorted by pubDate.

When choosing between collections, consider whether the content types have meaningfully different validation requirements, publishing workflows, or routing rules.

Common Mistakes and Troubleshooting

When a schema change causes validation failures, review the affected content before weakening the schema. A validation error may reveal a real content-quality problem rather than a problem with the validation system.

For larger repositories, include the Astro build or content validation process in continuous integration so that invalid content is detected before deployment.

Best Practices for Production Projects

Keep Schemas Aligned With Editorial Requirements

Do not add validation rules simply because they are technically possible. Each rule should reflect a real requirement, such as mandatory descriptions, valid categories, or consistent publication dates.

Overly restrictive schemas can slow down routine content updates.

Use Defaults Carefully

Defaults are useful for optional fields such as tags and draft status. Avoid assigning default values to essential fields when doing so would hide missing information.

For example, a missing article title should normally produce a validation error rather than silently receiving a generic title.

Validate Content During CI

Run the project's standard build or validation process before deploying changes. This helps catch invalid frontmatter before it reaches production.

For repositories with many contributors, automated validation also creates a consistent review process.

Plan Schema Changes

When introducing a required field or changing a field's type, inspect existing content first. Update the affected entries or design a migration strategy before enforcing the new schema.

This is particularly important for large documentation sites and blogs maintained by multiple authors.

Keep Content and Presentation Separate

Use schemas to validate content metadata and Astro components to render it.

This separation allows developers to improve the site's layout without changing the underlying content format unnecessarily.

Advantages and Limitations of Astro Content Collections

Advantages

• Type-safe content access: Schemas provide predictable types for content metadata.
• Early error detection: Invalid frontmatter can be identified during content processing.
• Consistent content structure: Required fields and allowed values reduce inconsistency.
• Easier querying: Collections provide a structured API for filtering and sorting entries.
• Better maintainability: Content rules are defined centrally instead of being repeated across pages.

Limitations

• Schema maintenance: Rules must evolve alongside the content model.
• Migration effort: Existing entries may need updates when validation becomes stricter.
• Limited scope: Frontmatter validation does not automatically validate every aspect of the Markdown body.
• Additional configuration: Small sites may need only a simple schema, while complex sites require more planning.
• Version differences: Projects using older Astro content APIs may need configuration changes when upgrading.

Conclusion

Astro Content Collections provide a structured way to manage Markdown and other supported content while validating metadata against clearly defined schemas. By combining collection definitions with Zod validation, developers can catch missing fields, incorrect data types, invalid dates, and inconsistent categories before those problems affect the website.

For production projects, begin with a schema that reflects the content's actual requirements. Add stricter validation where it improves consistency, filter drafts according to the publishing workflow, and run content validation as part of the deployment process.

The result is a content system that is easier to query, maintain, and extend as a website grows.