JSON Resume: the open standard for resume data

What JSON Resume is

JSON Resume defines a schema, an agreed list of fields and their structure, for the information a resume contains: your basic details, work history, education, skills, projects and more. The data lives in a file usually called resume.json. Themes and tools read that file and produce HTML, PDF or other formats.

The idea is the same one that made web development easier: separate content from presentation. Instead of copying text between word processor templates, you keep one canonical source and generate as many designs as you need. The project and its schema are open source and hosted at jsonresume.org.

How the schema is organised

A resume.json file is a single JSON object. Each top-level key is a section, and most sections are arrays of entries. All sections are optional, so you only include what applies to you.

• basics: name, label (your headline), image, email, phone, url, summary, location and an array of social profiles
• work: one entry per job with name (employer), position, url, startDate, endDate, summary and highlights
• education: institution, area, studyType, startDate, endDate, score and courses
• skills: name, level and a list of keywords for each skill group
• projects: name, description, highlights, keywords, startDate, endDate, url and roles
• volunteer, awards, certificates, publications, languages, interests and references
• meta: optional information about the file itself, such as version and last modified date

Dates and other details that trip people up

Dates use the ISO 8601 format: a full date like 2023-04-01, a year and month like 2023-04, or just a year like 2023. Leave endDate out of a current role rather than writing 'Present'; themes render a missing end date as present. Highlights are arrays of strings, one per bullet point, which keeps them easy to reorder.

Because the file is strict JSON, every key and string must use double quotes, and trailing commas are not allowed. If a tool refuses to import your file, paste it into a JSON validator first: a missing comma or quote is the most common cause. Validators that check against the official schema will also flag misspelled keys.

Why use JSON Resume

The main benefit is portability. Your resume becomes data you own, in a plain text format that any tool or script can read, rather than content locked inside a particular word processor or website.

Plain text also works well with version control. Developers often keep resume.json in a Git repository, which gives a full history of changes and makes it easy to create branches for different kinds of roles. Some people host the file publicly so websites and tools can render an always-current resume from it.

• Write once, then switch designs without retyping anything
• Move between resume tools without losing structure
• Track changes and keep tailored versions with Git
• Generate a resume, portfolio and other documents from the same source

Creating and editing a resume.json file

You can write the file by hand in any code editor, starting from the sample resume in the official schema repository. Editors such as VS Code can validate the file against the published JSON schema as you type, which catches mistakes immediately.

If you would rather not edit JSON directly, use a builder that imports and exports the format. You edit in a normal form, and the tool keeps the structure valid. The official command-line tool, resume-cli, can also validate a file and export it to HTML or PDF with a chosen theme, although community themes vary in quality and maintenance.

Importing and exporting with Portfolio OS

Portfolio OS imports JSON Resume files directly into Resume Studio, mapping basics, work, education, skills, projects and other sections onto its own fields. From there you can apply any of its 12 resume templates, run ATS checks, and export to PDF, Word (DOCX), plain text or back to JSON. It runs free in the browser with no sign-up, and the file is processed on your device rather than uploaded.

Whatever tool you use, keep resume.json as your master copy. When you finish a tailored version for an application, export it back to JSON as well so the structured data stays in sync with the PDF you sent.

Limitations to know about

JSON Resume describes content, not layout, so very specific design choices like custom section names or unusual ordering depend on the theme or tool that renders it. Tools also support the schema to different degrees, so lesser-used sections such as references or interests may not appear in every template. Check the output before sending it, and keep custom fields to a minimum if you want maximum compatibility.

Frequently asked questions