Upgrading

Start with the version you are on. Each section lists only what that step changes; skipping to the newest release means doing every section between.

You do not have to upgrade. Every release is published at a permanent URL and stays there. If a project works today, pinning it is a complete answer:

The same applies to meta-schema.json, context.jsonld, the examples and — from 1.1 onwards — schema-resume.xsd. See versioning and stability for the guarantees behind those URLs.

Which version am I on?

If your documents say "$schema": "https://schema-resume.org/schema.json", you are on whatever is current, because that URL floats. Check what you actually depend on:

An unpinned document is not on a version so much as exposed to all of them. The single most useful change you can make, whatever you decide about upgrading, is to replace /schema.json with a pinned URL in anything you store.

1.0 → 1.1

The largest step. 1.0 predates the schema-resume.org domain, Schema.org alignment and the XML schema.

Domain. 1.0 used https://tradik.github.io/schema-resume/. From 1.1 the canonical host is https://schema-resume.org/. Update both $schema and @context in your documents.

New sections.tools joins the top level. basics grows from 9 fields to 18, including nationalities, workAuthorization, dateOfBirth, gender, age and legalNote. All optional — a valid 1.0 document is a valid 1.1 document once the URLs are updated.

Schema.org alignment.@type and additionalType become available throughout. They are optional for JSON Schema validation but required if you want validator.schema.org to read your document. See the Schema.org validation guide.

XML. 1.1 is the first release with an XSD, at https://schema-resume.org/1.1/schema-resume.xsd. There is nothing to migrate; there was no XML before it.

Full detail: 1.0 → 1.1 migration guide.

1.1 → 1.2

work[].positions. A single company with several roles no longer needs several work entries. The old single-role shape stays valid — positions is additive, and the test suite covers both.

basics.legalNote. A place for GDPR consent statements and disclaimers, with optional country scoping.

Full detail: 1.1 → 1.2 migration guide.

1.2 → 1.3

Additive. Every 1.2 document is still valid.

basics.demographics.age, dateOfBirth and gender move into their own object. The old field names still validate, are marked deprecated, and are scheduled for removal in 2.0.0. See the 1.2 → 1.3 guide for why, and for the one-line change.

$schema names the draft-07 dialect. Nothing changes in your documents. If your code called ajv.addMetaSchema(metaSchema) to work around the old value, it is now unnecessary — harmless if you leave it.

The embedded @context is gone from schema.json. Only affects code that read schema.json["@context"]; use context.jsonld, which is what your document's own @context should point at.

Upgrading the validator packages

The packages embed the schema, so their version is the schema version:

npm  install schema-resume-validator@1.3.0
pip  install schema-resume-validator==1.3.0
gem  install schema-resume-validator -v 1.3.0
composer require schema-resume/validator:^1.3
go get github.com/tradik/schema-resume/validator@v1.3.0

Staying on an older schema means pinning the matching package version. That is the recommended way to depend on a specific release: it removes this site from your runtime path entirely, so nothing you rely on can change or become unreachable.

Check what a registry actually has before assuming. The registries have drifted from each other before — a release reported success while npm had failed:

npm view schema-resume-validator version
curl -s https://pypi.org/pypi/schema-resume-validator/json | jq -r .info.version
curl -s https://rubygems.org/api/v1/gems/schema-resume-validator.json | jq -r .version

Checking a document against a specific version

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

From 1.3 no extra flags are needed. For 1.0 to 1.2, $schema in those releases points at a meta-schema rather than a dialect, so add --strict=false and register it:

npx ajv validate -s https://schema-resume.org/1.2/schema.json \
  -r https://schema-resume.org/1.2/meta-schema.json \
  -c ajv-formats --strict=false -d your-resume.json

XML, from 1.1 onwards:

xmllint --schema https://schema-resume.org/1.3/schema-resume.xsd \
  your-resume.xml --noout

If something breaks

Open an issue with the version you moved from, the version you moved to, and a document that reproduces it: https://github.com/tradik/schema-resume/issues. A pinned URL is always a safe place to retreat to while it is investigated.