VitaeFlow Spec

An open standard for embedding structured resume data in PDF files.

VitaeFlow defines a JSON schema for resumes and a method for embedding it inside PDF documents — similar to how Factur-X embeds structured invoice data in PDF/A-3.

The result is a PDF that is both human-readable (the visual CV) and machine-readable (the embedded JSON), enabling reliable parsing by ATS and job platforms — no parsing heuristics, no guessing.

  Resume PDF  +  Structured JSON  →  .vf.pdf
  (visual)       (machine-readable)   (both)

Status

Draft v0.1 — the schema is functional and implemented in the SDK and CLI, but everything is subject to change before v1.0.

Schema

The schema is defined in schema.json using JSON Schema 2020-12.

Required fields

Field	Description
version	Schema version ("0.1")
profile	Always "standard"
basics	Name, email, and core identity

Optional sections

All other sections are opt-in — include what you have:

work education skills languages certifications projects publications volunteer references interests

Example

{
  "version": "0.1",
  "profile": "standard",
  "lang": "fr",
  "basics": {
    "givenName": "Marie",
    "familyName": "Laurent",
    "headline": "Développeuse Full Stack",
    "email": "marie.laurent@example.com",
    "location": { "city": "Lyon", "countryCode": "FR" },
    "profiles": [
      { "network": "github", "username": "mlaurent", "url": "https://github.com/mlaurent" }
    ]
  },
  "work": [
    {
      "organization": "TechCorp",
      "position": "Lead Developer",
      "startDate": "2021-03",
      "summary": "Lead d'une équipe de 5 développeurs.",
      "highlights": ["Migration vers microservices", "Réduction du temps de chargement de 60%"]
    }
  ],
  "education": [
    { "institution": "INSA Lyon", "area": "Informatique", "studyType": "Diplôme d'ingénieur", "startDate": "2011-09", "endDate": "2016-06" }
  ],
  "skills": [
    { "category": "Langages", "items": [{ "name": "TypeScript", "level": "expert" }] }
  ],
  "languages": [
    { "language": "Français", "code": "fr", "fluency": "native" }
  ]
}

See examples/ for a complete sample resume.

PDF embedding

VitaeFlow uses the PDF/A-3 associated files mechanism:

• The JSON is stored as an embedded file named vitaeflow.json
• The AFRelationship is set to /Alternative
• XMP metadata includes schema version and profile

This approach is non-destructive — the PDF remains readable by any viewer. Tools that understand VitaeFlow can extract the structured data; others simply ignore it.

Versioning

The schema follows an additive-only evolution model:

• New optional fields and enum values may be added in minor versions
• Fields are never removed or renamed
• A reader supporting v1.x can read any v1.0+ document

Ecosystem

Project	Description
@vitaeflow/sdk	JavaScript/TypeScript SDK — validate, embed, extract
vitaeflow CLI	Command-line tool
vitaeflow.org	Website with interactive tools

License

MIT