sec_id 4.2.0 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58a56c99692f66ae9ff3be10064ab29e729f34d6877456a6c998ee1a3509478d
-  data.tar.gz: ed1ead1827a544b8c48894739916781ea62337aa75e26f7263dd54c08f70b074
+  metadata.gz: d1a703602defc67f745ab0994c73f61d964ed1047a029cc01c2cf7edcda82045
+  data.tar.gz: cf7a004bb992ceb3a9991946d09c908a76d13852c7a87a0b2527a4633da869be
 SHA512:
-  metadata.gz: 437a5b95d0e14cead4d0392dbaa2da4fbc7c3325a01252f17032ca50e9dc3609a6dfe8e73947535de2e2fe228c460c33847635f90c0d99fddf6ff32c66117fbb
-  data.tar.gz: d2e44281f824c033add9074633432291794789b4f1b89e50b5977b1dfd34efd68e5dd2883c7c9076cf5e30316b6a8e487853185824f988827cad61e44e2c38c9
+  metadata.gz: c4e726ce2c1cd7b64dc6d2f8db7e284166ff0229eef52f064975d244e766e28ba239dd8f39dc1730e3b092ae0e57cf982adb683711cde6dd9b15a4bc8c88eb09
+  data.tar.gz: '0986116c63812cc37af215b4f564e3db44d4ea154d90dc49a99e82096fe18e099277087a2b399920e2bf03acbdc69d098b6442c2195d434f2af3230cffe2b257'

data/CHANGELOG.md

@@ -1,16 +1,66 @@
 # Changelog
 
-## [4.2.0] - 2025-01-12
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+## [Unreleased]
+
+## [4.4.0] - 2026-01-29
 
 ### Added
 
-- OCC support ([@wtn](https://github.com/wtn), [#93](https://github.com/svyatov/sec_id/pull/93))
+- Cross-identifier conversions: SEDOL, WKN, and Valoren `to_isin` methods with country code validation; ISIN `to_sedol`, `to_wkn`, `to_valoren` methods with predicate helpers (`sedol?`, `wkn?`, `valoren?`) ([#115](https://github.com/svyatov/sec_id/pull/115))
+- ISIN `nsin_type` and `to_nsin` methods for country-aware NSIN extraction ([#114](https://github.com/svyatov/sec_id/pull/114))
+- CEI (CUSIP Entity Identifier) support for syndicated loan market entity identification ([#113](https://github.com/svyatov/sec_id/pull/113))
+- FISN (Financial Instrument Short Name) support per ISO 18774 ([#112](https://github.com/svyatov/sec_id/pull/112))
+- CFI (Classification of Financial Instruments) support with category/group validation and equity-specific predicates ([#111](https://github.com/svyatov/sec_id/pull/111))
+- Valoren support (Swiss Security Number) ([@wtn](https://github.com/wtn), [#109](https://github.com/svyatov/sec_id/pull/109))
+- WKN support (Wertpapierkennnummer - German securities identifier) ([@wtn](https://github.com/wtn), [#108](https://github.com/svyatov/sec_id/pull/108))
+
+### Changed
+
+- Replaced `has_check_digit` DSL with explicit `Checkable` concern that consolidates all check-digit logic (constants, Luhn algorithms, validation, restoration)
+- Simplified `Base` class to core validation and parsing; check-digit classes now `include Checkable`
+- Non-check-digit classes (CIK, OCC, WKN, Valoren, CFI, FISN) no longer need any special declaration
+- Moved `Normalizable` module to `lib/sec_id/concerns/` for consistency with other concerns
+- Optimized hot paths by replacing `&method(:char_to_digit)` with inline blocks to avoid Method object allocation
+- Added frozen Set constants for ISIN country code lookups (`SEDOL_COUNTRY_CODES`, `VALOREN_COUNTRY_CODES`)
 
 ### Fixed
 
-- CUSIP#cins? usage example in README ([@wtn](https://github.com/wtn), [#91](https://github.com/svyatov/sec_id/pull/91))
+- Allow Crown Dependencies (GG, IM, JE) and Overseas Territories (FK) in SEDOL/ISIN conversions ([@wtn](https://github.com/wtn), [#117](https://github.com/svyatov/sec_id/pull/117))
+- Removed BR (Brazil) from CGS country codes — Brazil never used CINS numbers and Brazilian ISINs cannot be converted to CUSIP ([@wtn](https://github.com/wtn), [#110](https://github.com/svyatov/sec_id/pull/110))
 
-### Updated
+## [4.3.0] - 2025-01-13
+
+### Added
+
+- LEI support (Legal Entity Identifier, ISO 17442)
+- IBAN support (International Bank Account Number, ISO 13616) with EU/EEA country validation
+
+### Changed
+
+- Improved README: better formatting, navigation, and clear API distinction between check-digit and normalization identifiers
+- Refactored CIK and OCC to inherit from Base class with `has_check_digit?` hook for cleaner architecture
+- Added `Normalizable` module for consistent `normalize!` class method across identifiers
+- Added `validate_format_for_calculation!` helper method to Base class to reduce code duplication
+- Added comprehensive YARD documentation to all classes (public and private methods)
+- Applied Stepdown Rule to method ordering throughout codebase
+- Created shared RSpec examples for edge cases (nil, empty, whitespace inputs)
+- Created shared RSpec examples for check-digit and normalization identifiers
+- Applied shared examples to all identifier specs, removing ~350 lines of duplicate test code
+- Improved test maintainability with 582 tests covering all identifier types
+
+## [4.2.0] - 2025-01-12
+
+### Added
+
+- OCC support ([@wtn](https://github.com/wtn), [#93](https://github.com/svyatov/sec_id/pull/93))
+
+### Changed
 
 - Separate CIK from Base for cleaner architecture ([@wtn](https://github.com/wtn), [#92](https://github.com/svyatov/sec_id/pull/92))
 - Use rubocop-rspec plugin ([@wtn](https://github.com/wtn), [#90](https://github.com/svyatov/sec_id/pull/90))
@@ -18,6 +68,10 @@
 - Add permissions to CI workflow
 - Clean up gemspec: update description and simplify files list
 
+### Fixed
+
+- CUSIP#cins? usage example in README ([@wtn](https://github.com/wtn), [#91](https://github.com/svyatov/sec_id/pull/91))
+
 ## [4.1.0] - 2024-09-23
 
 ### Added
@@ -27,19 +81,16 @@
 - Convert between CUSIPs and ISINs ([@wtn](https://github.com/wtn), [#86](https://github.com/svyatov/sec_id/pull/86), [#88](https://github.com/svyatov/sec_id/pull/88))
 - CINS check method for CUSIPs ([@wtn](https://github.com/wtn), [#87](https://github.com/svyatov/sec_id/pull/87))
 
-### Updated
+### Changed
 
 - Small internal refactorings
 
 ## [4.0.0] - 2024-07-09
 
-### Breaking changes
-
-- Minimum required Ruby version is 3.1 now
-- Default repository branch renamed to `main`
-
-### Updated
+### Changed
 
+- **BREAKING:** Minimum required Ruby version is 3.1 now
+- **BREAKING:** Default repository branch renamed to `main`
 - Small internal refactorings
 - TravisCI -> GitHub Actions
 - Dropped tests for Ruby below 3.1
@@ -47,12 +98,9 @@
 
 ## [3.0.0] - 2020-03-10
 
-### Breaking changes
-
-- Minimum required Ruby version is 2.5 now
-
-### Updated
+### Changed
 
+- **BREAKING:** Minimum required Ruby version is 2.5 now
 - Small internal refactorings
 - TravisCI config updated: dropped Ruby 2.3 and 2.4, added Ruby 2.7
 - Rubocop's Ruby target version changed to 2.5
@@ -63,11 +111,9 @@
 
 - SEDOL numbers support: `SecId::SEDOL`
 
-### Updated
-
-- **Breaking change**
+### Changed
 
-    API for accessing full number is unified across all classes:
+- **BREAKING:** API for accessing full number is unified across all classes:
 
     ```
     SecId::ISIN#full_number  # previously SecId::ISIN#isin
@@ -86,7 +132,7 @@
 - CUSIP numbers support: `SecId::CUSIP`
 - CHANGELOG.md file added
 
-### Updated
+### Changed
 
 - Char to digit conversion now uses precalculated tables instead of dynamic calculation for speed
 

data/README.md

@@ -1,104 +1,69 @@
-# SecId
-[![Gem Version](https://badge.fury.io/rb/sec_id.svg)](https://badge.fury.io/rb/sec_id)
-[![codecov](https://codecov.io/gh/svyatov/sec_id/graph/badge.svg)](https://codecov.io/gh/svyatov/sec_id)
-![Build Status](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg?branch=main)
-
-Validate securities identification numbers with ease!
-
-Check-digit calculation is also available.
-
-Currently supported standards:
-[ISIN](https://en.wikipedia.org/wiki/International_Securities_Identification_Number),
-[CUSIP](https://en.wikipedia.org/wiki/CUSIP),
-[SEDOL](https://en.wikipedia.org/wiki/SEDOL),
-[FIGI](https://en.wikipedia.org/wiki/Financial_Instrument_Global_Identifier),
-[CIK](https://en.wikipedia.org/wiki/Central_Index_Key),
-[OCC](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol).
-
-Work in progress:
-[IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number).
+# SecId [![Gem Version](https://img.shields.io/gem/v/sec_id)](https://rubygems.org/gems/sec_id) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/sec_id)](https://app.codecov.io/gh/svyatov/sec_id) [![CI](https://github.com/svyatov/sec_id/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/sec_id/actions?query=workflow%3ACI)
+
+> Validate securities identification numbers with ease!
+
+## Table of Contents
+
+- [Supported Ruby Versions](#supported-ruby-versions)
+- [Installation](#installation)
+- [Supported Standards and Usage](#supported-standards-and-usage)
+  - [ISIN](#isin) - International Securities Identification Number
+  - [CUSIP](#cusip) - Committee on Uniform Securities Identification Procedures
+  - [CEI](#cei) - CUSIP Entity Identifier
+  - [SEDOL](#sedol) - Stock Exchange Daily Official List
+  - [FIGI](#figi) - Financial Instrument Global Identifier
+  - [LEI](#lei) - Legal Entity Identifier
+  - [IBAN](#iban) - International Bank Account Number
+  - [CIK](#cik) - Central Index Key
+  - [OCC](#occ) - Options Clearing Corporation Symbol
+  - [WKN](#wkn) - Wertpapierkennnummer
+  - [Valoren](#valoren) - Swiss Security Number
+  - [CFI](#cfi) - Classification of Financial Instruments
+  - [FISN](#fisn) - Financial Instrument Short Name
+- [Development](#development)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+- [Versioning](#versioning)
+- [License](#license)
+
+## Supported Ruby Versions
+
+Ruby 3.1+ is required.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 4.2'
+gem 'sec_id', '~> 4.4'
 ```
 
 And then execute:
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install sec_id
-
-## Usage
-
-### Base API
-
-Base API has 4 main methods which can be used both on class level and on instance level:
-
-* `valid?` - never raises any errors, always returns `true` or `false`,
-  numbers without the check-digit will return `false`
-
-  ```ruby
-  # class level
-  SecId::ISIN.valid?('US5949181045') # => true
-  SecId::ISIN.valid?('US594918104')  # => false
-
-  # instance level
-  isin = SecId::ISIN.new('US5949181045')
-  isin.valid? # => true
-  ```
-
-* `valid_format?` - never raises any errors, always returns `true` or `false`,
-  numbers without the check-digit but in valid format will return `true`
-
-  ```ruby
-  # class level
-  SecId::ISIN.valid_format?('US5949181045') # => true
-  SecId::ISIN.valid_format?('US594918104') # => true
-
-  # instance level
-  isin = SecId::ISIN.new('US594918104')
-  isin.valid_format? # => true
-  ```
+```bash
+bundle install
+```
 
-* `restore!` - restores check-digit and returns the full number,
-  raises an error if number's format is invalid and thus check-digit is impossible to calculate
+Or install it yourself:
 
-  ```ruby
-  # class level
-  SecId::ISIN.restore!('US594918104') # => 'US5949181045'
+```bash
+gem install sec_id
+```
 
-  # instance level
-  isin = SecId::ISIN.new('US5949181045')
-  isin.restore! # => 'US5949181045'
-  ```
+## Supported Standards and Usage
 
-* `check_digit` and `calculate_check_digit` - these are the same,
-  but the former is used at class level for bravity,
-  and the latter is used at instance level for clarity;
-  it calculates and returns the check-digit if the number is valid
-  and raises an error otherwise.
+All identifier classes provide `valid?` and `valid_format?` methods at both class and instance levels.
 
-  ```ruby
-  # class level
-  SecId::ISIN.check_digit('US594918104') # => 5
+**Check-digit based identifiers** (ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN) also provide:
+- `restore!` - restores check-digit and returns the full number
+- `check_digit` / `calculate_check_digit` - calculates and returns the check-digit
 
-  # instance level
-  isin = SecId::ISIN.new('US594918104')
-  isin.calculate_check_digit # => 5
-  isin.check_digit # => nil
-  ```
+**Normalization based identifiers** (CIK, OCC, Valoren) provide instead:
+- `normalize!` - pads/formats the identifier to its standard form
 
-  :exclamation: Please note that `isin.check_digit` returns `nil` because `#check_digit`
-  at instance level represents original check-digit of the number passed to `new`,
-  which in this example is missing and thus it's `nil`.
+### ISIN
 
-### SecId::ISIN full example
+> [International Securities Identification Number](https://en.wikipedia.org/wiki/International_Securities_Identification_Number) - a 12-character alphanumeric code that uniquely identifies a security.
 
 ```ruby
 # class level
@@ -118,16 +83,38 @@ isin.valid_format?         # => true
 isin.restore!              # => 'US5949181045'
 isin.calculate_check_digit # => 5
 isin.to_cusip              # => #<SecId::CUSIP>
+isin.nsin_type             # => :cusip
+isin.to_nsin               # => #<SecId::CUSIP>
+
+# NSIN extraction for different countries
+SecId::ISIN.new('GB00B02H2F76').nsin_type  # => :sedol
+SecId::ISIN.new('GB00B02H2F76').to_nsin    # => #<SecId::SEDOL>
+SecId::ISIN.new('DE0007164600').nsin_type  # => :wkn
+SecId::ISIN.new('DE0007164600').to_nsin    # => #<SecId::WKN>
+SecId::ISIN.new('CH0012221716').nsin_type  # => :valoren
+SecId::ISIN.new('CH0012221716').to_nsin    # => #<SecId::Valoren>
+SecId::ISIN.new('FR0000120271').nsin_type  # => :generic
+SecId::ISIN.new('FR0000120271').to_nsin    # => '000012027' (raw NSIN string)
+
+# Type-specific conversion methods with validation
+SecId::ISIN.new('GB00B02H2F76').sedol?     # => true
+SecId::ISIN.new('GB00B02H2F76').to_sedol   # => #<SecId::SEDOL>
+SecId::ISIN.new('DE0007164600').wkn?       # => true
+SecId::ISIN.new('DE0007164600').to_wkn     # => #<SecId::WKN>
+SecId::ISIN.new('CH0012221716').valoren?   # => true
+SecId::ISIN.new('CH0012221716').to_valoren # => #<SecId::Valoren>
 ```
 
-### SecId::CUSIP full example
+### CUSIP
+
+> [Committee on Uniform Securities Identification Procedures](https://en.wikipedia.org/wiki/CUSIP) - a 9-character alphanumeric code that identifies North American securities.
 
 ```ruby
 # class level
 SecId::CUSIP.valid?('594918104')       # => true
 SecId::CUSIP.valid_format?('59491810') # => true
 SecId::CUSIP.restore!('59491810')      # => '594918104'
-SecId::CUSIP.check_digit('59491810')   # => 5
+SecId::CUSIP.check_digit('59491810')   # => 4
 
 # instance level
 cusip = SecId::CUSIP.new('594918104')
@@ -143,7 +130,33 @@ cusip.to_isin('US')         # => #<SecId::ISIN>
 cusip.cins?                 # => false
 ```
 
-### SecId::SEDOL full example
+### CEI
+
+> [CUSIP Entity Identifier](https://www.cusip.com/identifiers.html) - a 10-character alphanumeric code that identifies legal entities in the syndicated loan market.
+
+```ruby
+# class level
+SecId::CEI.valid?('A0BCDEFGH1')       # => true
+SecId::CEI.valid_format?('A0BCDEFGH') # => true
+SecId::CEI.restore!('A0BCDEFGH')      # => 'A0BCDEFGH1'
+SecId::CEI.check_digit('A0BCDEFGH')   # => 1
+
+# instance level
+cei = SecId::CEI.new('A0BCDEFGH1')
+cei.full_number           # => 'A0BCDEFGH1'
+cei.prefix                # => 'A'
+cei.numeric               # => '0'
+cei.entity_id             # => 'BCDEFGH'
+cei.check_digit           # => 1
+cei.valid?                # => true
+cei.valid_format?         # => true
+cei.restore!              # => 'A0BCDEFGH1'
+cei.calculate_check_digit # => 1
+```
+
+### SEDOL
+
+> [Stock Exchange Daily Official List](https://en.wikipedia.org/wiki/SEDOL) - a 7-character alphanumeric code used in the United Kingdom, Ireland, Crown Dependencies (Jersey, Guernsey, Isle of Man), and select British Overseas Territories.
 
 ```ruby
 # class level
@@ -153,16 +166,20 @@ SecId::SEDOL.restore!('B0Z52W')      # => 'B0Z52W5'
 SecId::SEDOL.check_digit('B0Z52W')   # => 5
 
 # instance level
-cusip = SecId::SEDOL.new('B0Z52W5')
-cusip.full_number           # => 'B0Z52W5'
-cusip.check_digit           # => 5
-cusip.valid?                # => true
-cusip.valid_format?         # => true
-cusip.restore!              # => 'B0Z52W5'
-cusip.calculate_check_digit # => 5
+sedol = SecId::SEDOL.new('B0Z52W5')
+sedol.full_number           # => 'B0Z52W5'
+sedol.check_digit           # => 5
+sedol.valid?                # => true
+sedol.valid_format?         # => true
+sedol.restore!              # => 'B0Z52W5'
+sedol.calculate_check_digit # => 5
+sedol.to_isin               # => #<SecId::ISIN> (GB ISIN by default)
+sedol.to_isin('IE')         # => #<SecId::ISIN> (IE ISIN)
 ```
 
-### SecId::FIGI full example
+### FIGI
+
+> [Financial Instrument Global Identifier](https://en.wikipedia.org/wiki/Financial_Instrument_Global_Identifier) - a 12-character alphanumeric code that provides unique identification of financial instruments.
 
 ```ruby
 # class level
@@ -183,7 +200,61 @@ figi.restore!              # => 'BBG000DMBXR2'
 figi.calculate_check_digit # => 2
 ```
 
-### SecId::CIK full example
+### LEI
+
+> [Legal Entity Identifier](https://en.wikipedia.org/wiki/Legal_Entity_Identifier) - a 20-character alphanumeric code that uniquely identifies legal entities participating in financial transactions.
+
+```ruby
+# class level
+SecId::LEI.valid?('5493006MHB84DD0ZWV18')       # => true
+SecId::LEI.valid_format?('5493006MHB84DD0ZWV')  # => true
+SecId::LEI.restore!('5493006MHB84DD0ZWV')       # => '5493006MHB84DD0ZWV18'
+SecId::LEI.check_digit('5493006MHB84DD0ZWV')    # => 18
+
+# instance level
+lei = SecId::LEI.new('5493006MHB84DD0ZWV18')
+lei.full_number           # => '5493006MHB84DD0ZWV18'
+lei.lou_id                # => '5493'
+lei.reserved              # => '00'
+lei.entity_id             # => '6MHB84DD0ZWV'
+lei.check_digit           # => 18
+lei.valid?                # => true
+lei.valid_format?         # => true
+lei.restore!              # => '5493006MHB84DD0ZWV18'
+lei.calculate_check_digit # => 18
+```
+
+### IBAN
+
+> [International Bank Account Number](https://en.wikipedia.org/wiki/International_Bank_Account_Number) - an internationally standardized system for identifying bank accounts across national borders (ISO 13616).
+
+```ruby
+# class level
+SecId::IBAN.valid?('DE89370400440532013000')       # => true
+SecId::IBAN.valid_format?('DE370400440532013000')  # => true
+SecId::IBAN.restore!('DE370400440532013000')       # => 'DE89370400440532013000'
+SecId::IBAN.check_digit('DE370400440532013000')    # => 89
+
+# instance level
+iban = SecId::IBAN.new('DE89370400440532013000')
+iban.full_number           # => 'DE89370400440532013000'
+iban.country_code          # => 'DE'
+iban.bban                  # => '370400440532013000'
+iban.bank_code             # => '37040044'
+iban.account_number        # => '0532013000'
+iban.check_digit           # => 89
+iban.valid?                # => true
+iban.valid_format?         # => true
+iban.restore!              # => 'DE89370400440532013000'
+iban.calculate_check_digit # => 89
+iban.known_country?        # => true
+```
+
+Full BBAN structural validation is supported for EU/EEA countries. Other countries have length-only validation.
+
+### CIK
+
+> [Central Index Key](https://en.wikipedia.org/wiki/Central_Index_Key) - a 10-digit number used by the SEC to identify corporations and individuals who have filed disclosures.
 
 ```ruby
 # class level
@@ -202,7 +273,9 @@ cik.normalize!    # => '0001094517'
 cik.to_s          # => '0001094517'
 ```
 
-### SecId::OCC full example
+### OCC
+
+> [Options Clearing Corporation Symbol](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol) - a 21-character code used to identify equity options contracts.
 
 ```ruby
 # class level
@@ -239,18 +312,132 @@ occ.normalize!    # => 'X     250620C00050000'
 occ.full_symbol   # => 'X     250620C00050000'
 ```
 
+### WKN
+
+> [Wertpapierkennnummer](https://en.wikipedia.org/wiki/Wertpapierkennnummer) - a 6-character alphanumeric code used to identify securities in Germany.
+
+```ruby
+# class level
+SecId::WKN.valid?('514000')        # => true
+SecId::WKN.valid?('CBK100')        # => true
+SecId::WKN.valid_format?('514000') # => true
+
+# instance level
+wkn = SecId::WKN.new('514000')
+wkn.full_number   # => '514000'
+wkn.identifier    # => '514000'
+wkn.valid?        # => true
+wkn.valid_format? # => true
+wkn.to_s          # => '514000'
+wkn.to_isin       # => #<SecId::ISIN> (DE ISIN)
+```
+
+WKN excludes letters I and O to avoid confusion with digits 1 and 0.
+
+### Valoren
+
+> [Valoren](https://en.wikipedia.org/wiki/Valoren_number) - a numeric identifier for securities in Switzerland, Liechtenstein, and Belgium.
+
+```ruby
+# class level
+SecId::Valoren.valid?('3886335')        # => true
+SecId::Valoren.valid?('24476758')       # => true
+SecId::Valoren.valid?('35514757')       # => true
+SecId::Valoren.valid?('97429325')       # => true
+SecId::Valoren.valid_format?('3886335') # => true
+SecId::Valoren.normalize!('3886335')    # => '003886335'
+
+# instance level
+valoren = SecId::Valoren.new('3886335')
+valoren.full_number   # => '3886335'
+valoren.padding       # => ''
+valoren.identifier    # => '3886335'
+valoren.valid?        # => true
+valoren.valid_format? # => true
+valoren.normalize!    # => '003886335'
+valoren.to_s          # => '003886335'
+valoren.to_isin       # => #<SecId::ISIN> (CH ISIN by default)
+valoren.to_isin('LI') # => #<SecId::ISIN> (LI ISIN)
+```
+
+### CFI
+
+> [Classification of Financial Instruments](https://en.wikipedia.org/wiki/ISO_10962) - a 6-character alphabetic code that classifies financial instruments per ISO 10962.
+
+```ruby
+# class level
+SecId::CFI.valid?('ESXXXX')        # => true
+SecId::CFI.valid?('ESVUFR')        # => true
+SecId::CFI.valid_format?('ESXXXX') # => true
+
+# instance level
+cfi = SecId::CFI.new('ESVUFR')
+cfi.full_number    # => 'ESVUFR'
+cfi.identifier     # => 'ESVUFR'
+cfi.category_code  # => 'E'
+cfi.group_code     # => 'S'
+cfi.category       # => :equity
+cfi.group          # => :common_shares
+cfi.valid?         # => true
+cfi.valid_format?  # => true
+
+# Equity-specific predicates
+cfi.equity?        # => true
+cfi.voting?        # => true
+cfi.restrictions?  # => false
+cfi.fully_paid?    # => true
+cfi.registered?    # => true
+```
+
+CFI validates the category code (position 1) against 14 valid values and the group code (position 2) against valid values for that category. Attribute positions 3-6 accept any letter A-Z, with X meaning "not applicable".
+
+### FISN
+
+> [Financial Instrument Short Name](https://en.wikipedia.org/wiki/ISO_18774) - a human-readable short name for financial instruments per ISO 18774.
+
+```ruby
+# class level
+SecId::FISN.valid?('APPLE INC/SH')        # => true
+SecId::FISN.valid?('apple inc/sh')        # => true (normalized to uppercase)
+SecId::FISN.valid_format?('APPLE INC/SH') # => true
+
+# instance level
+fisn = SecId::FISN.new('APPLE INC/SH')
+fisn.full_number   # => 'APPLE INC/SH'
+fisn.identifier    # => 'APPLE INC/SH'
+fisn.issuer        # => 'APPLE INC'
+fisn.description   # => 'SH'
+fisn.valid?        # => true
+fisn.valid_format? # => true
+fisn.to_s          # => 'APPLE INC/SH'
+```
+
+FISN format: `Issuer Name/Abbreviated Instrument Description` with issuer (1-15 chars) and description (1-19 chars) separated by a forward slash. Character set: uppercase A-Z, digits 0-9, and space.
+
 ## Development
 
 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`
+Then, run `bundle exec rake` 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`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on
-GitHub at https://github.com/svyatov/sec_id.
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Make your changes and run tests (`bundle exec rake`)
+4. Commit using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format (`git commit -m 'feat: add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes, following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## Versioning
+
+This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
 
 ## License