references/persona-schema.md

Persona JSON Schema

This document defines the JSON schema for personas used in Persona Research virtual surveys. The schema is based on the TinyPerson format from the PyData demo, ensuring compatibility with existing persona libraries.

Schema

{
  "persona": {
    "name": "string (required) — Full name",
    "age": "integer (required) — Age in years",
    "nationality": "string (required) — e.g. 'American', 'Japanese-American'",
    "occupation": {
      "title": "string (required) — Job title",
      "organization": "string (required) — Employer or context",
      "description": "string (required) — What they do day-to-day (2-4 sentences)"
    },
    "gender": "string (required) — e.g. 'Male', 'Female', 'Non-binary'",
    "residence": "string (required) — City, Region (US: 'City, State'; Japan: 'City, Prefecture'; UK: 'City, Country')",
    "education": "string (required) — Narrative description of educational background",
    "long_term_goals": ["string — 3-5 life goals"],
    "style": "string (required) — Communication style, appearance, mannerisms (3-5 sentences). THIS FIELD DRIVES RESPONSE TONE.",
    "personality": {
      "traits": ["string — 5-8 personality descriptions"],
      "big_five": {
        "openness": "float 0.0-1.0",
        "conscientiousness": "float 0.0-1.0",
        "extraversion": "float 0.0-1.0",
        "agreeableness": "float 0.0-1.0",
        "neuroticism": "float 0.0-1.0"
      }
    },
    "preferences": {
      "interests": ["string — 5-10 interests"],
      "likes": ["string — 5-10 things they enjoy"],
      "dislikes": ["string — 5-10 things they avoid"]
    },
    "beliefs": ["string — 3-5 core beliefs or values"],
    "skills": ["string — 3-5 relevant skills"],
    "behaviors": {
      "general": ["string — 3-5 typical behaviors"],
      "routines": {
        "morning": ["string"],
        "workday": ["string"],
        "evening": ["string"],
        "weekend": ["string"]
      }
    },
    "health": {
      "physical": "string — Physical health summary",
      "mental": "string — Mental health summary"
    },
    "relationships": [
      {
        "name": "string",
        "relation": "string",
        "description": "string"
      }
    ]
  },
  "segment": "string (required) — Generic segment label for analysis (e.g. 'Daily Ritual Drinker', 'Early Adopter')",
  "segment_id": "integer (required) — Numeric segment identifier (1-based, matches segment order)"
}

Generation Guidelines

What Makes a Good Persona for Virtual Surveys

Big Five personality is the primary driver of response variation:
- High openness → exploratory, willing to try new things
- High conscientiousness → detail-oriented, researches before buying
- High extraversion → enthusiastic, verbose responses
- High agreeableness → positive bias, avoids criticism
- High neuroticism → anxious about purchases, risk-averse
Style field controls expression quality:
- A laconic farmer writes differently than a verbose marketing exec
- Education level should match vocabulary complexity
- Cultural background influences communication patterns
Income/occupation drives price sensitivity:
- Don't state income directly — imply through occupation and lifestyle
- A nurse and a hedge fund manager react differently to $300 shoes
Diversity requirements (per panel of 15+):
- Age range: at least 3 decades represented (e.g., 20s, 40s, 60s+)
- Gender: mixed
- Income: budget-conscious to affluent
- Geography: urban, suburban, rural
- Ethnicity: representative mix
- Personality: mix of Big Five profiles (not all agreeable/open)

Minimal vs Full Persona

Minimal (for quick surveys, ≤10 personas):

name, age, occupation.title, gender, residence, style
personality.big_five (numeric scores)
2-3 key preferences/interests relevant to the survey topic

Full (for rich simulations, reusable library):

All fields populated as in the schema above
Detailed style, behaviors, and routines
10+ interests, likes, dislikes each

Segment-Driven Generation

When generating personas from segment definitions:

{
  "segments": [
    {
      "name": "Serious Runner",
      "count": 10,
      "description": "Runs 30+ miles/week, values performance...",
      "demographic_priors": {
        "age_range": [25, 55],
        "income_signal": "moderate to high",
        "fitness_level": "high"
      }
    }
  ]
}

Each persona within a segment should vary — they share the segment's core trait but differ in age, personality, background, and priorities.

Segment Field Convention

The segment field is used for all analysis (cross-tabs, charts, comparisons). Its meaning depends on the generation mode:

Segment-driven mode (--segments): Shared segment label for grouping. Multiple personas share the same segment name.

Good: "Daily Ritual Drinker", "Early Adopter", "Budget-Conscious Parent"
Avoid: "Segment A", "Group 1" (not descriptive)

Topic-only mode (default): Per-persona archetype label — each persona gets a unique 2-4 word label describing their relationship to the topic.

Good: "Budget Pragmatist", "Health-Focused Explorer", "Skeptical Minimalist"
Avoid: Generic labels that don't convey persona character
Format: Adjective + Noun pattern preferred
When unique labels are used, analysis produces persona comparison tables instead of segment cross-tabulations.

Deprecated: Topic-specific field names like runner_type, coffee_preference, etc. should NOT be used. All segment grouping must go through the standard segment field. Legacy personas with runner_type or similar fields remain valid but the segment field takes precedence for analysis.

Persona Storage

Personas are stored in per-survey subdirectories:

personas/
├── _archive/                  # Archived panels (ignored by auto-detection)
│   └── shoes-demo-2025/       # Legacy shoe demo personas
├── {survey-id}/               # Active panels
│   ├── manifest.json          # topic, category, segments, count, created
│   └── {Name_Underscored}.json

Each manifest.json identifies the panel's topic and segments, enabling automatic reuse detection across surveys.

On this page