logicsrc/docs/openresume.md

OpenResume.md

A resume is a Markdown file. That is the whole idea.

Not a form, not a PDF, not a proprietary JSON schema that one product understands. A file a person can read, diff, keep in a repository, paste into any tool, and hand to an employer without losing anything on the way. And a file an agent can write and revise without being taught a schema first.

This document describes the convention. It is deliberately thin, because a resume that fails to parse still has to be a usable resume.

The shape

# Ada Lovelace

- **Email**: ada@example.com
- **Location**: London
- **Web**: https://example.com

Mathematician, looking for work on machines that do not exist yet.

## Experience

### Analytical Engine | London
Chief Programmer (1842 - 1843)

- Wrote the first published algorithm intended to be carried out by a machine.
- Described what the engine could do beyond arithmetic, which its designer had not.

## Skills

- Languages: analytical notation, French
- Tools: difference engine, correspondence

## Education

### University of London
Private tuition in mathematics (1840)

The rules

There are six, and every one of them degrades rather than fails.

1. One # heading, and it is the person's name. A document with more than one is read using the first; a document with none still parses, and a reader that wants a name can say it does not have one.

2. The bullet list directly under the name is the contact block. Each item is Key: value, with or without **bold** on the key, or a bare [label](url). Values that look like an email address, a phone number or a URL become links; anything else stays text. Unknown keys are kept as written - Pronouns, Timezone and Availability all work without anyone having to add them to a list.

3. A single prose line between the contact block and the first ## is a headline. One line. More than one, and only the first is treated that way.

4. ## opens a section. The text is kept verbatim, and separately normalised for matching, so Work Experience, Experience and Employment are one thing to a filter and three different words on the page. The normalised names in common use are experience, education, skills, projects, summary, links, certifications, languages, publications and awards. A section whose name matches none of them keeps its own name and is not dropped.

5. ### opens an entry within a section: a job, a degree, a project. A | in the heading splits it into a title and a place - Company | Berlin. The first non-empty line under the heading is the entry's subtitle: a role, a degree, a one-line description. If that line ends in a bracketed range, the range is read out of it:

Chief Programmer (1842 - 1843)
Staff Engineer (Mar 2020 - Present)
Contractor (2019 to 2021)

Hyphens, en dashes and em dashes are all accepted, because all three appear in real resumes. Present, Now, Current and Ongoing mark a current role. Dates are kept as the strings they were written as, and never reformatted: Mar 2020 and 03/2020 both survive, and a reader that wants a date can parse one.

6. Bullets under an entry are its highlights. Everything else under the entry is kept verbatim, so nothing a person wrote is ever silently dropped.

What is deliberately absent

No required fields. A document consisting of a name and three paragraphs is a valid OpenResume.md.

No date format. Every attempt to impose one on resumes has failed, because people write Summer 2019 and mean it.

No schema version. Readers ignore what they do not recognise. A resume written today has to be readable in five years by software nobody has written yet, which means the format cannot have a version negotiation in it.

No structured skills taxonomy. Skills are the lines people wrote. Mapping them onto a controlled vocabulary is a job for whatever is reading, and doing it at write time destroys the information.

Sections a parser derives, not the author

A reader may compute a structured view - name, contact pairs, sections, entries with parsed date ranges - and use it for search and filtering. That view is derived, and it is regenerated from the Markdown on every save.

The Markdown is the canonical copy. If the structured view and the document disagree, the document is right. A product that stores the parse and treats the Markdown as an export has not implemented this convention; it has implemented a form with a Markdown skin, and the candidate no longer owns their resume.

Converting into it

PDF, DOCX and plain text can all be converted to Markdown, and none of the conversions are perfect. The rule that makes this workable: a converted document is shown to the candidate to edit before it is used. A conversion nobody checks is a conversion nobody should trust.

The agenticjobs reference implementation converts .docx by reading word/document.xml directly, and .pdf with pdftotext -layout. Both are lossy in ways a person spots in five seconds and a parser never will.

Why Markdown

Because the alternative formats each fail one of the audiences.

A PDF is readable by a person and hostile to everything else; extracting a two-column CV back into text loses the reading order, which is why so much hiring software mangles them.

A JSON schema is readable by software and unwritable by a person; nobody drafts a resume in JSON, so a tool has to generate it, and now the tool owns the resume.

Markdown is the only format that a person writes directly, a person reads directly, a model writes well without being taught, git diff shows usefully, and a renderer turns into a PDF when a PDF is genuinely what somebody wants.

Implementations

• agenticjobs - the job board this convention was written for. MIT, https://github.com/profullstack/agenticjobs