The ident
library contains Scala classes for working with identifiers of
various types that have been validated to have the correct format:
-
CIK: An SEC / EDGAR Central Index Key (CIK) number is a 10-digit numerical identifier associated with every entity that files with the SEC (both the entity submitting the filing and the entity that is the subject of the filing).
-
CUSIP: An ANSI standard (ANSI X9.6-2020) identifier for North American securities, and select other countries that have adopted it as part of the CINS system. Defined by the Committee on Uniform Security Identification Procedures (CUSIP), from which it takes its name. The standard is available for purchase from the ANSI Store.
-
FIGI: A Financial Instrument Global Identifier (FIGI). The specification is available for download from OMG.
-
ISIN: International Security Identifiers (ISINs) as defined in ISO 6166:2021 Financial services — International securities identification number (ISIN) ("The Standard").
-
LEI: An ISO standard (ISO 17442-1:2020(E)) Legal Entity Identifier (LEI).
-
MIC: A (Financial) Market Identifier Code (MIC).
And, it includes integrations with a variety of other modules:
-
Circe: A JSON library for Scala powered by Cats. Use the
ident-circe
module. -
ZIO Config: An extension to ZIO's built-in Configuration facility. Use the
ident-zio-config
module. -
ZIO Json: "A fast and secure JSON library with tight ZIO integration". Use the
ident-zio-json
module. -
ZIO Schema: "A ZIO-based library for modeling the schema of data structures as first-class values. Use the
ident-zio-schema
module.
val input = "US0378331005"
// input: String = "US0378331005"
Isin.fromString(input) match {
case Right(isin) =>
println(s"Parsed ISIN: $isin")
println(s" Country code: ${isin.countryCode}")
println(s" Security identifier: ${isin.securityIdentifier}")
println(s" Check digit: ${isin.checkDigit}")
case Left(err) =>
throw new RuntimeException(s"Unable to parse ISIN $input: $err")
}
// Parsed ISIN: US0378331005
// Country code: US
// Security identifier: 037833100
// Check digit: 5
Add this to your build.sbt
:
libraryDependencies += "com.gregorpurdy" %% "ident" % "0.3.0"
for the basic identifier data types, or use one or more of the integrations to support various encodings:
libraryDependencies += "com.gregorpurdy" %% "ident-circe" % "0.3.0"
libraryDependencies += "com.gregorpurdy" %% "ident-zio-config" % "0.3.0"
libraryDependencies += "com.gregorpurdy" %% "ident-zio-json" % "0.3.0"
libraryDependencies += "com.gregorpurdy" %% "ident-zio-schema" % "0.3.0"
You can use the ident-circe
or ident-zio-json
artifacts to get JSON encoders
and decoders for supported identifiers.
You can also use the ident-zio-schema
artifact to get generic ZIO Schema
support, which includes support for JSON and other formats as well as other
functionality.
The tools directory contains Scala CLI scripts for working with identifiers on the command line:
-
cusip-tool.sc: Reads CUSIPs from standard input (one per line) and validates them. Includes a
--fix
mode that writes them back to standard output with corrected check digits. -
isin-tool.sc: Reads ISINs from standard input (one per line) and validates them. Includes a
--fix
mode that writes them back to standard output with corrected check digits.
These terms appear in the APIs and documentation:
-
Check Character(s): The general term for one or more characters computed from the Parts (equivalently from the Payload), used as an integrity check.
-
Check Digit(s): The specific term when the Check Character(s) are taken from the set of decimal digits.
-
Parts: For an identifier format with multiple fields, we use the term "Parts" to mean the sequence of all these fields, including any Check Characters.
-
Payload: The value from which the Check Character(s) are computed. Typically, the concatenation of the Payload Parts.
-
Payload Parts: The sub-sequence of the Parts that excludes any Check Characters.
Licensed under Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.
Copyright 2023 Gregor Purdy. All rights reserved.