Ident

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.

Example

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

Usage

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"

JSON

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.

Tools

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.

Identifier Component Terminology

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.

License

Licensed under Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

Contribution

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

Copyright 2023 Gregor Purdy. All rights reserved.