JSON Resume - Store Your Resume as Data, Not Documents

Currently viewing the human version

Why JSON Resume Exists (And Why You Might Want It)

I switched jobs in March 2024 and spent an entire weekend updating my resume everywhere - LinkedIn, my company bio, personal site, plus like 6 other places I'd forgotten about. Same fucking data, different formats every time. JSON Resume fixes this by letting you write your resume once as structured data, then generate whatever format you need.

JSON Resume Template Example

The Real Problem It Solves

You know the drill: you land a new gig, update your LinkedIn, then remember your company website needs updating, then your PDF resume is out of date, then your personal site... JSON Resume makes this suck less. Write your career history once in a standardized JSON format, then generate HTML, PDF, Word docs, or whatever else you need.

There's this schema thing that covers the usual resume stuff - work history, education, skills, whatever. Here's what a basic JSON resume looks like:

{
  "basics": {
    "name": "Jane Developer",
    "label": "Full Stack Engineer",
    "email": "jane@example.com",
    "phone": "(555) 123-4567",
    "url": "https://janedev.com",
    "summary": "I debug production issues at 3am and somehow still love this job"
  },
  "work": [{
    "name": "TechCorp",
    "position": "Senior Engineer",
    "startDate": "2023-01-15",
    "endDate": "2024-12-01",
    "summary": "Built some microservices, they broke constantly"
  }],
  "skills": [{
    "name": "Backend",
    "keywords": ["Node.js", "Python", "Docker", "PostgreSQL"]
  }]
}

What Actually Works Well

Version Control: Your resume becomes part of your development workflow. I keep mine in Git alongside my dotfiles - when I change jobs, it's a simple commit and push. Branch for different roles, merge when you land something.

Theme Swapping: There are tons of themes but most are garbage. Maybe 20 actually work without breaking on real data. The elegant theme and stackoverflow theme are solid choices.

Automated Generation: Set up a GitHub Action to regenerate your resume whenever you push changes. Deploy to GitHub Pages, update your PDF automatically, sync to your portfolio site.

ATS Compatibility: JSON resumes export to clean HTML/PDF that actually parses correctly in applicant tracking systems. No more wondering if your fancy formatting broke the parser.

The Parts That Kinda Suck

Setup Complexity: You need Node.js, understand JSON syntax, and be comfortable with command-line tools. The resume-cli works but assumes you know what you're doing.

Theme Quality: Most themes haven't been updated since 2019. The ones that work often break when you use real data instead of the sample data. Pro tip: test themes with your actual content before committing.

JSON Syntax Hell: One missing comma and everything dies. Spent like 3 hours debugging why my education section vanished - turns out the elegant theme wanted an array but I had a single object. The error? "ValidationError: child 'education' fails" - super fucking helpful, right?

JSON Document Structure

Export Limitations: PDF generation is hit-or-miss depending on your theme and data. Some themes generate gorgeous HTML but terrible PDFs. You'll end up manually tweaking CSS for print styles.

This tool makes sense if you're a developer who already lives in JSON/Git/CLI world. If you just need to update a resume twice a year, stick with Google Docs or Canva. JSON Resume is infrastructure for people who treat their career data like code.

Actually Setting This Thing Up (And What Will Go Wrong)

Installation: The Easy Part

Install the resume-cli globally. You need Node.js installed (obviously):

npm install -g resume-cli

If you hit permission errors on macOS/Linux (EACCES: permission denied), either fix your npm permissions or use nvm like a civilized person. On Windows, newer Node versions sometimes break the CLI - if it crashes, try Node 16.x or just use WSL2.

There's also resumed which is a modern rewrite, but the original CLI is fine for most people. Don't overthink it.

JSON Editor Interface

Creating Your First Resume: The Fun Begins

Generate a starter file:

resume init

This creates resume.json with sample data. The generated file is complete garbage - delete everything and start with someone else's real resume as a template. Trust me, it's faster than fighting with the schema documentation.

The official schema has the usual stuff - name, email, job history, education, skills. Plus some optional crap like volunteer work and interests that nobody reads anyway.

Validation: Where Things Break

Test your JSON syntax:

resume validate

This catches basic JSON errors but won't help with the logical problems. Common fuckups:

Trailing commas: \"skills\": [\"JavaScript\", \"Python\",] breaks everything
Date formats: Use YYYY-MM-DD format or shit breaks
Missing required fields: Some themes break if you don't have certain fields
Unicode characters: Fancy quotes from copy-pasting will break validation

JSON Schema Validation Error

The error messages are fucking useless. Spent 2 hours last week debugging what turned out to be a missing comma. Use jsonlint.com or get a JSON linter in your editor before you lose your mind.

Theme Hunting: The Disappointment Phase

Browse available themes and prepare for disappointment. Most haven't been updated since Obama was president - seriously, check the commit dates. The 'modern' theme's last commit was 2019. Here's what actually works in 2024:

elegant: Clean, professional. Works with real data.

stackoverflow: Familiar design for developers.

kendall: Modern, good for tech roles.

StackOverflow Theme Preview

Test themes locally:

resume serve --theme elegant

This starts a dev server at http://localhost:4000. The theme looks great until you use your actual data and everything breaks.

Export Reality Check

Generate different formats:

resume export resume.pdf --theme elegant
resume export resume.html --theme elegant
resume export resume.docx --theme elegant

JSON Resume to PDF Workflow

PDF Export Issues:

Print styles are often broken or missing
Fonts don't match the HTML version
Page breaks happen in weird places
Some themes generate 20-page PDFs from 2 pages of data

HTML Export: Usually works fine, but check mobile responsiveness

Word Export: Exists but the formatting is fucked - bullet points become weird Unicode chars, margins disappear. Use HTML and convert through Google Docs if you absolutely need .docx

Hosting Options That Don't Suck

GitHub Gist Method: Create a public gist named resume.json, get automatic hosting at registry.jsonresume.org/yourusername. Works but you're stuck with their default theme.

Self-Hosting: Generate HTML and upload to Netlify, Vercel, or GitHub Pages. More control but you handle the deployment.

Hosting Platform Comparison

GitHub Actions: Set up automated builds to regenerate your resume on every push. Overkill but satisfying.

Integration With Your Actual Workflow

Keep your resume.json in a private GitHub repo with your dotfiles. When you change jobs:

Update the JSON file
Commit and push
Regenerate exports
Update your portfolio site
Send recruiters the PDF version because they don't know what JSON is

The whole point is updating once and generating multiple formats. If you're manually editing different versions, you're doing it wrong.

JSON Resume vs The Rest (Honest Comparison)

Feature	JSON Resume	PDF Resume	Word Document	LinkedIn Profile
Setup Difficulty	🔴 Need Node.js + JSON skills	🟢 Open template, type	🟢 Open template, type	🟢 Fill out web form
Version Control	🟢 Git diffs work perfectly	🔴 Binary blobs, no diffs	🔴 Track Changes is garbage	🔴 No version history
Automation	🟢 CLI tools + GitHub Actions	🔴 Manual updates forever	🟡 Mail merge if you're lucky	🟡 API exists but limited
Multiple Formats	🟢 One JSON → many formats	🔴 Stuck with PDF	🟡 Export options vary	🔴 LinkedIn only
Theme Quality	🟡 Like 20 good themes, hundreds of broken ones	🔴 Start from scratch	🟢 Tons of templates	🔴 Can't customize much
ATS Compatibility	🟢 Clean HTML/PDF export	🟡 Hit-or-miss parsing	🟡 Depends on formatting	🟢 Integrates directly
Recruiter Acceptance	🔴 "What's a JSON?"	🟢 Everyone expects PDF	🟢 Standard format	🟢 Where recruiters live
Data Ownership	🟢 It's your file	🟢 It's your file	🟢 It's your file	🔴 LinkedIn owns everything
Collaboration	🟢 Pull requests work	🔴 Email versions around	🟢 Real-time editing	🔴 One person only
Error Detection	🟢 JSON validation catches bugs	🔴 Spell check only	🟡 Grammar suggestions	🔴 No validation
Mobile Editing	🔴 CLI tools don't work on phone	🔴 PDF editors suck on mobile	🟡 Office mobile apps exist	🟢 Mobile app works great
Privacy	🟢 Self-host or keep private	🟢 Send to who you want	🟢 Send to who you want	🔴 Public by default
Industry Standard	🔴 Only developers know this	🟢 Universal acceptance	🟢 HR departments love it	🟢 Required for job hunting
Time Investment	🔴 2-4 hours setup + learning	🟢 30 minutes	🟢 30 minutes	🟢 1 hour

Questions Developers Actually Ask

Do employers actually accept JSON resumes?

Hell no. 99% of companies want a PDF. JSON Resume is for generating PDFs and managing your data

not for submitting raw JSON to job applications. You'll get weird looks if you attach resume.json to an email. Export to PDF first.

How do I not accidentally commit my phone number to GitHub?

Keep sensitive info in a separate file or use environment variables. I learned this the hard way when my phone number got scraped by recruiters in 2023. Now I have resume-public.json and resume-private.json

the private one has my actual contact info, the public one on GitHub just has my email.

What if JSON Resume gets abandoned?

It's just a JSON file. Even if the entire project died tomorrow, your data is still readable and you could build your own tools in a weekend. The schema is on GitHub and it's simple enough that you could maintain it yourself. This is way better than being locked into a proprietary platform.

Can my designer friend use this?

Only if they're comfortable editing JSON by hand. There are visual JSON editors but honestly, most non-developers find the format intimidating. If your designer insists on using this, they'll probably ask you to update it anyway.

How do I use this with my React/Next.js/Vue site?

Import the JSON file directly:

import resume from './resume.json';

function About() {
  return (
    <div>
      <h1>{resume.basics.name}</h1>
      <p>{resume.basics.summary}</p>
    </div>
  );
}

For Jekyll or Hugo, drop the file in _data/ or data/ and access it in templates. For Gatsby, use gatsby-source-filesystem.

Why doesn't my theme look like the preview?

Because you have real data and the preview uses fake data. Most theme previews use perfect sample data with exactly the right amount of text. I switched to the elegant theme because the preview looked clean, then my 15 skills broke the layout completely and my summary wrapped weird. Test themes with your actual data before committing

save yourself the frustration.

Can I have different resumes for different jobs?

Yeah, but manage it properly.

I keep branches in Git: frontend-focus, backend-focus, devops-focus.

Or maintain separate files: resume-frontend.json, resume-backend.json. Don't manually edit 5 different files

that's the problem you're trying to solve.

Why does PDF export look like shit?

Because most themes don't have proper print styles. The elegant theme actually exports decent PDFs, but many others are HTML-only. Check the theme's GitHub repo for PDF issues before using it. Some themes generate 10-page PDFs from 1 page of content.

How do I back this up?

It's a text file. Put it in Dropbox, Google Drive, i

Cloud, whatever. The real backup is version control

keep it in a private Git repo and you have infinite history. I also export PDFs periodically and save them with timestamps as "point in time" snapshots.

The JSON syntax is breaking and I hate it

Use a proper editor with JSON validation.

VS Code, Sublime Text, even online tools like JSONLint. The most common error is trailing commas

JSON doesn't allow them but Java

Script does, so you get Unexpected token , errors. Install a JSON formatter/linter extension and save yourself hours of debugging invisible Unicode characters copy-pasted from LinkedIn.

Is this just over-engineering a simple problem?

Maybe. If you update your resume twice a year, just use Google Docs. JSON Resume makes sense if you're constantly updating your career info across multiple places (portfolio site, LinkedIn, PDF exports, team bios). The automation pays off if you use it regularly.