Job search
JSON Resume Guide: Build a Portable Resume File and Export It for Applications
Build a structured resume.json, validate it, choose a theme, and export and inspect the application file without confusing a standard with an employer requirement.
title: "JSON Resume Guide: Build a Portable Resume File and Export It for Applications" description: "Build and validate a portable JSON Resume, choose a rendering theme, then inspect the exact PDF or other file an employer requests." slug: "json-resume-portable-file-export-applications" category: "Career Materials / Practical Guide" featuredImage: "hero.webp"
JSON Resume gives you a structured resume.json file that can be validated and rendered with compatible tools and themes. It can make it easier to keep resume content separate from presentation, but the JSON file is usually not the attachment you send to an employer. You still need to choose a theme, export the requested file type, and inspect the output.
Before you put your details into a hosted service, decide whether you want a public profile. The current JSON Resume Registry describes a GitHub Gist-based sharing flow. GitHub says secret Gists are not private: anyone who gets the URL can see them. If you do not intend to publish your contact and career information, start with a local file and local rendering workflow.
This guide covers the structure, validation, theme selection, privacy choices, and final file checks. We reviewed the current official JSON Resume and GitHub documentation on October 14, 2026. We did not upload personal data, create an account, or test an employer’s application system. For a role to tailor your resume toward, browse recent roles on LandOffer.ai.

Decide where the resume data will live
JSON Resume can be used in a local workflow or with a hosted registry. Those are different choices. A local file lets you work with a copy on your device; a hosted profile gives you a URL that can be shared, but requires you to understand the account and visibility settings first.
| Workflow | What you maintain | What to decide first |
|---|---|---|
| Local source and export | resume.json, a theme or renderer, and the exported file |
Where your file, backups, installed packages, and generated PDFs are stored |
| Hosted Registry profile | Your resume content connected to the hosted account or Gist flow and a shareable page | Whether the profile or underlying Gist is public, secret, or otherwise accessible by URL; what information you want visible |
| Both | One structured source plus a hosted view and application copies | Which copy is authoritative and how you will keep versions and visibility consistent |
The JSON Resume Registry homepage currently describes the service as connecting a GitHub Gist to a shareable resume URL. GitHub’s Gist documentation distinguishes public Gists, which appear in Discover and are searchable, from secret Gists, which are not searchable but are still visible to anyone who has the URL. GitHub also says you cannot convert a public Gist into a secret one. Do not treat a secret link as access-controlled storage.
If you use the hosted path, read the current product and GitHub visibility settings before authorizing access or sharing a link. Remove details you do not need to publish, such as a street address, personal phone number, or references’ contact information. If you need restricted access, use a storage option with the access controls you intend rather than relying on a hard-to-guess URL. A local source can still end up in a synced folder, backup service, or shared computer, so check those settings too.
What the schema does—and does not—decide
The JSON Resume schema describes fields such as basics, work, education, skills, projects, and languages. A validator can tell you whether your file is structurally consistent with that schema. The schema does not decide which sections belong on your resume, verify whether a statement is true, or determine what an employer requires.
A small source file can look like this:
{
"$schema": "https://raw.githubusercontent.com/jsonresume/resume-schema/master/schema.json",
"basics": {
"name": "Alex Example",
"label": "Software Engineer",
"email": "alex@example.com",
"url": "https://example.com"
},
"work": [
{
"name": "Example Systems",
"position": "Software Engineer",
"startDate": "2022-03",
"endDate": "2025-08",
"highlights": [
"Reduced a recurring batch job from 90 minutes to 22 minutes by replacing a serial step with bounded parallel workers."
]
}
],
"education": [
{
"institution": "Example State University",
"area": "Computer Science",
"studyType": "Bachelor's degree",
"endDate": "2021-05"
}
]
}
The example is fictional. It shows the shape, not a recommended set of resume claims. Keep values as the schema expects: work and education are arrays of entries, and a work entry can hold its dates, role, organization, and highlight strings together. Use dates and wording that match your actual record. Do not add fields just because the format allows them; an optional schema field is not an instruction to disclose that information.
You can start with only the sections you plan to use. Add skills, projects, publications, or languages when they help describe your experience and the theme you choose renders them as you expect. Before adding a section such as references, consider whether it belongs in a resume you will share broadly. The file can contain more information than any one application needs.
Build and validate resume.json
Start from the current schema sample or a blank JSON file, then enter a small, representative subset of your resume. JSON is strict about punctuation: object keys and string values use double quotes, items in arrays are separated by commas, and a trailing comma can make the file invalid. Keep a clean backup before a bulk edit or conversion.
The current JSON Resume CLI documentation recommends the resumed command-line tool. After installing or running it according to the official instructions, use the validator on the file you intend to render:
npx resumed validate resume.json
The official CLI documentation says a successful validation returns exit code 0 and a validation error returns non-zero. If the validator reports an invalid field, fix the source and run the check again. Do not silence the error by deleting a section until you know whether the issue is a typo, a wrong value type, or a schema mismatch.
Schema validation is a structural check. Review the data separately:
- Confirm every title, date, employer, degree, and credential is accurate.
- Check that start and end dates do not contradict one another or your existing resume.
- Read each highlight as a standalone bullet; remove claims that are hard to substantiate.
- Open every portfolio, project, and profile link.
- Remove private details that are not needed for the intended reader.
A file can pass a schema check and still contain a wrong date, a broken link, or a statement you do not want to share. Validation does not replace a content review.
Choose a theme by testing your real content
JSON Resume themes are packages that transform structured data into a document layout. The official themes page lists a broad community ecosystem and notes that the hosted Registry may offer themes not listed on that page.
Choose a theme that handles your actual resume: number of roles, length of bullets, education, projects, and any optional sections. Check whether it supports links and how it wraps long text. If you are deciding between two themes, render the same data in both.
For a local first pass, the official CLI documentation shows rendering an HTML preview with a selected theme:
npx resumed render resume.json --theme jsonresume-theme-even --output resume.html
The theme must be available to the renderer. The documentation shows themes installed as npm packages; a package may have its own dependencies or setup. Check the current theme instructions and package name rather than assuming that every theme in an online gallery works with every local command.
Open the HTML output in a browser and inspect it at normal desktop and narrow-screen widths. It does not tell you how the PDF will paginate, so still review the final PDF.
Export the file type the employer asks for
The JSON source and the application attachment serve different purposes. If the application asks for PDF, use the renderer’s PDF option or export through a documented browser-based path. The current resumed CLI guide documents PDF output through Puppeteer and notes that Puppeteer is required for that command. Follow the current setup instructions for your environment.
npx resumed render resume.json --theme jsonresume-theme-even --type pdf --output resume.pdf
Run the command only after you have chosen the theme and confirmed the intended source file. If the employer requests DOCX, do not assume the JSON Resume CLI will provide that format; the documented CLI path centers on HTML and PDF. Use a workflow that can produce the requested format and inspect the result. A structured source file is not evidence that a particular export will meet an employer’s file requirement.
Keep each application copy identifiable. Use a clear filename such as Alex-Example-Software-Engineer-Resume.pdf, and avoid uploading resume.json when the application form asks for a finished resume file. Keep the editable source in a separate folder so you can make accurate changes later.
Inspect the exact PDF before you upload it
After the final wording edit, render a fresh file and open that exact export. Check it visually, then review the text and links. Do not rely only on the theme preview or a PDF generated before your last change.
Check page layout
Confirm the expected page count. Look for a blank extra page, clipped text, split headings, crowded contact details, or bullets that run into another column. Check the top and bottom of each page, where dates or final lines can disappear. Make sure the font is readable at normal zoom and the hierarchy helps a recruiter scan roles and dates.
Check the text layer
Select and copy a few lines from the PDF into a plain-text editor. Confirm the name and contact details appear in a sensible order, then section headings, roles, dates, and bullets. If text extraction is scrambled or symbols disappear, try a simpler theme and export again.
A JSON schema and an exported text layer do not guarantee that an applicant tracking system will parse or rank the file as intended. Follow the employer’s instructions and, when the portal provides a preview of uploaded material, review that preview before completing the application.
Check links, fonts, and personal details
Click your email, portfolio, and profile links in the PDF. Check your name and contact details. If a theme renders icons without visible link labels, consider whether a person can still tell where each link goes. Confirm any custom font looks consistent in another viewer or device. If your export tool supports document metadata, remove stale author or title details that should not travel with the file.
Keep the source and final file in a folder that fits your privacy needs. If you chose a hosted Registry path, review the public page from a signed-out browser and confirm that the visible information is intentional. If the URL is meant to be private, verify the access model rather than assuming a secret URL protects it.

Keep one source and control your variants
A structured source can make updates and alternate versions easier, but only if you decide which file is authoritative. Keep a primary resume.json with your accurate career history. If a role needs a shorter or more focused version, save a deliberate variant and label it with the target or date. Compare it with the master before sending it so that a tailored bullet or contact change does not accidentally persist into unrelated applications.
Do not use a schema as a substitute for a change history. Save a dated backup before a major edit, and keep a note of the theme and renderer version used for an important export. If you update a theme or package, render the same source again and check whether pagination, fonts, or section order changed.
Choose hosted sharing only when a public profile is useful to you. If the Registry’s current GitHub connection or Gist visibility does not fit your privacy needs, you can still keep the structured data locally and render an application file without publishing a shareable profile. Read product and repository documentation before moving private career data into a service.
A final application-file checklist
Before upload, confirm:
- The source passed JSON/schema validation and the content review.
- You rendered from the intended master or labeled variant.
- The final PDF opens, has the expected page count, and shows no cut-off lines.
- Text selection, dates, bullets, and links work in the exported file.
- The attachment has the format, size, and filename the employer requests.
- Your online profile, if you created one, exposes only the information you chose to share.
If the employer asks for a different file type, follow that requirement and review that file instead. Keep the JSON as your editable source where it helps, and treat the exported attachment as the version the application will receive.
For your next application, pair the reviewed file with a role that matches your current scope. Browse recent roles on LandOffer.ai.


