![\"Match](\"https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-6-match-diagram.png\")
<\/figure>\n\n\n\nThree details in this example matter:<\/p>\n\n\n\n
- ” Python ” matches “python”. Case and extra spaces are ignored. In Phase 1, I wrote down this exact requirement: matching must not care about case or extra spaces. I am happy I wrote it down, because the code below is where it had to be true.<\/li>
- aws changes nothing. Only the required skills count. A candidate with extra skills is not punished, and a candidate who lists fifty unrelated skills does not get a fake boost.<\/li>
- The result is a whole number. 2 out of 3 is 66.67%, which becomes 67.<\/li><\/ul>\n\n\n\n
And one special case: if a job requires no skills at all, the score is null (empty), not 100. I explain why in the decisions section.<\/p>\n\n\n\n
Step 1: A pure function in matching.py<\/h2>\n\n\n\n
The whole rule lives in a new file,
jobs\/matching.py<\/code>. It is only two small functions, and it imports nothing from Django.<\/p>\n\n\n\nCleaning a list of skills<\/h3>\n\n\n\n
def normalize_skills(skills):\n \"\"\"Lowercase, trim and de-duplicate a list of skill names.\"\"\"\n if not skills:\n return set()\n return {skill.strip().lower() for skill in skills if skill and skill.strip()}<\/code><\/pre>\n\n\n\nThis is a set comprehension. It looks like a list comprehension, but with curly braces {} instead of square brackets, so Python builds a set. Reading the inside, for each skill in the list:<\/p>\n\n\n\n
skill.strip().lower()<\/code> removes spaces at the start and end, and makes everything lowercase. ” Python ” becomes “python”.<\/li>if skill and skill.strip()<\/code> throws away empty values.None<\/code> and\"\"<\/code> fail the first part. A string of only spaces, ” “, passes the first part, but its strip is empty, so it fails the second.<\/li>- Why throw them away? Without this filter, an empty string would count as a skill. A job with [“python”, “”, ” “] would look like it requires 3 skills when it really requires 1.<\/li>
- Why a set? Because duplicates disappear. If a company accidentally lists python twice, it still counts once.<\/li><\/ul>\n\n\n\n
Calculating the score<\/h3>\n\n\n\n
def match_score(required_skills, candidate_skills):\n \"\"\"Percentage (0-100) of required skills the candidate has, or None.\"\"\"\n required = normalize_skills(required_skills)\n if not required:\n return None\n matched = required & normalize_skills(candidate_skills)\n return round(100 * len(matched) \/ len(required))<\/code><\/pre>\n\n\n\nif not required:<\/code> uses the fact that an empty set is false in Python. If the job needs nothing, we return None before we can divide by zero.<\/li>required & normalize_skills(candidate_skills)<\/code> is set intersection: the skills that appear in both sets. This one symbol, &, is the whole comparison.<\/li>len(matched) \/ len(required)<\/code> gives a fraction. In Python 3, \/ always returns a decimal number: 2 \/ 3 is 0.666…, not 0. (Older Python, and many other languages, would give 0 for two whole numbers. A classic bug source.)<\/li>round(...)<\/code> turns 66.67 into the whole number 67. A small Python detail I learned here:round()<\/code> uses “round half to even”, soround(2.5)<\/code> is 2, not 3. It does not hurt here, but it surprised me.<\/li><\/ul>\n\n\n\nWhy a pure function?<\/h3>\n\n\n\n
A pure function depends only on its inputs and changes nothing outside itself: no database, no request, no global state. Same inputs, same answer, every time. That buys two things:<\/p>\n\n\n\n
- It is very easy to test. I can call it with two plain lists and check the answer. No database, no users, no login. You will see this in Step 3.<\/li>
- It is reusable. It takes two lists, not a Job or an Application. So later I could use the same function to rank jobs for a candidate (“which jobs fit me best?”) without changing a line of it.<\/li><\/ol>\n\n\n\n
Step 2: Showing the score in the API<\/h2>\n\n\n\n
The function exists. Now the API needs to return it. I changed
ApplicationSerializer<\/code> in three small places.<\/p>\n\n\n\nThe import<\/h3>\n\n\n\n
from . import matching<\/code><\/pre>\n\n\n\nI import the module, not the function. So the call reads
matching.match_score(...)<\/code>. Why? Because the namematch_score<\/code> will also be a serializer field (next step), and both would live in the same file. Keeping the module name in front means the two can never collide. This is a naming problem I now think about before it bites, not after. Part 4 and Part 5 both bit me with names.<\/p>\n\n\n\nThe field<\/h3>\n\n\n\n
match_score = serializers.SerializerMethodField()<\/code><\/pre>\n\n\n\nA
SerializerMethodField<\/code> is a field whose value comes from a method calledget_<field name><\/code>. It is also read-only by design: a candidate cannot POST amatch_score<\/code> of 100 for themselves, because the value is always calculated by the server. (That is a nice free safety property. A writable score field would be a bug and a cheat code in one.)<\/p>\n\n\n\nI also added “match_score” to the
fields<\/code> list inMeta<\/code>, right after “status”, so the two values a company cares about sit next to each other in the JSON.<\/p>\n\n\n\nThe method<\/h3>\n\n\n\n
def get_match_score(self, obj):\n return matching.match_score(obj.job.required_skills, obj.candidate.skills)<\/code><\/pre>\n\n\n\n- DRF finds this method by its name:
get_<\/code> plus the field name. And here is a nice contrast with my last two parts: this name lookup fails loudly. If I had typedget_matchscore<\/code>, DRF would raise an error the first time the serializer runs. Not silently wrong likevalidateJob<\/code> in Part 4, and not silently ignored like a permission class insideMeta<\/code> in Part 5. Some framework names shout, some whisper. This one shouts.<\/li>- I placed the method at the class level, next to
validate_job<\/code>. Not insideMeta<\/code>. (I learned that one the hard way too.)<\/li>- No extra database queries. My views already load each application’s job and candidate in one SQL JOIN (I used
select_related<\/code> for that in Phase 1). Soobj.job<\/code> andobj.candidate<\/code> are already in memory when this runs. The score is pure Python set work on two small lists.<\/li><\/ul>\n\n\n\nNo new permission code<\/h3>\n\n\n\n
I didn’t write any new permission rules for the score, and I didn’t need to. The score is part of the application object, and the application already has its permissions from Part 5: only the candidate who owns it and the company that owns the job can read it. A new field inside an object inherits that object’s protection. But “inherits” is a claim, not a test. So I tested it anyway (the 403 case in Step 3). New surface, same checks. That is the habit Part 5 taught me.<\/p>\n\n\n\n
Step 3: Testing it<\/h2>\n\n\n\n
Seven cases, no database<\/h3>\n\n\n\n
Because
match_score<\/code> is a pure function, I could test it with plain lists in the Django shell. No users, no login, no seeding. This alone justified the pure-function design, and it took about a minute:<\/p>\n\n\n\nfrom jobs.matching import match_score\n\ncases = [\n ([\"python\", \"docker\", \"kubernetes\"], [\"Python\", \"docker\", \"aws\"], 67),\n ([\"python\", \"docker\", \"kubernetes\"], [\"python\", \"docker\", \"kubernetes\", \"aws\"], 100),\n ([\"python\", \"docker\"], [\"go\", \"rust\"], 0),\n ([], [\"python\"], None),\n ([\"python\"], [\" python \"], 100),\n ([\"python\", \"docker\"], [\"python\", \"python\"], 50),\n ([\"python\", \"\", \" \"], [\"python\"], 100),\n]\n\nfor required, candidate, expected in cases:\n result = match_score(required, candidate)\n print(required, candidate, \"->\", result, \"expected\", expected, \"OK\" if result == expected else \"FAIL\")<\/code><\/pre>\n\n\n\nThis style is called a table-driven test. Each line is one case: the input and the expected answer. You read it like a table, and adding a new case is adding one line.<\/p>\n\n\n\n
What each case proves:<\/p>\n\n\n\n
- 67: a partial match, and
Python<\/code> matchespython<\/code>. It also checks the rounding of 66.67.<\/li>- 100: the extra skill
aws<\/code> doesn’t change the score.<\/li>- 0: no overlap gives 0, not an error and not None.<\/li>
- None: a job with no required skills gives “no score”, and no division by zero.<\/li>
- 100: spaces around a skill are ignored.<\/li>
- 50: a duplicated
python<\/code> counts once. It is 1 of 2, not 2 of 3.<\/li>- 100: empty entries are ignored. It is 1 of 1, not 1 of 3.<\/li><\/ol>\n\n\n\n
All seven printed OK.<\/p>\n\n\n\n
Through the API<\/h3>\n\n\n\n
Then I checked it end to end. Job 1 (Acme’s) requires
python<\/code>,docker<\/code> andkubernetes<\/code>. Job 3 (Initech’s) requires two different skills. Reading real applications, with tokens, the scores came back inside the application JSON:<\/p>\n\n\n\n- sam reads his application to job 1: 67. He has 2 of the 3 required skills.<\/li>
- Acme lists job 1’s applicants: sam 67, dana 67. dana has
python<\/code> anddocker<\/code>, also 2 of 3. The applications list now shows a score per person, side by side.<\/li>- Initech lists job 3’s applicants: sam 50, riya 50. Each has 1 of the 2 required skills.<\/li>
- dana tries to read sam’s application: 403.<\/li><\/ul>\n\n\n\n
That last one is a regression check. A regression is when something that used to work breaks after a change. Part 5 made applications private; adding a field should not have opened them up again, and it didn’t.<\/p>\n\n\n\n
With these results, the second half of Phase 2’s goal is met: match scores return correctly.<\/p>\n\n\n\n
The decisions, and what they cost<\/h2>\n\n\n\n
No bugs this time. So instead, I want to be honest about the trade-offs I chose, because every one of them has a price I will pay later.<\/p>\n\n\n\n
1. The score is calculated when you read it, not stored.<\/strong><\/p>\n\n\n\n
The score is never saved in the database. It is calculated again every time someone reads an application.<\/p>\n\n\n\n
- The good part: no database migration, and the score is always up to date. If a candidate adds a skill to their profile today, every score changes instantly and correctly.<\/li>
- The cost: the database doesn’t know the score, so I can’t sort or filter by it in SQL. A company can’t ask for “only applicants above 80” without the API first calculating every score in Python. For a small project that is fine. For a big one it is the first thing I would change.<\/li>
- The other option was a stored
match_score<\/code> column, set when the candidate applies. It is sortable, but it goes stale when skills change, unless I also add update logic everywhere skills can change. I chose fresh over sortable, on purpose.<\/li><\/ul>\n\n\n\n2. No required skills means null, not 100.<\/strong><\/p>\n\n\n\n
If a job requires nothing, there is nothing to measure. A score of 100 would look like a perfect match, but it would really mean “we know nothing about this job”. That is misleading to a company making a decision.
null<\/code> is the honest answer: no score exists. The same thinking applies whenever a number is missing: show the gap, don’t invent a value.<\/p>\n\n\n\n3. Only the required skills count.<\/strong><\/p>\n\n\n\n
I considered a different formula called Jaccard similarity: the overlap divided by all skills from both sides combined. It punishes extra skills. For a job board that felt wrong: a candidate who knows
python<\/code>,docker<\/code> and five other things is not a worse fit for apython<\/code> +docker<\/code> job than one who knows exactly two things. My formula asks “of what this job needs, how much do you have?”, which is what a company actually wants to know.<\/p>\n\n\n\n4. No synonyms.<\/strong><\/p>\n\n\n\n
Right now,
k8s<\/code> andkubernetes<\/code> are different skills. Fixing that needs a list of skill names and their aliases, which is a whole data problem of its own. I am leaving it out on purpose: exact, case-insensitive matching is predictable and explainable. A wrong synonym table would quietly change scores and nobody would know why.<\/p>\n\n\n\n5. A whole number, not decimals.<\/strong><\/p>\n\n\n\n
A score of 66.67 suggests a precision that doesn’t really exist. 67 is easier to read, and the rounding rules are simple to explain.<\/p>\n\n\n\n
6. Only the score, no lists.<\/strong><\/p>\n\n\n\n
The API could also return which skills matched and which are missing. That would be useful in a user interface (“you are missing: kubernetes”). But it is also more API surface to design, document and keep consistent. The function already computes
matched<\/code> internally, so adding it later is easy. Deferred, not rejected.<\/p>\n\n\n\nWhat I learned<\/h2>\n\n\n\n
- Keep business rules out of the framework.
matching.py<\/code> imports nothing from Django. That made it the easiest code in the whole project to test, and it will survive any future refactor of views or serializers.<\/li>- Pure functions are a gift to your future self. Two lists in, one number out. No setup, no mocks, no database to clean.<\/li>
- Sets are the right tool for “what do these have in common?”. Duplicates disappear, and & gives the overlap in one symbol. Using lists and loops for this would have been longer and buggier.<\/li>
- None can be the most honest answer. A fake 100 is worse than “no score”.<\/li>
- Calculated vs stored is a real trade-off. Always fresh, but not sortable. Know which one you chose and why.<\/li>
- New fields inherit their object’s permissions, but test it anyway.<\/li>
- Not every framework name fails silently.
get_match_score<\/code> fails loudly if misspelled. Knowing which names shout and which whisper is becoming a theme of this project.<\/li><\/ul>\n\n\n\nWhat comes next<\/h2>\n\n\n\n
Both halves of Phase 2’s goal are now met: wrong user types get 403, and match scores return correctly.<\/p>\n\n\n\n
This is Part 6 of my Job Board API series, in Root Access. The story so far: Part 1 built the foundation, Part 2 designed the data model, Part 3 added JWT signup and login, Part 4 fixed validators that never ran, and Part 5 added the permissions.<\/p>\n\n\n\n
Next: Part 7, filtering and search. Companies will be able to search jobs and filter applications, and the limitations of a score you cannot sort by will stop being theoretical.<\/p>\n\n\n\n
Reza<\/p>\n\n","protected":false},"excerpt":{"rendered":"
Where we are In the last part, I added four permission classes to my Job Board API, so every user can only…<\/p>\n","protected":false},"author":2,"featured_media":238,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_rezaops_part":"6","_rezaops_linkedin_url":"https:\/\/www.linkedin.com\/pulse\/building-job-board-api-part-6-skill-match-score-reza-chegini-iebgc\/","footnotes":""},"categories":[10,116],"tags":[8,111,191,118,192,25,112],"series":[117],"class_list":["post-236","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops","category-django","tag-devops","tag-django","tag-drf","tag-job-board","tag-match-score","tag-python","tag-rest-api","series-job-board-api"],"jetpack_featured_media_url":"https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-6-cover.png","_links":{"self":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/236","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=236"}],"version-history":[{"count":2,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/236\/revisions"}],"predecessor-version":[{"id":240,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/236\/revisions\/240"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/media\/238"}],"wp:attachment":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=236"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=236"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=236"},{"taxonomy":"series","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fseries&post=236"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
- Keep business rules out of the framework.
- 100: the extra skill
- I placed the method at the class level, next to
- DRF finds this method by its name: