@jsonresume/schema 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,7 +8,7 @@ Standard, Specification, Schema
8
8
 
9
9
  > **Note:** This package now lives in the [jsonresume.org monorepo](https://github.com/jsonresume/jsonresume.org) as `packages/schema` (imported with full history from [jsonresume/resume-schema](https://github.com/jsonresume/resume-schema)). It keeps its npm identity as [`@jsonresume/schema`](https://www.npmjs.com/package/@jsonresume/schema) and is published from this workspace. Please open issues and PRs against the monorepo.
10
10
 
11
- The current stable schema is represented by the files `schema.json` and `sample.resume.json`.
11
+ The current stable schema is represented by the files `schema.json` and `sample.resume.json`. [`SPEC.md`](SPEC.md) is the normative description of the 1.x format: what a conforming document is, what each field means, and the compatibility promise.
12
12
 
13
13
  ### Getting started
14
14
 
package/SPEC.md ADDED
@@ -0,0 +1,170 @@
1
+ # JSON Resume 1.x
2
+
3
+ This document specifies the JSON Resume format, version 1.x: what a
4
+ conforming document is, what its fields mean, and what producers and
5
+ consumers of it must do. It is the first step towards a formal standard
6
+ (#310). The machine-readable definition is [`schema.json`](schema.json)
7
+ (JSON Schema draft-07); where this text and the schema disagree, the schema
8
+ decides what is valid and this text is wrong.
9
+
10
+ The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be
11
+ interpreted as described in RFC 2119.
12
+
13
+ ## 1. Documents
14
+
15
+ A JSON Resume document is a JSON text (RFC 8259) whose top-level value is
16
+ an object and which validates against `schema.json`. By convention it is
17
+ stored as `resume.json` and served as `application/json`, in UTF-8.
18
+
19
+ - Every field is optional. `{}` is a conforming document.
20
+ - Objects MAY carry properties this specification does not define; they
21
+ stay valid (§6).
22
+ - A field that is defined MUST have the type given here. A property whose
23
+ name this specification defines but whose value has another type makes the
24
+ document invalid, even where earlier versions did not define that name.
25
+
26
+ ## 2. Conventions
27
+
28
+ **Dates.** Dates are strings in a reduced ISO 8601 form: `YYYY`, `YYYY-MM`
29
+ or `YYYY-MM-DD` (years 1000 to 2999), as precise as the author knows. Every
30
+ date is optional. An entry with a `startDate` and no `endDate` is current or
31
+ ongoing. `meta.lastModified` is the exception: a date and time,
32
+ `YYYY-MM-DDThh:mm:ss`.
33
+
34
+ **URLs** are absolute URIs (RFC 3986) where marked `uri` in the schema.
35
+ `basics.email` is an email address. `basics.phone` is free text in any
36
+ format.
37
+
38
+ **Text** is plain text, written to be read by people. Newlines MAY separate
39
+ lines (for example in `location.address`). Values meant for programs (codes,
40
+ tags, identifiers) are noted as such below.
41
+
42
+ **Inline Markdown** is allowed in prose fields: every `summary`,
43
+ `work[].highlights[]`, `projects[].description` and
44
+ `projects[].highlights[]`. Only CommonMark inline syntax is part of the
45
+ format: `**strong**`, `*emphasis*` (or `_emphasis_`), `` `code` `` and
46
+ `[links](https://example.com)`. Block syntax (headings, lists, tables) is
47
+ not, and stays literal text. No flag marks it: inline syntax reads as plain
48
+ text where it isn't rendered. Consumers that render it MUST escape the text
49
+ as HTML first and SHOULD keep only `http`, `https` and `mailto` links;
50
+ consumers that can't show it (plain text, ATS) SHOULD strip the marks and
51
+ keep the words. `@jsonresume/utils` provides both (`renderInlineMarkdown`,
52
+ `stripInlineMarkdown`), so themes agree.
53
+
54
+ **Countries** are ISO 3166-1 alpha-2 codes (`US`, `AU`, `IN`) in
55
+ `location.countryCode`.
56
+
57
+ **Languages** are BCP 47 tags (`en`, `pt-BR`) in `meta.language` and
58
+ `meta.translations[].language`. `languages[].language` is the name of a
59
+ language, for people (`Spanish`).
60
+
61
+ **Lists** are arrays. Order is the author's: consumers SHOULD keep it, and
62
+ MAY additionally sort dated entries by date.
63
+
64
+ ## 3. The resume
65
+
66
+ | Field | Meaning |
67
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
68
+ | `$schema` | URL of the schema the document is written against. |
69
+ | `basics` | The person: `name`, `label` (a headline such as "Web Developer"), `image` (URL of a photo), `email`, `phone`, `url` (their site), `summary` (a short biography), `location` (§4), `profiles` (`network`, `username`, `url` on other sites). |
70
+ | `objective` | A forward-looking career goal. Distinct from `basics.summary`, which describes background. |
71
+ | `work` | Jobs held: `name` (employer), `description` (of the employer), `position`, `location`, `url`, `startDate`, `endDate`, `summary`, `highlights` (accomplishments), `keywords` (skills and tools used), `type` (how the role was held: `full-time`, `part-time`, `contract`, `freelance`, `internship`, `temporary`). |
72
+ | `volunteer` | Unpaid roles: `organization`, `position`, `location`, `url`, `startDate`, `endDate`, `summary`, `highlights`. |
73
+ | `education` | `institution`, `location`, `url`, `area` (subject), `studyType` (degree), `startDate`, `endDate`, `score`, `courses`, `summary` (thesis, honours, context). |
74
+ | `awards` | `title`, `date`, `awarder`, `summary`. |
75
+ | `certificates` | `name`, `date`, `issuer`, `url`, `credentialId`, `expiryDate`, `summary`. |
76
+ | `publications` | `name`, `authors` (in published order, including the owner), `publisher` (for a talk, the event), `releaseDate`, `volume`, `issue`, `pages`, `identifiers` (keyed by scheme: `doi`, `isbn`, `arxiv`, …), `url`, `summary`, `type` (`article`, `book`, `patent`, `thesis`, `talk`, …). |
77
+ | `skills` | `name`, `level`, `keywords`. |
78
+ | `languages` | `language` (its name) and `fluency` (a label people read, such as "Fluent"). |
79
+ | `interests` | `name`, `keywords`. |
80
+ | `references` | `name`, `reference` (the text), `relationship`, `organization`, `date`, `availableOnRequest` (show "available on request" instead of the text). There are deliberately no contact fields. |
81
+ | `projects` | `name`, `summary`, `description` (deprecated alias of `summary`; `summary` wins when both are set), `highlights`, `keywords`, `startDate`, `endDate`, `url`, `roles`, `entity` (affiliation), `type` (`talk`, `application`, …). |
82
+ | `meta` | About the document, not the person (§5). |
83
+ | `custom` | Extension data (§6). Allowed at the root, in `basics`, and on every entry of every section. |
84
+
85
+ Free-text type fields (`work[].type`, `publications[].type`, `projects[].type`) take any
86
+ value; the values listed are recommendations, so that tools can agree on
87
+ common cases.
88
+
89
+ ## 4. Locations
90
+
91
+ A location is an object with `address`, `postalCode`, `city`,
92
+ `countryCode` (§2) and `region` (a state or province). `basics.location` is
93
+ a location object. `work[].location`, `volunteer[].location` and
94
+ `education[].location` are a location object or a string of free text
95
+ ("Menlo Park, CA"); `work[].location` was only a string before 1.5, and
96
+ consumers SHOULD accept both forms.
97
+
98
+ ## 5. Meta
99
+
100
+ | Field | Meaning |
101
+ | -------------- | --------------------------------------------------------------------------- |
102
+ | `canonical` | URL of the latest version of this document. |
103
+ | `version` | The document's own version, in semver (`v1.0.0`). |
104
+ | `lastModified` | When the document last changed (§2). |
105
+ | `language` | The language the document is written in (§2). |
106
+ | `translations` | The same resume in other languages: `{ language, url }`, one document each. |
107
+
108
+ One document holds one language; a resume in several languages is several
109
+ documents linked by `meta.translations`.
110
+
111
+ Tools also keep their own settings in `meta`. The most common is
112
+ `meta.theme`, the name of the theme the author chose (a theme package name
113
+ such as `jsonresume-theme-even`, or its short name `even`). It is a
114
+ convention, not part of the schema.
115
+
116
+ ## 6. Extensions
117
+
118
+ Data this specification has no field for goes in `custom`, an object whose
119
+ keys are free-form. Producers SHOULD namespace its keys by tool
120
+ (`"custom": { "myTool": { … } }`) to avoid collisions.
121
+
122
+ Unknown properties outside `custom` are also valid, for compatibility with
123
+ documents written before `custom` existed. New extensions SHOULD use
124
+ `custom`.
125
+
126
+ ## 7. Producers and consumers
127
+
128
+ A **producer** writes documents; a **consumer** reads them (a theme, a
129
+ validator, an ATS, a converter).
130
+
131
+ - Producers MUST write conforming documents and SHOULD omit empty values
132
+ rather than write empty strings.
133
+ - Consumers MUST accept every conforming document, MUST NOT fail on unknown
134
+ properties, and SHOULD treat every field as possibly absent.
135
+ - Consumers that display a resume SHOULD NOT render `custom`, and need not
136
+ render every section.
137
+ - Tools that read and then write a document (editors, converters) SHOULD
138
+ preserve `custom` and unknown properties unchanged.
139
+
140
+ ## 8. Compatibility
141
+
142
+ Versions follow Semantic Versioning, published as `@jsonresume/schema`.
143
+
144
+ - **Within 1.x**, changes are additive: new fields are optional, and a
145
+ document that conforms to an earlier 1.x version conforms to every later
146
+ one. The one exception is §1's last rule: when a new field is defined, an
147
+ existing document that used the same name with a different type stops
148
+ validating. Before defining a field, the schema review checks the
149
+ resumes published on jsonresume.org for such uses.
150
+ - Deprecated fields stay valid for the rest of 1.x (for example
151
+ `projects[].description`).
152
+ - Breaking changes wait for a major version.
153
+
154
+ How changes are proposed and decided is in
155
+ [CONTRIBUTING.md → Proposing Schema Changes](../../CONTRIBUTING.md#proposing-schema-changes);
156
+ the decisions are recorded in [DECISIONS.md](DECISIONS.md).
157
+
158
+ ## 9. Implementations
159
+
160
+ - [`@jsonresume/schema`](https://www.npmjs.com/package/@jsonresume/schema)
161
+ (JavaScript): `schema.json` and a validator.
162
+ - [`json-resume-serde`](../core-rust) (Rust): typed serde bindings with
163
+ validation, written separately from the JavaScript validator. It covers
164
+ every field of 1.x, keeps unknown properties, and is tested against the
165
+ schema's sample and examples in CI.
166
+ - [`@jsonresume/types`](../types) (TypeScript): types generated from the
167
+ schema.
168
+
169
+ The job description format (`job-schema.json`) is a separate draft and not
170
+ part of this specification.
package/job-schema.json CHANGED
@@ -60,12 +60,100 @@
60
60
  },
61
61
  "salary": {
62
62
  "type": "string",
63
- "description": "100000"
63
+ "description": "The pay as the post words it, for display, e.g. '$120k–150k + equity'. Structured amounts go in compensation (#319)"
64
+ },
65
+ "compensation": {
66
+ "type": "object",
67
+ "description": "The pay as numbers, for tools (#319). salary stays the text people read. Values normalised to one currency are derived data, not part of the document",
68
+ "additionalProperties": true,
69
+ "properties": {
70
+ "min": {
71
+ "type": "number",
72
+ "description": "The lowest amount offered, per period"
73
+ },
74
+ "max": {
75
+ "type": "number",
76
+ "description": "The highest amount offered, per period; equal to min for a single figure"
77
+ },
78
+ "currency": {
79
+ "type": "string",
80
+ "description": "ISO 4217 code, e.g. USD, EUR, AUD"
81
+ },
82
+ "period": {
83
+ "type": "string",
84
+ "enum": ["hour", "day", "week", "month", "year"],
85
+ "description": "What each amount is paid for"
86
+ }
87
+ }
64
88
  },
65
89
  "experience": {
66
90
  "type": "string",
67
91
  "description": "Senior or Junior or Mid-level"
68
92
  },
93
+ "facets": {
94
+ "type": "object",
95
+ "description": "The post in fixed terms tools can filter on (#353). Each is optional, and unspecified means the post does not say. The free-text fields above stay for display",
96
+ "additionalProperties": true,
97
+ "properties": {
98
+ "remoteScope": {
99
+ "type": "string",
100
+ "enum": [
101
+ "onsite",
102
+ "hybrid",
103
+ "remote_region",
104
+ "remote_global",
105
+ "unspecified"
106
+ ],
107
+ "description": "Where the work is done: remote_region is remote within named regions, remote_global remote from anywhere"
108
+ },
109
+ "remoteRegions": {
110
+ "type": "array",
111
+ "items": {
112
+ "type": "string"
113
+ },
114
+ "description": "Where remote work is allowed, when limited, e.g. ['US'], ['EU']"
115
+ },
116
+ "timezoneRange": {
117
+ "type": "string",
118
+ "description": "Hours of overlap or time zones required, e.g. UTC-5 to UTC+1"
119
+ },
120
+ "seniority": {
121
+ "type": "string",
122
+ "enum": [
123
+ "intern",
124
+ "junior",
125
+ "mid",
126
+ "senior",
127
+ "staff_plus",
128
+ "lead_management",
129
+ "unspecified"
130
+ ],
131
+ "description": "The level of the role"
132
+ },
133
+ "employmentType": {
134
+ "type": "string",
135
+ "enum": [
136
+ "full_time",
137
+ "part_time",
138
+ "contract",
139
+ "internship",
140
+ "cofounder",
141
+ "unspecified"
142
+ ],
143
+ "description": "How the role is held"
144
+ },
145
+ "visaSponsorship": {
146
+ "type": "string",
147
+ "enum": ["yes", "no", "unspecified"],
148
+ "description": "Whether the employer sponsors a visa"
149
+ },
150
+ "salaryProvenance": {
151
+ "type": "string",
152
+ "enum": ["stated", "inferred", "absent"],
153
+ "description": "Whether compensation comes from numbers the post states, was inferred, or is missing"
154
+ }
155
+ }
156
+ },
69
157
  "responsibilities": {
70
158
  "type": "array",
71
159
  "description": "what the job entails",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jsonresume/schema",
3
- "version": "1.7.0",
3
+ "version": "1.8.0",
4
4
  "description": "JSON Resume Schema",
5
5
  "private": false,
6
6
  "main": "validator.js",
@@ -19,6 +19,7 @@
19
19
  "schema.json",
20
20
  "job-schema.json",
21
21
  "validator.js",
22
+ "SPEC.md",
22
23
  "examples"
23
24
  ],
24
25
  "dependencies": {
package/sample.job.json CHANGED
@@ -14,7 +14,20 @@
14
14
  },
15
15
  "remote": "Hybrid",
16
16
  "salary": "100000",
17
+ "compensation": {
18
+ "min": 100000,
19
+ "max": 100000,
20
+ "currency": "EUR",
21
+ "period": "year"
22
+ },
17
23
  "experience": "Mid-level",
24
+ "facets": {
25
+ "remoteScope": "hybrid",
26
+ "seniority": "mid",
27
+ "employmentType": "full_time",
28
+ "visaSponsorship": "unspecified",
29
+ "salaryProvenance": "stated"
30
+ },
18
31
  "responsibilities": [
19
32
  "Develop and maintain web applications",
20
33
  "Collaborate with cross-functional teams",
@@ -35,6 +35,7 @@
35
35
  "location": "Palo Alto, CA",
36
36
  "description": "Awesome compression company",
37
37
  "position": "CEO/President",
38
+ "type": "full-time",
38
39
  "url": "http://piedpiper.example.com",
39
40
  "startDate": "2013-12-01",
40
41
  "endDate": "2014-12-01",
@@ -155,6 +156,7 @@
155
156
  "meta": {
156
157
  "canonical": "https://raw.githubusercontent.com/jsonresume/jsonresume.org/master/packages/schema/sample.resume.json",
157
158
  "version": "v1.3.1",
158
- "lastModified": "2026-10-22T00:00:00"
159
+ "lastModified": "2026-10-22T00:00:00",
160
+ "language": "en"
159
161
  }
160
162
  }
package/schema.json CHANGED
@@ -57,10 +57,6 @@
57
57
  "type": "string",
58
58
  "description": "e.g. Web Developer"
59
59
  },
60
- "pronouns": {
61
- "type": "string",
62
- "description": "e.g. she/her, they/them (#312)"
63
- },
64
60
  "image": {
65
61
  "type": "string",
66
62
  "description": "URL (as per RFC 3986) to a image in JPEG or PNG format"
@@ -81,7 +77,7 @@
81
77
  },
82
78
  "summary": {
83
79
  "type": "string",
84
- "description": "Write a short 2-3 sentence biography about yourself"
80
+ "description": "Write a short 2-3 sentence biography about yourself. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
85
81
  },
86
82
  "location": {
87
83
  "$ref": "#/definitions/location"
@@ -147,6 +143,10 @@
147
143
  "type": "string",
148
144
  "description": "e.g. Software Engineer"
149
145
  },
146
+ "type": {
147
+ "type": "string",
148
+ "description": "How the role was held. Free text; recommended values: 'full-time', 'part-time', 'contract', 'freelance', 'internship', 'temporary'. Combine them as needed, e.g. 'part-time contract'. Describes past roles, not what you are looking for (#599). A career break is a work entry with type 'career-break', its dates and an optional summary, and no name (#589)"
149
+ },
150
150
  "url": {
151
151
  "type": "string",
152
152
  "description": "e.g. http://facebook.example.com",
@@ -160,11 +160,11 @@
160
160
  },
161
161
  "summary": {
162
162
  "type": "string",
163
- "description": "Give an overview of your responsibilities at the company"
163
+ "description": "Give an overview of your responsibilities at the company. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
164
164
  },
165
165
  "highlights": {
166
166
  "type": "array",
167
- "description": "Specify multiple accomplishments",
167
+ "description": "Specify multiple accomplishments. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)",
168
168
  "items": {
169
169
  "type": "string",
170
170
  "description": "e.g. Increased profits by 20% from 2011-2012 through viral advertising"
@@ -222,7 +222,7 @@
222
222
  },
223
223
  "summary": {
224
224
  "type": "string",
225
- "description": "Give an overview of your responsibilities at the company"
225
+ "description": "Give an overview of your responsibilities at the company. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
226
226
  },
227
227
  "highlights": {
228
228
  "type": "array",
@@ -292,7 +292,7 @@
292
292
  },
293
293
  "summary": {
294
294
  "type": "string",
295
- "description": "Thesis topic, honours, notable projects or other context (#292)"
295
+ "description": "Thesis topic, honours, notable projects or other context (#292). Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
296
296
  },
297
297
  "custom": {
298
298
  "$ref": "#/definitions/custom"
@@ -320,7 +320,7 @@
320
320
  },
321
321
  "summary": {
322
322
  "type": "string",
323
- "description": "e.g. Received for my work with Quantum Physics"
323
+ "description": "e.g. Received for my work with Quantum Physics. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
324
324
  },
325
325
  "custom": {
326
326
  "$ref": "#/definitions/custom"
@@ -360,7 +360,7 @@
360
360
  },
361
361
  "summary": {
362
362
  "type": "string",
363
- "description": "What the certificate covers (#590)"
363
+ "description": "What the certificate covers (#590). Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
364
364
  },
365
365
  "custom": {
366
366
  "$ref": "#/definitions/custom"
@@ -433,7 +433,7 @@
433
433
  },
434
434
  "summary": {
435
435
  "type": "string",
436
- "description": "Short summary of publication. e.g. Discussion of the World Wide Web, HTTP, HTML."
436
+ "description": "Short summary of publication. e.g. Discussion of the World Wide Web, HTTP, HTML. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
437
437
  },
438
438
  "type": {
439
439
  "type": "string",
@@ -567,15 +567,15 @@
567
567
  },
568
568
  "summary": {
569
569
  "type": "string",
570
- "description": "Short summary of the project, consistent with summary in other sections (#296). e.g. Collated works of 2017."
570
+ "description": "Short summary of the project, consistent with summary in other sections (#296). e.g. Collated works of 2017. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
571
571
  },
572
572
  "description": {
573
573
  "type": "string",
574
- "description": "Deprecated alias of summary, kept for compatibility; when both are set, summary wins (#296). e.g. Collated works of 2017."
574
+ "description": "Deprecated alias of summary, kept for compatibility; when both are set, summary wins (#296). e.g. Collated works of 2017. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)"
575
575
  },
576
576
  "highlights": {
577
577
  "type": "array",
578
- "description": "Specify multiple features",
578
+ "description": "Specify multiple features. Inline Markdown allowed: **strong**, *emphasis*, `code` and [links](https://example.com); no headings, lists or tables (#600)",
579
579
  "items": {
580
580
  "type": "string",
581
581
  "description": "e.g. Directs you close but not quite there"
@@ -639,6 +639,29 @@
639
639
  "lastModified": {
640
640
  "type": "string",
641
641
  "description": "Using ISO 8601 with YYYY-MM-DDThh:mm:ss"
642
+ },
643
+ "language": {
644
+ "type": "string",
645
+ "description": "The language this resume is written in, as a BCP 47 tag, e.g. en, pt-BR. One document per language (#288)"
646
+ },
647
+ "translations": {
648
+ "type": "array",
649
+ "description": "The same resume in other languages, one document each (#288)",
650
+ "items": {
651
+ "type": "object",
652
+ "additionalProperties": true,
653
+ "properties": {
654
+ "language": {
655
+ "type": "string",
656
+ "description": "BCP 47 tag of that document, e.g. fr"
657
+ },
658
+ "url": {
659
+ "type": "string",
660
+ "description": "URL (as per RFC 3986) of that document",
661
+ "format": "uri"
662
+ }
663
+ }
664
+ }
642
665
  }
643
666
  }
644
667
  },