Content Schemas

Schemas define the JSON structure that AI fills to produce validated, consistent pages.

What Is a Content Schema?

A content schema is a JSON structure definition that tells the AI exactly what to generate for each page. Instead of producing free-form prose, the AI fills in a structured JSON object with specific fields, item counts, and validation constraints. The renderer then transforms this JSON into HTML using a template.

This approach ensures:

• Consistency — Every page follows the same structure within a collection
• Validation — Output is checked against strict rules (item counts, string lengths, required fields)
• Deterministic titles — Page titles follow a pattern, never AI-improvised
• Predictable rendering — Each schema has a matched renderer that knows the field layout

The 10 Built-in Schemas

Schema	Title Pattern	Traffic Potential	Renderer
Idea List	{count} {subtopic} Ideas for {year}	High	idea-list
Comparison	{toolA} vs {toolB}: Which {subtopic} Tool Is Better?	High	comparison
How-To Guide	How to {action} with {subtopic} in {year}	High	how-to
Best-Of Roundup	{count} Best {subtopic} Tools in {year}	Very High	best-of
Beginner Guide	{subtopic} for Beginners: A Complete Guide ({year})	Medium	beginner-guide
Checklist	The Ultimate {subtopic} Checklist ({count} Items)	Medium	checklist
FAQ	{count} Common {subtopic} Questions Answered	Medium	faq
Alternatives	{count} Best {tool} Alternatives in {year}	High	alternatives
Statistics	{count} {subtopic} Statistics You Should Know ({year})	Medium	statistics
Use Cases	{count} {subtopic} Use Cases for {audience}	Medium	use-cases

Schema Structure

Each schema record has these key fields:

Field	Type	Description
SchemaJson	jsonb	The JSON structure definition that the AI must fill
PromptTemplate	text	The prompt template sent to the AI, with {niche}, {subtopic}, {schema} placeholders
TitlePattern	varchar	Deterministic title template (e.g., "{count} Best {subtopic} Tools in {year}")
MetaDescPattern	varchar	Meta description template with the same token syntax
RendererSlug	varchar	The slug of the HTML renderer that transforms the JSON to a page

Schema Validation Rules

After the AI generates JSON content, it is validated against the schema's rules before publishing. Validation ensures quality and catches hallucinated or malformed output.

Rule	Example	Failure Behavior
Exact item count	Schema says "items": 10, AI must produce exactly 10	Rejected
String min/max length	"description": { "minLength": 50, "maxLength": 300 }	Rejected
Enum values	"difficulty": ["easy", "medium", "hard"]	Rejected
Required fields	"required": ["title", "description", "items"]	Rejected
JSON parse	Output must be valid JSON	Retry (1 attempt)

When validation fails, the generator retries once with an adjusted prompt. If the second attempt also fails, the page is marked as failed and logged for manual review.

Creating a Custom Schema

# List schemas
contento schemas list

# View schema details in JSON
contento schemas list --json

# Example schema definition:
{
    "name": "Idea List",
    "slug": "idea-list",
    "titlePattern": "{count} {subtopic} Ideas for {year}",
    "metaDescPattern": "Discover {count} actionable {subtopic} ideas for {year}. Curated for {audience}.",
    "rendererSlug": "idea-list",
    "promptTemplate": "Generate a JSON object with exactly {count} creative, actionable ideas about {subtopic} for the {niche} audience. Each idea must have a title (5-12 words), description (50-200 chars), and difficulty (easy/medium/hard). Return ONLY valid JSON matching this schema: {schema}",
    "schemaJson": {
      "type": "object",
      "required": ["intro", "items", "conclusion"],
      "properties": {
        "intro": {
          "type": "string",
          "minLength": 100,
          "maxLength": 500,
          "description": "Engaging introduction paragraph"
        },
        "items": {
          "type": "array",
          "exactCount": 10,
          "items": {
            "type": "object",
            "required": ["title", "description", "difficulty"],
            "properties": {
              "title": { "type": "string", "minLength": 20, "maxLength": 80 },
              "description": { "type": "string", "minLength": 50, "maxLength": 200 },
              "difficulty": { "type": "string", "enum": ["easy", "medium", "hard"] }
            }
          }
        },
        "conclusion": {
          "type": "string",
          "minLength": 80,
          "maxLength": 400,
          "description": "Wrap-up paragraph with next steps"
        }
      }
    }
  }

How AI Uses the Schema

The generation prompt is assembled from three pieces:

1. Niche context — Audience, pain points, monetization model (from the niche)
2. Prompt template — The schema's PromptTemplate with tokens replaced
3. Schema JSON — The SchemaJson is serialized and included so the AI knows the exact structure to produce

The AI receives a single prompt that combines all three, returns JSON, and the validator checks it against the schema rules. This architecture means the AI never decides the page structure — it only fills in the content within a pre-defined shape.

CLI Commands

Command	Description
contento schemas list	List all schemas
contento schemas list --json	List schemas with full JSON structure

See the CLI reference for all available flags and options.