# Resume JSON schema

> The JSON Schema for Hiresweep resume data, served at /schema.json: what it covers, how it's structured, and how to validate files against it.

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](https://docs.hiresweep.com/guides/using-the-api), the [Patch API](https://docs.hiresweep.com/guides/using-the-patch-api) and the [MCP server](https://docs.hiresweep.com/guides/using-the-mcp-server).

<Info>[https://hiresweep.com/schema.json](https://hiresweep.com/schema.json)</Info>

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.

<Note>
  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.
</Note>

## 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`.

```json
{
  "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](https://docs.hiresweep.com/guides/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`).

```json 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:

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

## Validate a file

Use a validator that supports draft 2020-12. With [Ajv](https://ajv.js.org), import the 2020 build; the default `ajv` export only knows draft-07 and can't compile this schema.

```javascript

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:

```json
{
  "$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](https://docs.hiresweep.com/guides/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](https://jsonresume.org) standard. Hiresweep imports JSON Resume files too, as the **JSON Resume** type.