A Sri Lankan National Identity Card number looks random, but most of it is a birth date written in a slightly odd way. I wrote a decoder for it, and the interesting part was not the parsing. It was a calendar quirk that makes a naive date conversion wrong for most of the year.
This post walks through the layout, the quirk, and the line the code has to draw between "well formed" and "real". The code is TypeScript from my NIC decoder.
Two layouts
The old card has 9 digits and a letter, V or X. The new one has 12 digits.
old, 9 digits and V or X: YY DDD SSS C (V|X)
new, 12 digits: YYYY DDD SSSS C
-
YYorYYYYis the birth year. The old layout only has two digits, so it always means a 1900s year. -
DDDis the day of the year, with 500 added for women. -
Sis a serial number. -
Cis a check digit.
Converting old to new is "19" + YY + DDD + "0" + SSS + C. The serial grows from three digits to four, so the new form pads it with a zero.
One caveat before going further. This layout is documented by Wikipedia and by open-source NIC libraries. I could not find an official specification from the Department for Registration of Persons, and the code's header comment says so. Treat the layout as well established but not official.
Gender is a number added to the day
There is no gender field. A woman's day code has 500 added to it. So the code does this:
const code = Number(dayCode);
const female = code > 500;
const day = female ? code - 500 : code;
Running the real code, 856202345V gives a female born on 1985-04-29: the day code is 620, so the day is 120.
The February quirk
This is the part that matters most. The day count behaves as if February always has 29 days. Day 60 is 29 February. Day 61 is 1 March, in every year, leap or not.
In a leap year that matches the real calendar. In a non-leap year it does not: from 1 March on, the real day of the year is one less than the code. So the conversion has to branch:
const doy = isLeap(year) ? day : day > 60 ? day - 1 : day;
const d = new Date(Date.UTC(year, 0, doy));
Date.UTC(year, 0, n) treats day 1 of January as n = 1 and rolls over into later months, which is a handy way to turn a day of year into a date. I use UTC so the result does not depend on the server's time zone.
Here is what the decoder printed for the same day code in different years (I ran these, with "now" fixed at 2026-11-16 so the output is repeatable):
200006112340 true Male 2000-03-01
199906112340 true Male 1999-03-01
200006012340 true Male 2000-02-29
199906012340 false Male (none) Day 60 is 29 February, which does not exist in 1999.
199936612340 true Male 1999-12-31
200036612340 true Male 2000-12-31
200036712340 false Male (none) The day number 367 is outside 1 to 366.
Day code 061 is 1 March in both years, even though 1 March is the 60th day of 1999. Day code 366 is 31 December in both years too: in 1999 the code is 366 but the real day of the year is 365. If you skipped the adjustment, every non-leap-year birthday from March to December would be off by one day, and 31 December would land on 1 January of the next year.
Day 60 in a non-leap year is the one code that can never be a real birthday, so it is rejected with its own message. Anything outside 1 to 366 is rejected too, as is day 0.
Validation as a list of issues
Rather than return a boolean, the parser collects issues strings and sets valid only if the list is empty. The checks are:
- the shape:
^\d{9}[VX]$or^\d{12}$after stripping spaces and upper-casing - the year is between 1900 and the current year
- the day number is in range, and not 29 February in a non-leap year
- the birth date is not in the future
A list is more useful to the person typing than a bare "invalid". Pasting 8532023450 (no letter) gives "A NIC is 9 digits followed by V or X, or 12 digits." and nothing else, because without a known layout there is nothing further to say.
The same function backs a small public endpoint, /api/v1/nic/{number}. It limits the input to 20 characters and returns the decoded fields only when the number is valid.
The check digit is not published
The last digit of the number is a check digit. I do not know its algorithm, and as far as I can tell it is not public. So the code shows the digit and never verifies it. The header comment states the consequence plainly:
a "valid" result means the number is well formed and describes a possible birth date, not that the card exists.
The API repeats it in every response: "Checks the format and decodes it. It does not prove that a card was issued: the check digit is not published."
This matters. A birth date and a serial number in range are easy to fake or mistype into something that parses. The decoder can tell you that a number is impossible (wrong length, 29 February 1999). It cannot tell you that a number is genuine. Anything that needs real identity verification has to go through the issuing authority, not a regex.
The 12-to-9 conversion has a similar limit. A new-format number has no V or X, and the old suffix cannot be recovered from the number. The code guesses V, which it notes is the usual one, and only offers a conversion when the birth year is in the 1900s and the serial starts with 0.
What I would reuse from this
- Write down the calendar rules a format assumes. "Day of year" sounds standard, but here February is always 29 days.
- Use
Date.UTCwith a month of 0 and a day count to convert day-of-year to a date, and keep everything in UTC. - Return a list of reasons instead of a boolean.
- Say in the output what a "valid" result does and does not mean.
The leap-year branch is the easiest thing to get subtly wrong, so the cases above are the ones worth keeping as tests.
Have you run into an ID or date format that quietly breaks a standard assumption, like a fixed-length February? How did you find it?
This article was written with the help of AI. The code, numbers and sources come from my own project and were checked against it before publishing.
Top comments (0)