Analysis Output Format

All ChapterWise analysis modules produce structured JSON in the Codex V1.2 analysis format. This page is the canonical reference for the output schema.

Module Output Structure

Every module returns a JSON object with five fields:

{
  "body": "## Module Name\n\nMain analysis content in markdown...",
  "summary": "One-line summary of findings",
  "children": [
    {
      "name": "Section Name",
      "summary": "Section summary",
      "content": "## Section\n\nDetailed content...",
      "attributes": [
        {"key": "score", "name": "Score", "value": 8, "dataType": "int"}
      ]
    }
  ],
  "tags": ["analysis", "module-name"],
  "attributes": [
    {"key": "overall_score", "name": "Overall Score", "value": 7, "dataType": "int"}
  ]
}

Field Reference

Field Required Description
body Yes Main analysis content in markdown with ## headers
summary Yes 1-2 sentence overview of findings
children Yes Structured sub-sections (2-5 recommended)
tags Yes Relevant keywords for searchability
attributes Yes Scored metrics with dataType hint

Children Fields

Each child in the children array represents a sub-section of the analysis:

Field Description
name Display name for the section
summary Brief summary of the section
content Full markdown content for the section
attributes Array of typed key-value metrics

Attribute Structure

Each attribute contains:

Field Description
key Machine-readable identifier (snake_case)
name Human-readable display name (Title Case)
value The attribute value
dataType Type hint for rendering

Attribute Data Types

dataType Description Example
int Integer value {"key": "score", "value": 8, "dataType": "int"}
float Decimal value {"key": "ratio", "value": 0.75, "dataType": "float"}
string Text value {"key": "mood", "value": "tense", "dataType": "string"}
stringArray List of strings {"key": "themes", "value": ["love", "loss"], "dataType": "stringArray"}
boolean True/false {"key": "present", "value": true, "dataType": "boolean"}

Scoring Conventions

All integer scores use a 1-10 scale:

Score Meaning
1-2 Significant issues or absent
3-4 Below average, needs work
5 Competent, baseline
6 Above average
7 Good
8 Very good
9-10 Exceptional

Naming Conventions

Element Convention Example
Module IDs snake_case plot_holes, story_beats
Attribute keys snake_case word_count, overall_score
Display names Title Case Overall Score, Beat Count
Tags hyphenated-lowercase story-beats, character-arc

Codex Envelope

When analysis is saved, the module output gets wrapped in a full Codex V1.2 document structure:

{
  "metadata": {"formatVersion": "1.2", "created": "...", "updated": "..."},
  "id": "{basename}-analysis",
  "type": "analysis",
  "attributes": [
    {"key": "sourceFile", "value": "source.codex.yaml"},
    {"key": "sourceHash", "value": "16-char-sha256-hash"}
  ],
  "children": [
    {
      "id": "module_name",
      "type": "analysis-module",
      "name": "Module Display Name",
      "children": [
        {
          "id": "entry-YYYYMMDDTHHMMSSz",
          "type": "analysis-entry",
          "status": "published",
          "attributes": [
            {"key": "model", "value": "claude-sonnet-4"},
            {"key": "sourceHash", "value": "16-char-hash"},
            {"key": "analysisStatus", "value": "current"},
            {"key": "timestamp", "value": "ISO-8601"}
          ],
          "body": "YOUR body FIELD",
          "summary": "YOUR summary FIELD",
          "children": "YOUR children ARRAY",
          "tags": "YOUR tags ARRAY"
        }
      ]
    }
  ]
}

Each module's output becomes a child of the analysis document, and each run becomes an analysis-entry within that module.

Want to build your own modules? See Custom Modules.