Resume JSON schema

Hiresweep describes a resume’s data with a public JSON Schema. The same shape is used by Download JSON, by Hiresweep (JSON) imports, and by the resume data in the API, the Patch API and the MCP server.

https://hiresweep.com/schema.json

The endpoint needs no sign-in. It returns the schema as application/schema+json, generated from the same definitions the app validates against, so it always matches the current version of Hiresweep. It follows JSON Schema draft 2020-12.

What it covers

Content: the picture, basic details, the summary, twelve built-in sections and any custom sections.
Design: the template, page layout, page settings, colors, level style, typography and Custom Styles rules (styleRules).
Notes: your private notes (metadata.notes).
Descriptions: every field has a description explaining what it holds and its format.

Text fields that come from the rich-text editor, such as summary.content and each item’s description, are HTML strings. Colors are rgba(r, g, b, a) strings.

The schema has no version field, and a Hiresweep JSON export doesn’t include one. Validate against the live endpoint to check a file against the current shape.

Top-level structure

Key	Type	What it holds
`picture`	object	The photo: `url`, `hidden`, `size`, `rotation`, `aspectRatio`, border and shadow settings.
`basics`	object	`name`, `headline`, `email`, `phone`, `location`, `website` and `customFields`.
`summary`	object	The summary section: `title`, `icon`, `columns`, `hidden` and `content`.
`sections`	object	The built-in sections: `profiles`, `experience`, `education`, `projects`, `skills`, `languages`, `interests`, `awards`, `certifications`, `publications`, `volunteer` and `references`.
`customSections`	array	Extra sections, each with an `id`, a `type` and its own items.
`metadata`	object	Design settings and notes (see below).

All six keys are required.

Sections

Every built-in section has the same outer shape. The fields inside items depend on the section, for example company, position, period and roles in experience.

{
  "title": "",
  "icon": "",
  "columns": 1,
  "hidden": false,
  "items": [
    {
      "id": "…",
      "hidden": false
    }
  ]
}

An empty title prints the default heading in the resume’s language (metadata.page.locale). columns is 1 to 6. A custom section adds an id and a type, one of summary, profiles, experience, education, projects, skills, languages, interests, awards, certifications, publications, volunteer, references or cover-letter. Its items use the item shape of that type.

Metadata

Key	What it holds
`template`	The template id. See the excerpt below.
`layout`	`sidebarWidth` (10 to 50, a percentage) and `pages`, each with `fullWidth` and the section ids in its `main` and `sidebar` columns.
`page`	Margins, spacing, `format`, `locale` and icon settings. See the excerpt below.
`design`	`colors` (`primary`, `text`, `background`) and `level` (`type` and `icon`).
`typography`	`body` and `heading`, each with `fontFamily`, `fontWeights`, `fontSize` (6 to 24 pt) and `lineHeight` (0.5 to 4).
`notes`	Private notes as HTML. Not printed, but included in JSON exports.
`styleRules`	Custom Styles rules, each with an `id`, `label`, `enabled`, a `target` and per-slot `slots`. See Using custom styles.

Excerpt

This excerpt of metadata.properties is copied from the live schema. Template ids are internal names; the gallery shows them as Compass (slate), Beacon (azurill), Bastion (bronzor), Haven (chikorita), Summit (ditgar), Atlas (ditto), Meridian (gengar), Cardinal (glalie), Cove (kakuna), Vantage (lapras), Grove (leafish), Tide (meowth), Ridge (onyx), Drift (pikachu), Vista (rhyhorn) and Crest (scizor).

schema.json (excerpt)

{
  "template": {
    "default": "onyx",
    "description": "The template to use for the resume. Determines the overall design and appearance of the resume.",
    "type": "string",
    "enum": [
      "slate",
      "azurill",
      "bronzor",
      "chikorita",
      "ditgar",
      "ditto",
      "gengar",
      "glalie",
      "kakuna",
      "lapras",
      "leafish",
      "meowth",
      "onyx",
      "pikachu",
      "rhyhorn",
      "scizor"
    ]
  },
  "page": {
    "type": "object",
    "properties": {
      "gapX": {
        "type": "number",
        "minimum": 0,
        "description": "The horizontal gap between the sections of the page, defined in points (pt)."
      },
      "gapY": {
        "type": "number",
        "minimum": 0,
        "description": "The vertical gap between the sections of the page, defined in points (pt)."
      },
      "marginX": {
        "type": "number",
        "minimum": 0,
        "description": "The horizontal margin of the page, defined in points (pt)."
      },
      "marginY": {
        "type": "number",
        "minimum": 0,
        "description": "The vertical margin of the page, defined in points (pt)."
      },
      "format": {
        "default": "a4",
        "type": "string",
        "enum": ["a4", "letter", "free-form"],
        "description": "The format of the page. Can be 'a4', 'letter', or 'free-form'."
      },
      "locale": {
        "default": "en-US",
        "type": "string",
        "description": "The locale of the page. Used for displaying pre-translated section headings, if not overridden."
      },
      "hideLinkUnderline": {
        "default": false,
        "type": "boolean",
        "description": "Whether to hide the underlines of the links."
      },
      "hideIcons": {
        "default": false,
        "type": "boolean",
        "description": "Whether to hide the item-level icons (skills, profiles, interests)."
      },
      "hideSectionIcons": {
        "default": true,
        "type": "boolean",
        "description": "Whether to hide the section heading icons displayed before section titles."
      }
    },
    "required": [
      "gapX",
      "gapY",
      "marginX",
      "marginY",
      "format",
      "locale",
      "hideLinkUnderline",
      "hideIcons",
      "hideSectionIcons"
    ],
    "additionalProperties": false,
    "description": "The page settings of the resume. Determines the margins, format, and locale of the resume."
  }
}

For the full schema, fetch the endpoint:

curl -s https://hiresweep.com/schema.json -o schema.json

Validate a file

Use a validator that supports draft 2020-12. With Ajv, import the 2020 build; the default ajv export only knows draft-07 and can’t compile this schema.

import Ajv2020 from "ajv/dist/2020";

const schema = await fetch("https://hiresweep.com/schema.json").then((response) => response.json());
const validate = new Ajv2020().compile(schema);

if (!validate(resumeData)) {
  console.error(validate.errors);
}

Nested objects don’t allow extra keys (additionalProperties: false), so a typo in a field name fails validation. The top level allows extra keys.

Editor autocompletion

The top level accepts extra keys, so you can add $schema to a resume file to get autocompletion and validation in editors such as VS Code:

{
  "$schema": "https://hiresweep.com/schema.json",
  "basics": {
    "name": "Jane Doe"
  }
}

The editor then flags missing, misspelled or out-of-range fields as you type. Because the top level allows extra keys, a file with $schema still imports.

Using the schema elsewhere

Edit a JSON export in another tool or with an AI assistant, then import it as Hiresweep (JSON). See Importing resumes.
Generate or check resume data before sending it to the API.
Read Hiresweep exports in your own tools without parsing a PDF.

Hiresweep JSON is a different format from the JSON Resume standard. Hiresweep imports JSON Resume files too, as the JSON Resume type.

Getting started

Job search

Resume builder

AI

Account and security

Developers

Use cases

Legal

Resume JSON schema

What it covers

Top-level structure

Sections

Metadata

Excerpt

Validate a file

Editor autocompletion

Using the schema elsewhere

​What it covers

​Top-level structure

​Sections

​Metadata

​Excerpt

​Validate a file

​Editor autocompletion

​Using the schema elsewhere

What it covers

Top-level structure

Sections

Metadata

Excerpt

Validate a file

Editor autocompletion

Using the schema elsewhere