Occupations and skills should be ESCO, for the reason industries are NACE

tiagoagueda commented

2026-09-17 19:30:34 +00:00

Owner

A job title is free text everywhere in Postulo. So is a skill. That is correct for what a
person types and wrong for what the application can then do with it: Software Engineer,
Ingénieur logiciel and Engenheiro de software are one job and three strings, and nothing
in the code can tell.

For an application whose whole argument is a job search conducted across European languages,
that is the gap worth closing.

This project has already made this decision once

jobs/industries.py explains why the list of areas of activity is NACE rather than a list
assembled here:

Thirty-two names assembled by hand was not a classification […] the way to fix that is not
to keep adding names, because a hand-made list of two hundred would be two hundred names in
thirty-nine languages, carried by this project for ever (#140).

The translations are the real argument, more than the taxonomy. Eurostat publishes NACE
[…]

Every word of that transfers. ESCO is to occupations and skills what NACE is to
industries: published by the European Commission, roughly 3,000 occupations and 14,000
skills, in every EU language, mapped to ISCO-08, and maintained by somebody else.

What it would buy

Cross-language matching. A listing captured in French and a CV written in Portuguese
become comparable. Nothing else on the roadmap makes that possible.
A skills vocabulary for the CV that is not free text, which the résumé side needs and
currently invents per entry.
Translations that arrive with the data, exactly as NACE's do — which is the argument
#140 already accepted, and which matters more with each language milestone (#70, #71,
#72).
A ladder to the public services. EURES and the national services already speak ESCO, so
a source plugin reading one of them (#241) has somewhere to put what it reads.

The judgement to make, and it is the same one as NACE

ESCO's full occupation list is far too deep for a picker, exactly as NACE's 615 classes were
— industries.py chose divisions because they are "the level where the names still mean
something to the person reading them".

The analogue here is probably ISCO-08 unit groups: about 436 four-digit codes, which is
the same order of magnitude as the 87 NACE divisions relative to its classes, and the level
at which a name is still a job somebody recognises. Full ESCO occupations underneath as an
optional refinement, or not at all to begin with.

That choice should be made deliberately and written down in the module the way industries.py
wrote down the NACE one, because it is the decision everything else rests on.

Scope questions this issue has to answer

Where it attaches. A title on JobPosting, a skill on the résumé, or both — and
whether the free-text field stays beside the code, as a person's own wording usually
should.
Licence and distribution. ESCO is published under the EUPL; the data would ship in
jobs/data/ beside nace-2.1.json with its own LICENCE.md, as NACE already does.
Size. NACE at division level is 87 rows. ESCO is a different order of magnitude, and
what ships in the repository versus what is loaded on demand is a real decision rather than
a detail.
Never a requirement. A person must be able to type a job title that is not in any
classification. The code is for what Postulo can do across languages; the text is what the
person meant.

Filed from the same conversation as #241's additions. Not a plugin: this is a core
vocabulary, in the same shape as #140.

A job title is free text everywhere in Postulo. So is a skill. That is correct for what a person types and wrong for what the application can then do with it: *Software Engineer*, *Ingénieur logiciel* and *Engenheiro de software* are one job and three strings, and nothing in the code can tell. For an application whose whole argument is a job search conducted across European languages, that is the gap worth closing. ## This project has already made this decision once `jobs/industries.py` explains why the list of areas of activity is NACE rather than a list assembled here: > Thirty-two names assembled by hand was not a classification […] the way to fix that is not > to keep adding names, because a hand-made list of two hundred would be two hundred names in > thirty-nine languages, carried by this project for ever (#140). > > **The translations are the real argument, more than the taxonomy.** Eurostat publishes NACE > […] Every word of that transfers. **ESCO is to occupations and skills what NACE is to industries**: published by the European Commission, roughly 3,000 occupations and 14,000 skills, in every EU language, mapped to ISCO-08, and maintained by somebody else. ## What it would buy - **Cross-language matching.** A listing captured in French and a CV written in Portuguese become comparable. Nothing else on the roadmap makes that possible. - **A skills vocabulary for the CV that is not free text**, which the résumé side needs and currently invents per entry. - **Translations that arrive with the data**, exactly as NACE's do — which is the argument #140 already accepted, and which matters more with each language milestone (#70, #71, #72). - **A ladder to the public services.** EURES and the national services already speak ESCO, so a source plugin reading one of them (#241) has somewhere to put what it reads. ## The judgement to make, and it is the same one as NACE ESCO's full occupation list is far too deep for a picker, exactly as NACE's 615 classes were — `industries.py` chose divisions because they are "the level where the names still mean something to the person reading them". The analogue here is probably **ISCO-08 unit groups**: about 436 four-digit codes, which is the same order of magnitude as the 87 NACE divisions relative to its classes, and the level at which a name is still a job somebody recognises. Full ESCO occupations underneath as an optional refinement, or not at all to begin with. That choice should be made deliberately and written down in the module the way `industries.py` wrote down the NACE one, because it is the decision everything else rests on. ## Scope questions this issue has to answer - **Where it attaches.** A title on `JobPosting`, a skill on the résumé, or both — and whether the free-text field stays beside the code, as a person's own wording usually should. - **Licence and distribution.** ESCO is published under the EUPL; the data would ship in `jobs/data/` beside `nace-2.1.json` with its own `LICENCE.md`, as NACE already does. - **Size.** NACE at division level is 87 rows. ESCO is a different order of magnitude, and what ships in the repository versus what is loaded on demand is a real decision rather than a detail. - **Never a requirement.** A person must be able to type a job title that is not in any classification. The code is for what Postulo can do across languages; the text is what the person meant. Filed from the same conversation as #241's additions. Not a plugin: this is a core vocabulary, in the same shape as #140.

tiagoagueda added this to the 0.5.0 milestone

2026-09-17 19:30:34 +00:00

tiagoagueda added the

enhancement

internationalisation

labels

2026-09-17 19:30:34 +00:00

tiagoagueda commented

2026-09-29 11:37:54 +00:00

Author

Owner

Where this stands on 2026-09-29, checked against the code on main.

Occupations: done, in three commits on 2026-09-24 that did not name this issue, which is why it stayed open:

cbee1e16b: a posting keeps the ISCO-08 unit group its title matches. The title box offers the unit groups in the reader's language on the intake form, the listing form and the capture review, and the code travels in the API and the export (format 18).
949f784e8: the classification is downloaded in place by manage.py fetch_esco, not committed.
85eabdf74: fetched from the ESCO web service's real endpoint.

jobs/esco.py writes down the decisions this issue asked to have written down: the unit group as the level a person picks, the free text kept beside the code, EUPL 1.2, and nothing fetched at run time.

Skills: not done. The issue's second point, "a skills vocabulary for the CV that is not free text", and its scope question "a skill on the résumé, or both" have no code behind them:

resume.Skill is a name and a group, free text only.
fetch_esco harvests unit groups and occupations and no skills; the downloaded esco-1.2.1.json holds 28 languages, 436 unit groups and 3,039 occupations, and nothing else.
Nothing on the résumé side reads ESCO.

This stays open for the skills half.

Where this stands on 2026-09-29, checked against the code on `main`. **Occupations: done**, in three commits on 2026-09-24 that did not name this issue, which is why it stayed open: - `cbee1e16b`: a posting keeps the ISCO-08 unit group its title matches. The title box offers the unit groups in the reader's language on the intake form, the listing form and the capture review, and the code travels in the API and the export (format 18). - `949f784e8`: the classification is downloaded in place by `manage.py fetch_esco`, not committed. - `85eabdf74`: fetched from the ESCO web service's real endpoint. `jobs/esco.py` writes down the decisions this issue asked to have written down: the unit group as the level a person picks, the free text kept beside the code, EUPL 1.2, and nothing fetched at run time. **Skills: not done.** The issue's second point, "a skills vocabulary for the CV that is not free text", and its scope question "a skill on the résumé, or both" have no code behind them: - `resume.Skill` is a name and a group, free text only. - `fetch_esco` harvests unit groups and occupations and no skills; the downloaded `esco-1.2.1.json` holds 28 languages, 436 unit groups and 3,039 occupations, and nothing else. - Nothing on the résumé side reads ESCO. This stays open for the skills half.

tiagoagueda referenced this issue from a commit

2026-09-29 17:30:56 +00:00

Give each skill on the career record the ESCO skill its name is (#266)

tiagoagueda closed this issue

2026-09-29 17:30:56 +00:00

tiagoagueda referenced this issue

2026-09-29 19:46:00 +00:00

CodeQL: a small cluster of real quality findings, and the guards it cannot see #249

tiagoagueda referenced this issue

2026-10-01 10:46:30 +00:00

Docker image: fetch_esco writes into the root-owned source tree, so the documented install step fails #411

tiagoagueda referenced this issue