cv.json

An open schema for publishing a CV as a single JSON document at a stable URL — so AI agents, ATS systems, and other tools can read career data without parsing a PDF.

Site · Validator · Schema (v1) · /.well-known/cv.json (discovery)

Status

Emerging. cv.json is not a ratified standard. It is a small, opinionated schema currently maintained by FreeCV and used in production on the FreeCV portfolio platform. We're publishing the schema, validator, and examples here so other tools can adopt it and so the schema can evolve in the open. If you ship a CV product and want a say in v2, open an issue.

cv.json keeps the top-level field names of basics, work, education, skills, projects, languages, publications, awards, volunteer, interests, references, and meta familiar — anyone who has touched a JSON-shaped CV before should feel at home. It adds fields the rest of the ecosystem doesn't have (availability, ats, verification, referencesMode, i18n, the v1.3 hiring-signal block, and x-customSections for user-defined sections) and pins down date formats and a discovery convention.

60-second demo

Every published cv.json lives at a stable URL. No auth, no API key, plain HTTP. Try it right now — the demo profile is live (Ashley is fictional; the endpoint and format are real):

$ curl -s https://livelink.cv/ashley/cv.json | jq '.basics.name, .work[0].company'
"Ashley Carter"
"Brightfold Studio"

The response advertises its schema in headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-CV-Version: 1.2.2
Link: <https://cvjson.com/schema/v1.json>; rel="describedby"
Access-Control-Allow-Origin: *
Cache-Control: public, max-age=300

Sites that host a CV can also declare it in HTML for crawlers:

<link rel="alternate" type="application/json"
      href="/ashley/cv.json" title="cv.json" />

…or expose a site-wide discovery manifest at /.well-known/cv.json listing all CVs hosted on the domain.

Schema at a glance

Only basics and meta are required. Everything else is optional and consumers MUST ignore unknown fields.

Date fields accept YYYY, YYYY-MM, or YYYY-MM-DD. The full schema is at schema/v1.json.

Why cv.json exists

Three problems, one schema.

1. PDFs are unparseable in practice. Every CV in the world eventually meets an ATS. ATS parsers are notorious for merging job titles into dates, putting names in the address field, and silently dropping skills. The fix isn't a better parser — it's not parsing in the first place.

2. Existing JSON CV schemas have stalled. The shape of a JSON résumé has been a solved problem for years, but nothing in the space has moved meaningfully — no discovery convention, no version negotiation, no availability or ATS signals, no references-mode. cv.json picks up the parts that haven't been touched and ships them under a real versioning policy.

3. AI agents need structured career data. Recruiting agents, candidate-search tools, and matching systems are being built right now against scraped PDFs and HTML. A canonical JSON endpoint at a known URL is the cheapest way to feed them — same role HTML played for browsers, robots.txt played for crawlers, OpenAPI plays for APIs.

cv.json is the file. The URL is the contract.

Quick start

Option 1 — Publish via FreeCV (easiest)

1. Sign up at freecv.org, build your CV in the editor.
2. Enable the public endpoint in Dashboard → Settings → Public cv.json.
3. Your endpoint goes live at https://livelink.cv/{your-slug}/cv.json.

That's the whole thing. Update your CV once, every consumer fetching the URL gets the new version.

Option 2 — Self-host

You don't need FreeCV. Any web server can serve a cv.json. Minimal recipe:

1. Write a JSON file conforming to schema/v1.json. Start from examples/minimal.json.
2. Serve it at a stable URL with Content-Type: application/json and (ideally) Access-Control-Allow-Origin: *.
3. Add a discovery <link> to the HTML page that "represents" you (portfolio, personal site).
4. Validate before publishing:

npx -y ajv-cli validate \
  -s https://cvjson.com/schema/v1.json \
  -d my-cv.json

Or paste it into freecv.org/validate.

Recommended response headers

Content-Type: application/json; charset=utf-8
X-CV-Version: 1.2.2
Link: <https://cvjson.com/schema/v1.json>; rel="describedby"
Access-Control-Allow-Origin: *
Cache-Control: public, max-age=300

X-CV-Version lets consumers branch behavior without parsing the body. Access-Control-Allow-Origin: * is what makes the file usable from browser tools — please set it.

Minimal example

{
  "$schema": "https://cvjson.com/schema/v1.json",
  "basics": {
    "name": "Jane Smith",
    "label": "Software Engineer",
    "location": "London, UK",
    "summary": "Full-stack developer with 3 years building web apps."
  },
  "work": [{
    "company": "Acme Corp",
    "position": "Software Engineer",
    "startDate": "2022-03",
    "current": true,
    "highlights": ["Cut deploy time by 40% with new CI pipeline"]
  }],
  "skills": ["TypeScript", "React", "Node.js", "PostgreSQL"],
  "education": [{
    "institution": "University of London",
    "degree": "BSc Computer Science",
    "endDate": "2022"
  }],
  "meta": {
    "version": "1.2.2",
    "canonical": "https://example.com/cv.json",
    "lastModified": "2026-06-01",
    "generator": "hand-written"
  }
}

See examples/ for a fuller document, a references-mode demo, and edge cases.

Discovery

Two complementary mechanisms:

Per-page link. On any HTML page that represents a person, add:

<link rel="alternate" type="application/json"
      href="/cv.json" title="cv.json" />

This is the same pattern RSS used. Crawlers and agents can find a person's CV from any page they're mentioned on.

Site-wide manifest. A platform hosting many CVs (job board, agency, talent network) can publish a discovery manifest at /.well-known/cv.json:

{
  "standard": "cv.json",
  "version": "1.2.2",
  "schema": "https://cvjson.com/schema/v1.json",
  "endpointPattern": "https://example.com/{slug}/cv.json",
  "discovery": {
    "humanReadable": "https://example.com/{slug}",
    "machineReadable": "https://example.com/{slug}/cv.json",
    "index": "https://example.com/sitemap-portfolios.xml"
  }
}

The manifest tells a machine how CVs on the domain are addressed and where the index of live endpoints lives (a sitemap or an inline endpoints array — either is conformant). One HTTP request, and an agent knows how to enumerate every CV the site is willing to expose. FreeCV serves this at https://freecv.org/.well-known/cv.json, with the quality-gated index at livelink.cv/sitemap-portfolios.xml.

Adopters

If you publish or consume cv.json, add yourself here via PR.

Publishers

Consumers

PRs welcome. Be honest about implementation status (production, beta, prototype).

Versioning policy