Content Schema System

Norgolith content schemas system allows you to define and enforce structure and validation rules for your Norg documents’ metadata. This ensures consistency across your content and prevents errors during the build process.

Why Use Content Schemas?

Content schemas are particularly useful for:

• Enforcing consistency: Ensure all posts have required fields like title, author, or publish_date.

• Preventing errors: Catch missing or invalid metadata before building your site.

• Conditional logic: Require specific fields based on other metadata (e.g., require hero_image if featured = true).

• Team collaboration: Provide clear guidelines for content contributors.

Schema Basics

Content schemas are defined in your norgolith.toml file under the [content_schema] section. A schema consists of:

• Required fields: Fields that must be present in the metadata.

• Field definitions: Rules for validating individual fields.

• Validation rules: Conditional logic for enforcing additional constraints.

Example: Basic Schema

[content_schema]
required = ["title", "author"]

[content_schema.fields.title]
type = "string"
max_length = 120

[content_schema.fields.author]
type = "string"

Field Types

Norgolith supports several field types, each with its own validation rules:

String

• Validates text fields.

Options

• max_length: Maximum allowed characters.

• pattern: Regex pattern for validation.

Example

[content_schema.fields.title]
type = "string"
max_length = 100
pattern = "^[A-Z].*"  # Must start with uppercase letter

Boolean

• Validates true or false values.

Example

[content_schema.fields.draft]
type = "boolean"

Array

• Validates lists of items.

Options

• items: Schema for individual items.

• min_items: Minimum number of items.

• max_items: Maximum number of items.

• must_contain: Specific values that must be present.

Example

[content_schema.fields.categories]
type = "array"
items = { type = "string" }
min_items = 1
max_items = 5
must_contain = ["norgolith"]

Object

• Validates nested metadata structures.

Options

• schema: Nested metadata structure schema.

Example

[content_schema.fields.author]
type = "object"
schema = { name = { type = "string" }, email = { type = "string" } }

Validation Rules

Validation rules allow you to enforce conditional logic based on metadata values.

Example: Conditional Rule

[content_schema.posts.rules]
if = { draft = false }  # Condition
then = { required = ["publish_date"] }  # Action

This rule ensures that if draft is false, the publish_date field must be present in any posts/ file.

Schema Inheritance

Schemas can inherit and extend rules based on content paths. For example, rules for /posts can extend global rules, and /posts/2023 can further extend /posts.

Example: Path-Based Inheritance

# Global rules
[content_schema]
required = ["title"]

# Rules for /posts
[content_schema.posts]
required = ["category"]

# Rules for /posts/2023
[content_schema.posts.2023]
required = ["year"]

In this example:

• All content requires a title field.

• Posts require a category field.

• Posts in /posts/2023 require a year field.

Practical Examples

Example 1: Blog Post Schema

[content_schema]
required = ["title", "author"]

[content_schema.fields.title]
type = "string"
max_length = 120

[content_schema.fields.author]
type = "string"

[content_schema.posts.rules]
if = { draft = false }
then = { required = ["publish_date"] }

Example 2: Project Documentation Schema

[content_schema]
required = ["title", "version"]

[content_schema.fields.title]
type = "string"

[content_schema.fields.project_version]
type = "string"
pattern = '^\d+\.\d+\.\d+$'  # Semantic versioning

[content_schema.docs.rules]
if = { status = "published" }
then = { required = ["reviewer"] }

Troubleshooting Validation Errors

Norgolith will show you validation issues by default in the following format, either as errors when trying to build the site or as warnings during the development server:

11:58 AM 2025-03-01 ERROR Validation failed for '/home/amartin/Develop/Rust/norgolith/my-site/content/index.norg'
→ Schema applied: 'index'
→ Constraint violation for field 'title': Exceeds max length 12

Common Errors and Fixes

Missing Required Field

• Error: Missing field 'title'.

• Fix: Add the missing field to your metadata.

Type Mismatch

• Error: Type mismatch for field 'version': expected string, got number.

• Fix: Ensure the field value matches the expected type.

Constraint Violation

• Error: Constraint violation for field 'title': Exceeds max length 12.

• Fix: Shorten the field value to meet the constraint.

Rule Condition Failed

• Error: Rule condition failed: Missing condition field 'draft'.

• Fix: Add the required condition field or update the rule.