JSON Resume: Open Standard for Developer CVs — Structure & Themes

Schema Structure: 10 Sections

The JSON Resume schema defines 10 top-level sections, all of which except basics are optional arrays. Understanding the structure before writing your first resume.json saves time — field names are case-sensitive, and a typo like startdate instead of startDate silently produces a blank field in rendered output. Use JSON syntax rules as a foundation since every field name and string value must be double-quoted.

The 10 sections are: basics (personal info, location, profiles), work (array of jobs with name, position, url, startDate, endDate, summary, highlights), volunteer (same shape as work), education (institution, area, studyType, startDate, endDate, score, courses), awards, certificates, publications, skills (name, level, keywords), languages, and references. An unofficial projects section is also supported by most themes. Dates use YYYY-MM (e.g., "2023-06"); omit endDate for current roles to display "Present" in rendered output.

Here is a minimal JSON Resume with basics and 1 work entry — valid against the official schema and renderable by any theme:

{
  "basics": {
    "name": "Alice Smith",
    "label": "Software Engineer",
    "email": "alice@example.com",
    "phone": "+1-555-0100",
    "url": "https://alice.dev",
    "summary": "Full-stack engineer with 5 years building web APIs and React UIs.",
    "location": {
      "city": "San Francisco",
      "countryCode": "US"
    }
  },
  "work": [
    {
      "name": "Acme Corp",
      "position": "Senior Software Engineer",
      "url": "https://acme.com",
      "startDate": "2021-03",
      "summary": "Led backend API development for a SaaS platform serving 50k users.",
      "highlights": [
        "Reduced API p99 latency from 800 ms to 120 ms by adding Redis caching",
        "Migrated monolith to 6 microservices, cutting deploy time by 70%"
      ]
    }
  ],
  "skills": [
    {
      "name": "JavaScript",
      "level": "Master",
      "keywords": ["Node.js", "React", "TypeScript"]
    }
  ]
}

All sections except basics are optional arrays — omitting a section entirely is valid. The schema uses JSON Schema Draft 4 for validation. Run resume validate to check your file before exporting.

The basics Section

The basics section is the only section with a required field: name (string). In practice every useful resume also includes email and label (your job title). The complete set of common fields covers 8 properties: name, label, image (headshot URL), email, phone, url (personal site), summary (2–3 sentence bio), and nested objects location and profiles.

The location object has 5 sub-fields: address, postalCode, city, countryCode (ISO 3166-1 alpha-2, e.g., "US", "GB"), and region (state/province). For privacy, most people only include city and countryCode. The profiles array holds social network links — each entry has 3 fields: network (display name), username, and url. Here is a complete basics object with 3 social profiles:

{
  "basics": {
    "name": "Alice Smith",
    "label": "Full-Stack Software Engineer",
    "image": "https://alice.dev/avatar.jpg",
    "email": "alice@example.com",
    "phone": "+1-555-0100",
    "url": "https://alice.dev",
    "summary": "Full-stack engineer with 5 years of experience in Node.js and React. Open-source contributor and conference speaker.",
    "location": {
      "city": "San Francisco",
      "countryCode": "US",
      "region": "California"
    },
    "profiles": [
      {
        "network": "LinkedIn",
        "username": "alicesmith",
        "url": "https://linkedin.com/in/alicesmith"
      },
      {
        "network": "GitHub",
        "username": "alicesmith",
        "url": "https://github.com/alicesmith"
      },
      {
        "network": "Twitter",
        "username": "alicesmith",
        "url": "https://twitter.com/alicesmith"
      }
    ]
  }
}

The image field accepts any publicly accessible image URL for a headshot — it is optional and some themes display it prominently while others ignore it. The summary is a plain string (no HTML); keep it to 2–3 sentences. Themes render the profiles array as social icons or links in the header. Country codes must be exactly 2 uppercase letters per ISO 3166-1 alpha-2. Validate the entire file with validate JSON tools before sharing.

work, education, and skills

These 3 sections form the body of most resumes and account for roughly 80% of the content recruiters scan. Each is a JSON array — the order of entries within an array determines the display order (most recent first is the convention). The work section alone has 7 fields per entry; mastering the field names avoids the most common validation errors.

work array: each entry has name (company name), position (job title), url (company website), startDate, endDate (omit for current role), summary (1-2 sentence description), and highlights (array of achievement strings). Here is a work entry with 3 highlights:

{
  "work": [
    {
      "name": "Stripe",
      "position": "Senior Backend Engineer",
      "url": "https://stripe.com",
      "startDate": "2022-01",
      "summary": "Designed and maintained payment processing microservices handling 2M transactions per day.",
      "highlights": [
        "Reduced checkout latency by 35% by introducing async processing for fraud checks",
        "Led migration of 3 legacy services to gRPC, cutting inter-service payload size by 60%",
        "Mentored 4 junior engineers through bi-weekly code reviews and pair programming sessions"
      ]
    },
    {
      "name": "Acme Corp",
      "position": "Software Engineer",
      "url": "https://acme.com",
      "startDate": "2019-06",
      "endDate": "2021-12",
      "summary": "Built REST APIs and React dashboards for an e-commerce SaaS platform.",
      "highlights": [
        "Shipped the order tracking feature used by 20k daily active users"
      ]
    }
  ]
}

education array: fields are institution, area (major/field of study), studyType (BS, MS, PhD, etc.), startDate, endDate, score (GPA or grade), and courses (array of course names). All fields are optional except by convention institution and area are always included.

skills array: each entry has name (e.g., "JavaScript"), level ("Master" / "Senior" / "Intermediate" / "Beginner" — free-form string), and keywords (array of specific tools or subtopics). Themes typically render skills as a tag cloud or grouped list. Keep each keywords array to 5–8 items for clean rendering across all themes. See JSON date formats for the full rules on YYYY-MM partial date strings used in startDate and endDate.

resume-cli: Build and Export

The resume-cli npm package is the official command-line tool for JSON Resume. It provides 4 core commands: validate, serve, export, and init. Install it globally once and use it across all projects. The CLI reads resume.json from the current directory by default; pass a different path with --resume path/to/file.json.

# Install resume-cli globally
npm install -g resume-cli

# Create a blank resume.json in the current directory
resume init

# Validate resume.json against the official JSON Schema
resume validate
# → "Resume validated successfully"  (or lists schema errors)

# Start a local preview server with live reload (default: even theme)
resume serve
# → Preview at http://localhost:4000

# Preview with a specific theme
resume serve --theme kendall

# Export to HTML
resume export resume.html

# Export to HTML with a specific theme
resume export --theme elegant resume.html

# Export to PDF (requires Chrome or Puppeteer)
resume export resume.pdf

# Export to PDF with a specific theme
resume export --theme stackoverflow resume.pdf

PDF export requires a headless Chrome installation. If Chrome is not found, install Puppeteer: npm install -g puppeteer. The CLI uses Puppeteer to render the HTML theme in a headless browser and print to PDF, producing pixel-accurate output that matches the browser preview. For CI/CD pipelines, pass --format pdf and ensure a headless Chrome binary is available in the environment (e.g., via the puppeteer or chrome-aws-lambda packages).

The resume validate command checks your file against the official JSON Schema (Draft 4). It catches 3 classes of errors: missing required fields (only basics.name is truly required), wrong field types (e.g., a string where an array is expected), and malformed date strings. Always run resume validate before exporting — a blank section in the rendered output almost always means a typo in a field name. Use validate JSON tools to check raw JSON syntax first if the CLI reports parse errors.

Themes and GitHub Gist Hosting

Over 30 official themes are available on npm, all following the naming convention jsonresume-theme-*. Browse them at npm search jsonresume-theme or at the npm registry search. Each theme is a standalone npm package that exports a render(resume) function that returns an HTML string. The 4 most popular themes are: even (clean 2-column layout, the registry default), stackoverflow (Stack Overflow developer story style), kendall (classic single-column serif), and elegant (minimal serif with strong typography). Install and preview any theme in 2 commands:

# Install a theme globally
npm install -g jsonresume-theme-even

# Preview with that theme
resume serve --theme even

# Or export directly
resume export --theme even resume.html

GitHub Gist hosting is the easiest way to publish a JSON Resume online for free. The workflow has 3 steps: (1) go to gist.github.com and create a new public Gist named exactly resume.json; (2) paste your resume JSON into the editor and save; (3) visit registry.jsonresume.org/<your-github-username> — the registry automatically fetches your Gist and renders it with the even theme. Append ?theme=kendall to the URL to switch themes without changing the Gist. The registry supports all 30+ npm themes via the query parameter.

Gist hosting has 3 advantages over self-hosting: automatic HTTPS via GitHub's CDN, full revision history (every Gist save is a git commit), and zero infrastructure. Changes to the Gist are reflected on the registry URL immediately with no cache invalidation needed. For a custom domain, set up a redirect from your personal site to the registry URL. Validate your JSON before pushing — use validate JSON to confirm the file is well-formed before saving the Gist.

Key terms

JSON Resume

An open standard created in 2013 that defines a JSON schema for expressing a curriculum vitae as a structured, machine-readable document renderable via themes.

basics

The first and only non-array top-level section in JSON Resume, containing personal information including name (the only required field), email, phone, url, summary, location, and profiles.

resume-cli

The official npm command-line tool for JSON Resume that provides validate, serve, export, and init commands for working with resume.json files locally.

jsonresume-theme-*

The npm package naming convention for JSON Resume themes; over 30 themes exist, each exporting a render function that converts a resume JSON object into an HTML string.

registry.jsonresume.org

The official JSON Resume registry that fetches a public GitHub Gist named resume.json for a given GitHub username and renders it as a themed HTML page.

ISO 8601 partial date

A date format used by JSON Resume for startDate and endDate fields, accepting YYYY-MM-DD, YYYY-MM, or YYYY — without time components or timezone offsets.

highlights

An array of strings within each work entry in JSON Resume, intended for bullet-point achievements; themes typically render these as a bulleted list under the job summary.

Frequently asked questions

What is JSON Resume?

JSON Resume is an open standard (schema + tooling) for expressing a CV as a JSON document. The schema defines 10 sections including basics, work experience, education, and skills. It is machine-readable, version-controllable with git, and renderable into HTML/PDF via 30+ themes. Created in 2013 by Thomas Davis, it is maintained at jsonresume.org. The resume-cli npm package validates and exports a resume.json file with a single command. GitHub Gist hosting lets you publish your resume for free at registry.jsonresume.org/your-github-username. The official JSON Schema validation (Draft 4) is available at the jsonresume GitHub repository. Only basics.name is technically required by the schema, but a useful resume includes at minimum basics with name and email.

What format do dates use in JSON Resume?

JSON Resume dates use ISO 8601 partial dates: YYYY-MM-DD (e.g., "2023-06-15") or YYYY-MM (e.g., "2023-06"). Year-only "2023" also works for education entries. Omit endDate for a current role — the resume renderer will display "Present". Do not use full ISO timestamps with time components such as "2023-06-15T00:00:00Z". The YYYY-MM format is the most common choice for work and education entries since exact day precision is rarely needed on a resume. See JSON date formats for the broader context of how dates are handled in JSON documents and APIs.

How do I convert my JSON Resume to a PDF?

Install resume-cli: npm install -g resume-cli. Run resume export my-resume.pdf — this requires Chrome or Puppeteer installed on the system. Or run resume export --theme elegant my-resume.html for an HTML file. Alternatively, use resume serve to preview in a browser and use the browser's Print → Save as PDF function. To use a specific theme for export, install it first: npm install -g jsonresume-theme-elegant, then run resume export --theme elegant my-resume.pdf. The resume-cli reads resume.json from the current directory by default. Run resume validate first to catch any JSON Schema validation errors before exporting.

How do I host my JSON Resume online for free?

Create a public GitHub Gist named exactly resume.json, paste your resume JSON into it, and save it. Then visit https://registry.jsonresume.org/your-github-username — the registry automatically fetches and renders your Gist. Append ?theme=theme-name to the URL to change themes, for example ?theme=kendall or ?theme=stackoverflow. The default theme is even. This approach gives you a live URL you can share on job applications, a version-controlled resume (Gist has full revision history), and free HTTPS hosting with no server to maintain. Updates to the Gist are reflected on the registry URL immediately with no redeployment needed.

Is there a JSON Schema for validating a JSON Resume?

Yes. The official schema is at https://raw.githubusercontent.com/jsonresume/resume-schema/master/schema.json. Validate with resume validate (resume-cli) or use ajv validate -s schema.json -d resume.json from the command line. The schema uses JSON Schema Draft 4. You can also validate online by loading the schema URL into any JSON Schema validator tool. The schema documents all required and optional fields, their types, and allowed formats for date strings. Running resume validate before exporting is a best practice — it catches typos in field names (e.g., "startdate" instead of "startDate") that would otherwise silently produce a blank field in rendered output.

What sections are required in JSON Resume?

Technically only basics.name is validated as required by the official JSON Schema, but basics itself (with name and email at minimum) is expected for any useful resume. All other 9 sections — work, volunteer, education, awards, certificates, publications, skills, languages, and references — are optional arrays. A valid minimal JSON Resume is just {"basics":{"name":"Alice"}}. In practice, most resumes include basics, work, education, and skills at minimum. The projects section is not in the official schema but is widely supported by themes as an unofficial extension. Omitting an entire section (e.g., no volunteer array at all) is valid and produces no output for that section in the rendered resume.