sec_id 4.4.1 → 5.1.0

data/README.md

@@ -1,4 +1,4 @@
-# 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)
+# 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!
 
@@ -7,6 +7,8 @@
 - [Supported Ruby Versions](#supported-ruby-versions)
 - [Installation](#installation)
 - [Supported Standards and Usage](#supported-standards-and-usage)
+  - [Metadata Registry](#metadata-registry) - enumerate, filter, look up, and detect identifier types
+  - [Structured Validation](#structured-validation) - detailed error codes and messages
   - [ISIN](#isin) - International Securities Identification Number
   - [CUSIP](#cusip) - Committee on Uniform Securities Identification Procedures
   - [CEI](#cei) - CUSIP Entity Identifier
@@ -20,6 +22,7 @@
   - [Valoren](#valoren) - Swiss Security Number
   - [CFI](#cfi) - Classification of Financial Instruments
   - [FISN](#fisn) - Financial Instrument Short Name
+- [Lookup Service Integration](#lookup-service-integration)
 - [Development](#development)
 - [Contributing](#contributing)
 - [Changelog](#changelog)
@@ -28,14 +31,14 @@
 
 ## Supported Ruby Versions
 
-Ruby 3.1+ is required.
+Ruby 3.2+ is required.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sec_id', '~> 4.4'
+gem 'sec_id', '~> 5.1'
 ```
 
 And then execute:
@@ -50,16 +53,152 @@ Or install it yourself:
 gem install sec_id
 ```
 
+**Upgrading from v4?** See [MIGRATION.md](MIGRATION.md) for a step-by-step guide.
+
 ## Supported Standards and Usage
 
-All identifier classes provide `valid?` and `valid_format?` methods at both class and instance levels.
+All identifier classes provide `valid?`, `errors`, `validate`, `validate!` methods at both class and instance levels.
+
+**All identifiers** support normalization and display formatting:
+- `.normalize(id)` - strips separators, upcases, validates, and returns the canonical string
+- `#normalized` / `#normalize` - returns the canonical string for a valid instance
+- `#normalize!` - mutates `full_id` to canonical form, returns `self`
+- `#to_pretty_s` / `.to_pretty_s(id)` - returns a human-readable formatted string, or `nil` for invalid input
+
+**All identifiers** support hash serialization:
+- `#to_h` - returns a hash with `:type`, `:full_id`, `:normalized`, `:valid`, and `:components` keys
+
+```ruby
+SecID::ISIN.new('US5949181045').to_h
+# => { type: :isin, full_id: 'US5949181045', normalized: 'US5949181045',
+#      valid: true, components: { country_code: 'US', nsin: '594918104', check_digit: 5 } }
+
+SecID::ISIN.new('INVALID').to_h
+# => { type: :isin, full_id: 'INVALID', normalized: nil,
+#      valid: false, components: { country_code: nil, nsin: nil, check_digit: nil } }
+```
+
+**All identifiers** support value equality — two instances of the same type with the same normalized form are equal:
+
+```ruby
+a = SecID::ISIN.new('US5949181045')
+b = SecID::ISIN.new('us 5949 1810 45')
+
+a == b  # => true
+a.eql?(b) # => true
+
+# Works as Hash keys and in Sets
+{ a => 'MSFT' }[b]          # => 'MSFT'
+Set.new([a, b]).size         # => 1
+```
 
 **Check-digit based identifiers** (ISIN, CUSIP, CEI, SEDOL, FIGI, LEI, IBAN) also provide:
-- `restore!` - restores check-digit and returns the full number
+- `restore` / `.restore` - returns the full identifier string with correct check-digit (no mutation)
+- `restore!` / `.restore!` - restores check-digit in place and returns `self` / instance
 - `check_digit` / `calculate_check_digit` - calculates and returns the check-digit
 
-**Normalization based identifiers** (CIK, OCC, Valoren) provide instead:
-- `normalize!` - pads/formats the identifier to its standard form
+### Metadata Registry
+
+All identifier classes are registered automatically and can be enumerated, filtered, and looked up by symbol key:
+
+```ruby
+# Look up by symbol key
+SecID[:isin]                              # => SecID::ISIN
+SecID[:cusip]                             # => SecID::CUSIP
+
+# Enumerate all identifier classes
+SecID.identifiers                         # => [SecID::ISIN, SecID::CUSIP, ...]
+SecID.identifiers.map(&:short_name)       # => ["ISIN", "CUSIP", "SEDOL", ...]
+
+# Query metadata
+SecID::ISIN.short_name                    # => "ISIN"
+SecID::ISIN.full_name                     # => "International Securities Identification Number"
+SecID::ISIN.id_length                     # => 12
+SecID::ISIN.example                       # => "US5949181045"
+SecID::ISIN.has_check_digit?              # => true
+
+# Filter with standard Ruby
+SecID.identifiers.select(&:has_check_digit?).map(&:short_name)
+# => ["ISIN", "CUSIP", "SEDOL", "FIGI", "LEI", "IBAN", "CEI"]
+
+# Detect identifier type from an unknown string
+# Results are sorted by specificity: check-digit types first, then by length precision
+SecID.detect('US5949181045')  # => [:isin]
+SecID.detect('037833100')     # => [:cusip, :valoren, :cik]
+SecID.detect('APPLE INC/SH')  # => [:fisn]
+SecID.detect('INVALID')       # => []
+
+# Quick boolean validation
+SecID.valid?('US5949181045')                      # => true (any type)
+SecID.valid?('INVALID')                           # => false
+SecID.valid?('US5949181045', types: [:isin])      # => true
+SecID.valid?('594918104', types: %i[cusip sedol]) # => true
+SecID.valid?('US5949181045', types: [:cusip])     # => false
+
+# Parse into a typed instance (returns the most specific match)
+SecID.parse('US5949181045')                       # => #<SecID::ISIN>
+SecID.parse('594918104')                          # => #<SecID::CUSIP>
+SecID.parse('unknown')                            # => nil
+SecID.parse('594918104', types: [:cusip])         # => #<SecID::CUSIP>
+
+# Bang version raises on failure
+SecID.parse!('US5949181045')                      # => #<SecID::ISIN>
+SecID.parse!('unknown')                           # raises SecID::InvalidFormatError
+```
+
+### Structured Validation
+
+All identifier classes provide a Rails-like `#errors` API for detailed error reporting:
+
+```ruby
+isin = SecID::ISIN.new('US5949181040')
+isin.errors.none?     # => false
+isin.errors.messages  # => ["Check digit '0' is invalid, expected '5'"]
+isin.errors.details   # => [{ error: :invalid_check_digit, message: "Check digit '0' is invalid, expected '5'" }]
+isin.errors.any?      # => true
+isin.errors.empty?    # => false
+isin.errors.size      # => 1
+isin.errors.to_a      # => same as messages
+
+# Class-level convenience method (returns the instance with errors cached)
+SecID::ISIN.validate('US5949181040')         # => #<SecID::ISIN>
+SecID::ISIN.validate('US5949181040').errors   # => #<SecID::Errors>
+```
+
+**Common error codes** (all identifier types):
+- `:invalid_length` - wrong number of characters
+- `:invalid_characters` - contains characters not allowed for this type
+- `:invalid_format` - correct length and characters but wrong structure
+
+**Type-specific error codes:**
+- `:invalid_check_digit` - check digit mismatch (ISIN, CUSIP, SEDOL, FIGI, LEI, IBAN, CEI)
+- `:invalid_prefix` - restricted FIGI prefix (FIGI)
+- `:invalid_category` - unknown CFI category code (CFI)
+- `:invalid_group` - unknown CFI group code for category (CFI)
+- `:invalid_bban` - BBAN format invalid for country (IBAN)
+- `:invalid_date` - unparseable expiration date (OCC)
+
+#### Fail-fast validation with `validate!`
+
+Use `validate!` when you want to raise an exception on invalid input instead of inspecting errors:
+
+```ruby
+# Returns self when valid (enables chaining)
+SecID::ISIN.new('US5949181045').validate!  # => #<SecID::ISIN>
+
+# Raises with a descriptive message when invalid
+SecID::ISIN.new('INVALID').validate!
+# => SecID::InvalidFormatError: Expected 12 characters, got 7
+
+SecID::ISIN.new('US5949181040').validate!
+# => SecID::InvalidCheckDigitError: Check digit '0' is invalid, expected '5'
+
+SecID::FIGI.new('BSG000BLNNH6').validate!
+# => SecID::InvalidStructureError: Prefix 'BS' is restricted
+
+# Class-level convenience method (returns the instance)
+isin = SecID::ISIN.validate!('US5949181045')  # => #<SecID::ISIN>
+```
 
 ### ISIN
 
@@ -67,42 +206,43 @@ All identifier classes provide `valid?` and `valid_format?` methods at both clas
 
 ```ruby
 # class level
-SecId::ISIN.valid?('US5949181045')       # => true
-SecId::ISIN.valid_format?('US594918104') # => true
-SecId::ISIN.restore!('US594918104')      # => 'US5949181045'
-SecId::ISIN.check_digit('US594918104')   # => 5
+SecID::ISIN.valid?('US5949181045')      # => true
+SecID::ISIN.restore('US594918104')      # => 'US5949181045'
+SecID::ISIN.restore!('US594918104')     # => #<SecID::ISIN>
+SecID::ISIN.check_digit('US594918104')  # => 5
 
 # instance level
-isin = SecId::ISIN.new('US5949181045')
-isin.full_number           # => 'US5949181045'
+isin = SecID::ISIN.new('US5949181045')
+isin.full_id               # => 'US5949181045'
 isin.country_code          # => 'US'
 isin.nsin                  # => '594918104'
 isin.check_digit           # => 5
 isin.valid?                # => true
-isin.valid_format?         # => true
-isin.restore!              # => 'US5949181045'
+isin.restore               # => 'US5949181045'
+isin.restore!              # => #<SecID::ISIN> (mutates instance)
 isin.calculate_check_digit # => 5
-isin.to_cusip              # => #<SecId::CUSIP>
+isin.to_pretty_s           # => 'US 594918104 5'
+isin.to_cusip              # => #<SecID::CUSIP>
 isin.nsin_type             # => :cusip
-isin.to_nsin               # => #<SecId::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)
+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::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>
 ```
 
 ### CUSIP
@@ -111,22 +251,23 @@ SecId::ISIN.new('CH0012221716').to_valoren # => #<SecId::Valoren>
 
 ```ruby
 # class level
-SecId::CUSIP.valid?('594918104')       # => true
-SecId::CUSIP.valid_format?('59491810') # => true
-SecId::CUSIP.restore!('59491810')      # => '594918104'
-SecId::CUSIP.check_digit('59491810')   # => 4
+SecID::CUSIP.valid?('594918104')      # => true
+SecID::CUSIP.restore('59491810')      # => '594918104'
+SecID::CUSIP.restore!('59491810')     # => #<SecID::CUSIP>
+SecID::CUSIP.check_digit('59491810')  # => 4
 
 # instance level
-cusip = SecId::CUSIP.new('594918104')
-cusip.full_number           # => '594918104'
+cusip = SecID::CUSIP.new('594918104')
+cusip.full_id               # => '594918104'
 cusip.cusip6                # => '594918'
 cusip.issue                 # => '10'
 cusip.check_digit           # => 4
 cusip.valid?                # => true
-cusip.valid_format?         # => true
-cusip.restore!              # => '594918104'
+cusip.restore               # => '594918104'
+cusip.restore!              # => #<SecID::CUSIP> (mutates instance)
 cusip.calculate_check_digit # => 4
-cusip.to_isin('US')         # => #<SecId::ISIN>
+cusip.to_pretty_s           # => '594918 10 4'
+cusip.to_isin('US')         # => #<SecID::ISIN>
 cusip.cins?                 # => false
 ```
 
@@ -136,21 +277,21 @@ cusip.cins?                 # => false
 
 ```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
+SecID::CEI.valid?('A0BCDEFGH1')      # => true
+SecID::CEI.restore('A0BCDEFGH')      # => 'A0BCDEFGH1'
+SecID::CEI.restore!('A0BCDEFGH')     # => #<SecID::CEI>
+SecID::CEI.check_digit('A0BCDEFGH')  # => 1
 
 # instance level
-cei = SecId::CEI.new('A0BCDEFGH1')
-cei.full_number           # => 'A0BCDEFGH1'
+cei = SecID::CEI.new('A0BCDEFGH1')
+cei.full_id               # => '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.restore               # => 'A0BCDEFGH1'
+cei.restore!              # => #<SecID::CEI> (mutates instance)
 cei.calculate_check_digit # => 1
 ```
 
@@ -160,21 +301,21 @@ cei.calculate_check_digit # => 1
 
 ```ruby
 # class level
-SecId::SEDOL.valid?('B0Z52W5')       # => true
-SecId::SEDOL.valid_format?('B0Z52W') # => true
-SecId::SEDOL.restore!('B0Z52W')      # => 'B0Z52W5'
-SecId::SEDOL.check_digit('B0Z52W')   # => 5
+SecID::SEDOL.valid?('B0Z52W5')      # => true
+SecID::SEDOL.restore('B0Z52W')      # => 'B0Z52W5'
+SecID::SEDOL.restore!('B0Z52W')     # => #<SecID::SEDOL>
+SecID::SEDOL.check_digit('B0Z52W')  # => 5
 
 # instance level
-sedol = SecId::SEDOL.new('B0Z52W5')
-sedol.full_number           # => 'B0Z52W5'
+sedol = SecID::SEDOL.new('B0Z52W5')
+sedol.full_id               # => 'B0Z52W5'
 sedol.check_digit           # => 5
 sedol.valid?                # => true
-sedol.valid_format?         # => true
-sedol.restore!              # => 'B0Z52W5'
+sedol.restore               # => 'B0Z52W5'
+sedol.restore!              # => #<SecID::SEDOL> (mutates instance)
 sedol.calculate_check_digit # => 5
-sedol.to_isin               # => #<SecId::ISIN> (GB ISIN by default)
-sedol.to_isin('IE')         # => #<SecId::ISIN> (IE ISIN)
+sedol.to_isin               # => #<SecID::ISIN> (GB ISIN by default)
+sedol.to_isin('IE')         # => #<SecID::ISIN> (IE ISIN)
 ```
 
 ### FIGI
@@ -183,21 +324,22 @@ sedol.to_isin('IE')         # => #<SecId::ISIN> (IE ISIN)
 
 ```ruby
 # class level
-SecId::FIGI.valid?('BBG000DMBXR2')        # => true
-SecId::FIGI.valid_format?('BBG000DMBXR2') # => true
-SecId::FIGI.restore!('BBG000DMBXR')       # => 'BBG000DMBXR2'
-SecId::FIGI.check_digit('BBG000DMBXR')    # => 2
+SecID::FIGI.valid?('BBG000DMBXR2')     # => true
+SecID::FIGI.restore('BBG000DMBXR')     # => 'BBG000DMBXR2'
+SecID::FIGI.restore!('BBG000DMBXR')    # => #<SecID::FIGI>
+SecID::FIGI.check_digit('BBG000DMBXR') # => 2
 
 # instance level
-figi = SecId::FIGI.new('BBG000DMBXR2')
-figi.full_number           # => 'BBG000DMBXR2'
+figi = SecID::FIGI.new('BBG000DMBXR2')
+figi.full_id               # => 'BBG000DMBXR2'
 figi.prefix                # => 'BB'
 figi.random_part           # => '000DMBXR'
 figi.check_digit           # => 2
 figi.valid?                # => true
-figi.valid_format?         # => true
-figi.restore!              # => 'BBG000DMBXR2'
+figi.restore               # => 'BBG000DMBXR2'
+figi.restore!              # => #<SecID::FIGI> (mutates instance)
 figi.calculate_check_digit # => 2
+figi.to_pretty_s           # => 'BBG 000DMBXR 2'
 ```
 
 ### LEI
@@ -206,22 +348,23 @@ figi.calculate_check_digit # => 2
 
 ```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
+SecID::LEI.valid?('5493006MHB84DD0ZWV18')    # => true
+SecID::LEI.restore('5493006MHB84DD0ZWV')     # => '5493006MHB84DD0ZWV18'
+SecID::LEI.restore!('5493006MHB84DD0ZWV')    # => #<SecID::LEI>
+SecID::LEI.check_digit('5493006MHB84DD0ZWV') # => 18
 
 # instance level
-lei = SecId::LEI.new('5493006MHB84DD0ZWV18')
-lei.full_number           # => '5493006MHB84DD0ZWV18'
+lei = SecID::LEI.new('5493006MHB84DD0ZWV18')
+lei.full_id               # => '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.restore               # => '5493006MHB84DD0ZWV18'
+lei.restore!              # => #<SecID::LEI> (mutates instance)
 lei.calculate_check_digit # => 18
+lei.to_pretty_s           # => '5493 006M HB84 DD0Z WV18'
 ```
 
 ### IBAN
@@ -230,24 +373,25 @@ lei.calculate_check_digit # => 18
 
 ```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
+SecID::IBAN.valid?('DE89370400440532013000')    # => true
+SecID::IBAN.restore('DE370400440532013000')     # => 'DE89370400440532013000'
+SecID::IBAN.restore!('DE370400440532013000')    # => #<SecID::IBAN>
+SecID::IBAN.check_digit('DE370400440532013000') # => 89
 
 # instance level
-iban = SecId::IBAN.new('DE89370400440532013000')
-iban.full_number           # => 'DE89370400440532013000'
+iban = SecID::IBAN.new('DE89370400440532013000')
+iban.full_id               # => '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.restore               # => 'DE89370400440532013000'
+iban.restore!              # => #<SecID::IBAN> (mutates instance)
 iban.calculate_check_digit # => 89
 iban.known_country?        # => true
+iban.to_pretty_s           # => 'DE89 3704 0044 0532 0130 00'
 ```
 
 Full BBAN structural validation is supported for EU/EEA countries. Other countries have length-only validation.
@@ -258,58 +402,51 @@ Full BBAN structural validation is supported for EU/EEA countries. Other countri
 
 ```ruby
 # class level
-SecId::CIK.valid?('0001094517')        # => true
-SecId::CIK.valid_format?('0001094517') # => true
-SecId::CIK.normalize!('1094517')       # => '0001094517'
+SecID::CIK.valid?('0001094517')    # => true
+SecID::CIK.normalize('1094517')    # => '0001094517'
 
 # instance level
-cik = SecId::CIK.new('0001094517')
-cik.full_number   # => '0001094517'
+cik = SecID::CIK.new('0001094517')
+cik.full_id       # => '0001094517'
 cik.padding       # => '000'
 cik.identifier    # => '1094517'
 cik.valid?        # => true
-cik.valid_format? # => true
-cik.normalize!    # => '0001094517'
-cik.to_s          # => '0001094517'
+cik.normalized    # => '0001094517'
+cik.normalize!    # => #<SecID::CIK> (mutates full_id, returns self)
 ```
 
 ### 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.
+> [Options Clearing Corporation Symbol](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol) - a 16-to-21-character code used to identify equity options contracts.
 
 ```ruby
 # class level
-SecId::OCC.valid?('BRKB  100417C00090000')        # => true
-SecId::OCC.valid_format?('BRKB  100417C00090000') # => true
-SecId::OCC.normalize!('BRKB100417C00090000')      # => 'BRKB  100417C00090000'
-SecId::OCC.build(
+SecID::OCC.valid?('BRKB  100417C00090000')    # => true
+SecID::OCC.normalize('BRKB100417C00090000')   # => 'BRKB  100417C00090000'
+SecID::OCC.build(
   underlying: 'BRKB',
   date: Date.new(2010, 4, 17),
   type: 'C',
   strike: 90,
-)                                                 # => #<SecId::OCC>
+)                                                 # => #<SecID::OCC>
 
 # instance level
-occ = SecId::OCC.new('BRKB  100417C00090000')
-occ.full_symbol   # => 'BRKB  100417C00090000'
+occ = SecID::OCC.new('BRKB  100417C00090000')
+occ.full_id       # => 'BRKB  100417C00090000'
 occ.underlying    # => 'BRKB'
 occ.date_str      # => '100417'
 occ.date_obj      # => #<Date: 2010-04-17>
 occ.type          # => 'C'
 occ.strike        # => 90.0
 occ.valid?        # => true
-occ.valid_format? # => true
-occ.normalize!    # => 'BRKB  100417C00090000'
-
-occ = SecId::OCC.new('BRKB 2010-04-17C00090000')
-occ.valid_format? # => false
-occ.normalize!    # raises SecId::InvalidFormatError
+occ.normalized    # => 'BRKB  100417C00090000'
 
-occ = SecId::OCC.new('X 250620C00050000')
-occ.full_symbol   # => 'X 250620C00050000'
+occ = SecID::OCC.new('X 250620C00050000')
+occ.full_id       # => 'X 250620C00050000'
 occ.valid?        # => true
-occ.normalize!    # => 'X     250620C00050000'
-occ.full_symbol   # => 'X     250620C00050000'
+occ.normalize!    # => #<SecID::OCC> (mutates full_id, returns self)
+occ.full_id       # => 'X     250620C00050000'
+occ.to_pretty_s   # => 'X 250620 C 00050000'
 ```
 
 ### WKN
@@ -318,18 +455,16 @@ occ.full_symbol   # => 'X     250620C00050000'
 
 ```ruby
 # class level
-SecId::WKN.valid?('514000')        # => true
-SecId::WKN.valid?('CBK100')        # => true
-SecId::WKN.valid_format?('514000') # => true
+SecID::WKN.valid?('514000')  # => true
+SecID::WKN.valid?('CBK100')  # => true
 
 # instance level
-wkn = SecId::WKN.new('514000')
-wkn.full_number   # => '514000'
+wkn = SecID::WKN.new('514000')
+wkn.full_id       # => '514000'
 wkn.identifier    # => '514000'
 wkn.valid?        # => true
-wkn.valid_format? # => true
 wkn.to_s          # => '514000'
-wkn.to_isin       # => #<SecId::ISIN> (DE ISIN)
+wkn.to_isin       # => #<SecID::ISIN> (DE ISIN)
 ```
 
 WKN excludes letters I and O to avoid confusion with digits 1 and 0.
@@ -340,24 +475,23 @@ WKN excludes letters I and O to avoid confusion with digits 1 and 0.
 
 ```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'
+SecID::Valoren.valid?('3886335')        # => true
+SecID::Valoren.valid?('24476758')       # => true
+SecID::Valoren.valid?('35514757')       # => true
+SecID::Valoren.valid?('97429325')       # => true
+SecID::Valoren.normalize('3886335')     # => '003886335'
 
 # instance level
-valoren = SecId::Valoren.new('3886335')
-valoren.full_number   # => '3886335'
+valoren = SecID::Valoren.new('3886335')
+valoren.full_id       # => '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)
+valoren.normalized    # => '003886335'
+valoren.normalize!    # => #<SecID::Valoren> (mutates full_id, returns self)
+valoren.to_pretty_s   # => '3 886 335'
+valoren.to_isin       # => #<SecID::ISIN> (CH ISIN by default)
+valoren.to_isin('LI') # => #<SecID::ISIN> (LI ISIN)
 ```
 
 ### CFI
@@ -366,20 +500,17 @@ valoren.to_isin('LI') # => #<SecId::ISIN> (LI ISIN)
 
 ```ruby
 # class level
-SecId::CFI.valid?('ESXXXX')        # => true
-SecId::CFI.valid?('ESVUFR')        # => true
-SecId::CFI.valid_format?('ESXXXX') # => true
-
+SecID::CFI.valid?('ESXXXX')        # => true
+SecID::CFI.valid?('ESVUFR')        # => true
 # instance level
-cfi = SecId::CFI.new('ESVUFR')
-cfi.full_number    # => 'ESVUFR'
+cfi = SecID::CFI.new('ESVUFR')
+cfi.full_id        # => '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
@@ -397,23 +528,33 @@ CFI validates the category code (position 1) against 14 valid values and the gro
 
 ```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
-
+SecID::FISN.valid?('APPLE INC/SH')        # => true
+SecID::FISN.valid?('apple inc/sh')        # => true (normalized to uppercase)
 # instance level
-fisn = SecId::FISN.new('APPLE INC/SH')
-fisn.full_number   # => 'APPLE INC/SH'
+fisn = SecID::FISN.new('APPLE INC/SH')
+fisn.full_id       # => '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.
 
+## Lookup Service Integration
+
+SecID validates identifiers but does not include HTTP clients. The [`docs/guides/`](docs/guides/) directory provides integration patterns for external lookup services using only stdlib (`net/http`, `json`):
+
+| Guide | Service | Identifier |
+|-------|---------|------------|
+| [OpenFIGI](docs/guides/openfigi.md) | [OpenFIGI API](https://www.openfigi.com/api) | FIGI |
+| [SEC EDGAR](docs/guides/sec-edgar.md) | [SEC EDGAR](https://www.sec.gov/edgar/sec-api-documentation) | CIK |
+| [GLEIF](docs/guides/gleif.md) | [GLEIF API](https://www.gleif.org/en/lei-data/gleif-api) | LEI |
+| [Eurex](docs/guides/eurex.md) | [Eurex Reference Data](https://www.eurex.com/ex-en/data/free-reference-data-api) | ISIN |
+
+Each guide includes a complete adapter class and a [runnable example](examples/).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
@@ -424,12 +565,9 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-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
+Bug reports and pull requests are welcome on [GitHub](https://github.com/svyatov/sec_id). See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines.
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Changelog