isin

Documentation

Overview

Package isin decodes and validates an International Securities Identification Number (ISO 6166) — the 12-character code that identifies a tradable security (a stock, bond, or fund). It is the securities leg of the financial-data decoder family alongside internal/iban (the account) and internal/lei (the entity): an ISIN turns up in brokerage statements, trade confirmations, market-data dumps, and investment-fraud lures, so decoding one off a paste tells an operator the issuing prefix and whether the number is internally consistent.

Wrap-vs-native judgement

Native. An ISIN is a fixed character-field layout — a 2-letter
prefix (an ISO 3166-1 country code, or a special code such as XS for
internationally-cleared issues), a 9-character National Securities
Identifying Number, then 1 check digit — guarded by an ISO 6166
modulus-10 (Luhn) checksum over the letter-expanded body. Validating
it is integer arithmetic; no runtime dependency or hand-transcribed
table is justified. stdlib only, no new go.mod dep.

Verifiable / no confidently-wrong output

The Luhn check digit is the verification anchor — it is recomputed
and compared, and a mismatch is reported as luhn_valid=false with the
expected check digit in a note (a mistyped ISIN), never asserted as a
definitively fake security. The 2-letter prefix is surfaced raw, not
mapped to a country name — that would need a hand-transcribed table
the ISIN does not carry, and several prefixes (XS, EU) are not
countries at all. The NSIN is surfaced whole, not split into its
national scheme (CUSIP, SEDOL, WKN, …) — that split is
prefix-specific with no single public rule. The algorithm is verified
against five well-known real ISINs in the tests (Apple, IBM, Nokia,
BAE Systems, Microsoft).

Index

• type Result
  • func Decode(raw string) (*Result, error)

Types

type Result

type Result struct {
	ISIN       string   `json:"isin"`        // normalised: separators stripped, upper-cased
	Prefix     string   `json:"prefix"`      // chars 1-2: ISO 3166-1 country code (or a special code such as XS)
	NSIN       string   `json:"nsin"`        // chars 3-11: National Securities Identifying Number
	CheckDigit string   `json:"check_digit"` // char 12
	LuhnValid  bool     `json:"luhn_valid"`  // ISO 6166 modulus-10 (the verification anchor)
	Notes      []string `json:"notes,omitempty"`
}

Result is the decoded view of an ISIN.

func Decode

func Decode(raw string) (*Result, error)

Decode validates and breaks down an ISIN. Spaces, '-' and ':' separators are tolerated and the input is upper-cased.