Migration Guide: v1.2 to v1.3

Nothing you have breaks. Every document valid under 1.2.0 is still valid under 1.3.0, in both JSON and XML. If you do nothing, everything keeps working. The changes below are worth making, not urgent.

If you would rather not move at all, pin the old version — it is frozen and will not change:

{ "$schema": "https://schema-resume.org/1.2/schema.json" }

1. Demographic fields moved into their own object

basics.age, basics.dateOfBirth and basics.gender now live under basics.demographics.

Before

{
  "basics": {
    "name": "Jane Smith",
    "age": 34,
    "dateOfBirth": "1992-04-11",
    "gender": "female"
  }
}

After

{
  "basics": {
    "name": "Jane Smith",
    "demographics": {
      "age": 34,
      "dateOfBirth": "1992-04-11",
      "gender": "female"
    }
  }
}

The old field names still validate and are marked deprecated; they are scheduled for removal in 2.0.0. Editors that understand the keyword will show them struck through.

XML follows the same shape:

<basics>
  <name>Jane Smith</name>
  <demographics>
    <age>34</age>
    <dateOfBirth>1992-04-11</dateOfBirth>
    <gender>female</gender>
  </demographics>
</basics>

Why

These are protected characteristics. In the UK and most of the EU a CV should not carry age, date of birth or gender: employers are advised not to request them, and a document that volunteers them invites a discrimination claim against whoever processes it. Gender may additionally be special-category data under GDPR Article 9.

They were not removed, because the convention is not universal — a German or Japanese CV commonly carries a date of birth. Grouping them makes including them a deliberate act rather than an incidental one, and lets a processor strip the whole object in a single step:

delete resume.basics.demographics;

2. $schema names the JSON Schema dialect

schema.json previously declared:

"$schema": "https://schema-resume.org/meta-schema.json"

which no validator could resolve, so ajv compile -s schema.json, check-jsonschema and IDE validation all failed until the consumer registered the meta-schema by hand. It now declares the dialect it is actually written in:

"$schema": "http://json-schema.org/draft-07/schema#"

Nothing to change in your documents. Your document's own $schema still points at https://schema-resume.org/schema.json (or a pinned version). If your code called ajv.addMetaSchema(metaSchema) to work around the old value, it is now unnecessary — harmless if you leave it.

meta-schema.json is unchanged in purpose and still published. It describes what a Schema Resume schema looks like; it was never a dialect.

3. The embedded @context is gone from schema.json

schema.json carried a top-level @context with 14 terms. It covered 9 of the 102 terms in the canonical context.jsonld, defined 7 terms that do not exist there, and contradicted it on address. It was also the reason the file failed JSON Schema strict-mode validation.

Use context.jsonld, which is what your document's @context should point at and always should have:

{
  "@context": "https://schema-resume.org/1.3/context.jsonld",
  "$schema": "https://schema-resume.org/1.3/schema.json"
}

4. Dead additionalItems keywords removed

27 occurrences of "additionalItems": false sat beside a schema-form items, where draft-07 ignores the keyword entirely. They constrained nothing. No behaviour changes.

Checking your documents

npx ajv validate -s https://schema-resume.org/1.3/schema.json \
  -c ajv-formats -d your-resume.json

No --strict=false and no -r flag: both schemas now pass ajv's strict mode unaided.

To find documents still using the deprecated field names:

grep -l '"age"\|"dateOfBirth"\|"gender"' *.json

Summary