JSON Resume: AI-Optimized Technical Reference

Core Concept

JSON Resume: Store career data as JSON, generate multiple output formats (HTML, PDF, Word). Solves data duplication across LinkedIn, portfolio sites, and resume files.

Configuration

Working Setup Requirements

• Node.js: Required for resume-cli
• Command: npm install -g resume-cli
• Alternative: resumed package (modern rewrite, actively maintained)

Critical File Structure

{
  "basics": {
    "name": "string",
    "label": "string",
    "email": "string",
    "phone": "string",
    "url": "string",
    "summary": "string"
  },
  "work": [{
    "name": "string",
    "position": "string",
    "startDate": "YYYY-MM-DD",
    "endDate": "YYYY-MM-DD",
    "summary": "string"
  }],
  "skills": [{
    "name": "string",
    "keywords": ["array", "of", "strings"]
  }]
}

Production-Ready Themes (Only These Work Reliably)

• elegant: Clean, professional, good PDF export
• stackoverflow: Familiar design, mobile responsive
• kendall: Modern typography, handles long content
• paper: Minimal, well-maintained, proper PDF support

Theme Failure Rate: ~80% of available themes are broken/unmaintained since 2019

Resource Requirements

Time Investment

• Initial Setup: 2-4 hours (includes learning JSON syntax, debugging)
• Per-Update: 5-10 minutes once configured
• Theme Testing: 30-60 minutes per theme with real data

Expertise Requirements

• JSON syntax knowledge (critical - one missing comma breaks everything)
• Command-line comfort
• Git/version control understanding
• Basic Node.js troubleshooting

Skill Difficulty Comparison

• Easier than: Building custom resume templates from scratch
• Harder than: Google Docs/Canva resume editing
• Similar to: Managing configuration files for development tools

Critical Warnings

What Documentation Doesn't Tell You

JSON Syntax Failures:

• Trailing commas break validation: "skills": ["JavaScript", "Python",] = fatal error
• Date format must be YYYY-MM-DD or themes break
• Unicode characters from copy-paste cause invisible validation errors
• Error messages are useless: "ValidationError: child 'education' fails"

Theme Reality vs Previews:

• Previews use perfect sample data
• Real data with 15+ skills breaks most layouts
• PDF export often generates 20 pages from 2 pages of content
• Print styles missing or broken in most themes

Export Limitations:

• PDF generation hit-or-miss depending on theme
• Word export formatting corrupted (bullets become Unicode chars)
• Mobile responsiveness varies dramatically by theme

Breaking Points and Failure Modes

Will Break If:

• Node.js version incompatibility (try Node 16.x if CLI crashes)
• npm permissions not configured properly
• JSON contains any syntax errors
• Theme hasn't been updated for current schema version

Common Production Failures:

• UI breaks at 1000+ character summaries, making long career histories unreadable
• Date parsing fails with non-standard formats, causing entire work sections to disappear
• Skill arrays with 20+ items break most theme layouts completely

Decision Criteria

Use JSON Resume When:

• You're a developer comfortable with JSON/CLI tools
• You update career info across multiple platforms frequently
• You need version control for resume changes
• You want automated resume generation in CI/CD

Don't Use JSON Resume When:

• You update resume twice per year maximum
• You're not comfortable with command-line tools
• You need immediate PDF without technical setup
• Your audience expects traditional resume formats only

Cost-Benefit Analysis

Worth It Despite:

• 2-4 hour initial setup cost
• Theme quality lottery
• JSON syntax learning curve
• PDF export limitations

Hidden Costs:

• Theme debugging time (2-3 hours per broken theme)
• JSON syntax error hunting (common: 1-3 hours per error)
• PDF formatting fixes (manual CSS tweaking required)
• Node.js/npm environment maintenance

Implementation Reality

Actual vs Documented Behavior

• Documented: "Easy theme switching"

• Reality: Most themes break with real data, require testing and fixes

• Documented: "Clean PDF export"

• Reality: PDF formatting broken in 60%+ of themes

• Documented: "JSON validation catches errors"

• Reality: Validation catches syntax but not logical/theme compatibility issues

Working Production Settings

# Validation (catches basic errors only)
resume validate

# Local testing (essential before committing)
resume serve --theme elegant

# Export formats
resume export resume.pdf --theme elegant
resume export resume.html --theme elegant
# Skip Word export - formatting always broken

Integration Patterns That Work

1. Keep resume.json in private Git repo with dotfiles
2. Use separate files for public/private versions
3. GitHub Actions for automated builds
4. Export to multiple formats, distribute PDFs to recruiters
5. Import JSON directly in React/Vue portfolio sites

Migration Pain Points

• No migration path from Word/PDF to JSON (manual conversion required)
• Schema changes break older themes
• Theme abandonment requires theme switching and reformatting

Community and Support Quality

• Discord community: Active, faster than GitHub issues
• GitHub issues: Slow response, many unresolved theme problems
• Theme maintenance: Most themes abandoned, ~20 actively maintained
• Documentation: Outdated, missing real-world implementation details

Failure Recovery Strategies

• Use JSONLint.com for syntax debugging
• Test themes with actual data before committing
• Keep multiple export formats as backup
• Maintain separate public/private versions for security

Comparative Analysis

JSON Resume vs Traditional Approaches

Aspect	JSON Resume	PDF Resume	Word Document
Setup Effort	2-4 hours + learning	30 minutes	30 minutes
Update Frequency Efficiency	High (once → many formats)	Low (manual each time)	Low (manual each time)
Version Control	Excellent (Git diffs)	None (binary files)	Poor (track changes)
Automation Potential	High (CLI + CI/CD)	None	Limited (mail merge)
ATS Compatibility	Good (clean HTML/PDF)	Variable	Variable
Recruiter Acceptance	None (must export PDF)	Universal	Universal
Error Detection	Good (JSON validation)	None (spell check only)	Basic (grammar check)
Theme Quality	20 good / 200+ broken	Template dependent	Template dependent

Resource Investment ROI

• Break-even point: ~10 resume updates across multiple platforms
• High ROI scenarios: Frequent job changes, portfolio maintenance, team bio updates
• Negative ROI scenarios: Infrequent updates, non-technical users, PDF-only workflows