@jsonresume/schema 1.7.1 → 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.1",
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
@@ -77,7 +77,7 @@
77
77
  },
78
78
  "summary": {
79
79
  "type": "string",
80
- "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)"
81
81
  },
82
82
  "location": {
83
83
  "$ref": "#/definitions/location"
@@ -143,6 +143,10 @@
143
143
  "type": "string",
144
144
  "description": "e.g. Software Engineer"
145
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
+ },
146
150
  "url": {
147
151
  "type": "string",
148
152
  "description": "e.g. http://facebook.example.com",
@@ -156,11 +160,11 @@
156
160
  },
157
161
  "summary": {
158
162
  "type": "string",
159
- "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)"
160
164
  },
161
165
  "highlights": {
162
166
  "type": "array",
163
- "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)",
164
168
  "items": {
165
169
  "type": "string",
166
170
  "description": "e.g. Increased profits by 20% from 2011-2012 through viral advertising"
@@ -218,7 +222,7 @@
218
222
  },
219
223
  "summary": {
220
224
  "type": "string",
221
- "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)"
222
226
  },
223
227
  "highlights": {
224
228
  "type": "array",
@@ -288,7 +292,7 @@
288
292
  },
289
293
  "summary": {
290
294
  "type": "string",
291
- "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)"
292
296
  },
293
297
  "custom": {
294
298
  "$ref": "#/definitions/custom"
@@ -316,7 +320,7 @@
316
320
  },
317
321
  "summary": {
318
322
  "type": "string",
319
- "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)"
320
324
  },
321
325
  "custom": {
322
326
  "$ref": "#/definitions/custom"
@@ -356,7 +360,7 @@
356
360
  },
357
361
  "summary": {
358
362
  "type": "string",
359
- "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)"
360
364
  },
361
365
  "custom": {
362
366
  "$ref": "#/definitions/custom"
@@ -429,7 +433,7 @@
429
433
  },
430
434
  "summary": {
431
435
  "type": "string",
432
- "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)"
433
437
  },
434
438
  "type": {
435
439
  "type": "string",
@@ -563,15 +567,15 @@
563
567
  },
564
568
  "summary": {
565
569
  "type": "string",
566
- "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)"
567
571
  },
568
572
  "description": {
569
573
  "type": "string",
570
- "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)"
571
575
  },
572
576
  "highlights": {
573
577
  "type": "array",
574
- "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)",
575
579
  "items": {
576
580
  "type": "string",
577
581
  "description": "e.g. Directs you close but not quite there"
@@ -635,6 +639,29 @@
635
639
  "lastModified": {
636
640
  "type": "string",
637
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
+ }
638
665
  }
639
666
  }
640
667
  },