A simple gem for working with South African ID numbers.

South African ID numbers have a fair amount of information serialized into them, including an all important checksum number. The below information is taken from a page deep within The Western Cape Government's website.

A South African ID number is a 13-digit number which is defined by the following format: YYMMDDSSSSCAZ.

• The first 6 digits (YYMMDD) are based on your date of birth. 20 February 1992 is displayed as 920220.
• The next 4 digits (SSSS) are used to define your gender. Females are assigned numbers in the range 0000-4999 and males from 5000-9999.
• The next digit (C) shows if you're a ZA citizen status, with 0 denoting that you were born a ZA citizen, 1 denoting that you're a permanent resident and 2 denoting that you're a refugee.
• The last digit (Z) is a checksum digit – used to check that the number sequence is accurate using a set formula called the Luhn algorithm.

The graphic below details the different sections of an ID number, based on the fictitious sequence 9202204720082

Add this line to your application's Gemfile:

gem 'za_id_number'

And then execute:

$ bundle

Or install it yourself as:

$ gem install za_id_number

Given a valid ZA ID Number, 7501151234085, the following interface is available:

id_number = ZAIDNumber.new('7501151234085') # => #<ZAIDNumber:0x00d40 @id_number="75011...

id_num.valid_length?      # => true
id_num.only_digits?       # => true
id_num.valid_date?        # => true
id_num.valid_citizenship? # => true
id_num.valid_checksum?    # => true

Or, roll up all those validation checks into one call:

id_number.valid? # => true

You can also use this gem to extract information embedded in the ID number as per the infographic above.

id_num.date_of_birth       # => #<Date: 1975-01-15 ((2442428j,0s,0n),+0s,2299161j)>
id_num.gender              # => :f
id_num.female?             # => true
id_num.male?               # => false
id_num.citizenship         # => :za_citizen
id_num.za_citizen?         # => true
id_num.permanent_resident? # => false
id_num.refugee?            # => false

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/zero-one-software/za_id_number. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.