AstroPaper Schema Deep Dive

Understanding AstroPaper’s content collection schema is crucial for successful integration.

The Schema Definition

AstroPaper uses Zod for schema validation:

const blogSchema = ({ image }: SchemaContext) =>
  z.object({
    author: z.string().default(SITE.author),
    pubDatetime: z.date(),  // REQUIRED!
    modDatetime: z.date().optional().nullable(),
    title: z.string(),      // REQUIRED!
    featured: z.boolean().optional(),
    draft: z.boolean().optional(),
    tags: z.array(z.string()).default(["others"]),
    ogImage: image().or(z.string()).optional(),
    description: z.string(), // REQUIRED!
    canonicalURL: z.string().optional(),
    hideEditPost: z.boolean().optional(),
    timezone: z.string().optional(),
  });

Required Fields Analysis

pubDatetime

Must be a valid ISO 8601 date string. Our adapter extracts from:

1. metadata.publishedAt
2. metadata.date
3. metadata.pubDatetime
4. Falls back to new Date() if none found

description

Must be a non-empty string. Our adapter:

1. Uses page.description if available
2. Falls back to page.title if not

title

Must be a non-empty string. Always taken from page.title.

Optional Fields

modDatetime

Modification timestamp. Extracted from:

• metadata.modifiedAt
• metadata.updatedAt

featured

Boolean flag for featured posts. Used to highlight content on the homepage.

tags

String array for categorization. Defaults to ["others"] if not provided.

Adapter Implementation

Our adapter ensures all required fields are present:

buildPostFrontmatter(page: Page, site: Site): AstroPaperPostFrontmatter {
  return {
    title: page.title,
    pubDatetime: this.extractPubDatetime(page), // Never null
    description: page.description || page.title, // Fallback
    // ... other fields
  };
}

Validation Results

Our validatePageContent method returns compatibility results:

return {
  compatible: errors.length === 0,
  warnings: ["No date metadata found - current date will be used"],
  errors: []
};