Schema Reference

Complete reference for the blog.json file structure. All fields are optional unless marked as required.

Root Structure

{
  "site": { ... },      // Site metadata (required)
  "basics": { ... },    // Author information
  "posts": [ ... ],     // Blog posts
  "pages": [ ... ]      // Static pages
}

site (required)

Core website metadata.

Field	Type	Description
`title`	string	Your blog's title
`description`	string	Brief description for meta tags
`url`	string	Full URL (e.g., https://blog.example.com)

basics

Information about the author.

Field	Type	Description
`name`	string	Author's name
`email`	string	Contact email
`url`	string	Personal website or portfolio

posts

Array of blog post objects.

Field	Type	Description
`title`	string	Post title
`content`	string	Markdown content
`description`	string	Short summary for listings
`createdAt`	string	Date in YYYY-MM-DD format
`updatedAt`	string	Last updated date
`tags`	string[]	Array of tag names
`categories`	string[]	Array of category names
`type`	'ai' \| 'human'	Mark AI-generated posts
`slug`	string	Custom URL slug (auto-generated if omitted)

{
  "posts": [
    {
      "title": "My First Post",
      "content": "# Hello\n\nThis is my first post!",
      "description": "An introduction to my blog",
      "createdAt": "2025-01-20",
      "tags": ["intro", "welcome"],
      "categories": ["Meta"],
      "type": "human"
    }
  ]
}

pages

Array of static page objects (About, Contact, etc.).

Field	Type	Description
`title`	string	Page title
`content`	string	Markdown content
`slug`	string	Custom URL slug (auto-generated if omitted)

Complete Example

{
  "site": {
    "title": "Jane's Dev Blog",
    "description": "Thoughts on web development and design",
    "url": "https://janedoe.dev"
  },
  "basics": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "url": "https://janedoe.com"
  },
  "posts": [
    {
      "title": "Building with TypeScript",
      "content": "# TypeScript Best Practices\n\n...",
      "description": "Tips for writing better TypeScript",
      "createdAt": "2025-01-15",
      "tags": ["typescript", "javascript"],
      "categories": ["Development"]
    },
    {
      "title": "AI-Generated Weekly Summary",
      "content": "# This Week in Tech\n\n...",
      "type": "ai",
      "createdAt": "2025-01-20"
    }
  ],
  "pages": [
    {
      "title": "About",
      "content": "# About Me\n\nI'm a web developer..."
    }
  ]
}

Validation

The @jsonblog/schema package provides validation using JSON Schema and Zod.

npm install @jsonblog/schema