ISIN scalar proposal for GraphQL Scalars

Overview

While implementing a financial-product feature, I needed to validate an ISIN entered through a form.

An ISIN, or International Securities Identification Number, is a 12-character identifier used for financial instruments. The original requirement looked like a straightforward alphanumeric input-validation task. After researching the format, I found that checking the length and allowed characters was not sufficient to determine whether an ISIN was structurally valid.

I opened a feature request in the GraphQL Scalars project and prepared a proof-of-concept implementation in my fork.

This proposal has not been merged or released by the upstream GraphQL Scalars project.

The problem

The product needed to prevent invalid security identifiers from reaching downstream services.

A regular expression can confirm that an input has the expected arrangement of letters and numbers, but complete structural validation also needs to verify:

• the 12-character ISIN format;
• the two-character country or issuer prefix;
• the alphanumeric National Securities Identifying Number;
• the final numeric check digit;
• the check digit using the Luhn algorithm.

The rule was initially needed in a frontend form. However, enforcing it only in the UI would still allow another API client to submit an invalid value.

This led to a broader question:

Could ISIN validation be represented as a reusable GraphQL scalar and enforced consistently at the schema boundary?

Proposed solution

I proposed adding an ISIN scalar to GraphQL Scalars.

The proof-of-concept implementation:

1. Accepts string values through the standard GraphQL scalar APIs.
2. Validates the expected ISIN structure.
3. Validates the country or special issuer prefix.
4. Converts alphabetic characters to their numeric representation.
5. Verifies the final check digit with the Luhn algorithm.
6. Rejects unsupported GraphQL value types and invalid identifiers.

The scalar implements:

• serialize;
• parseValue;
• parseLiteral.

It is also connected to the library’s scalar exports, resolver map and GraphQL type definitions.

Testing

I added tests for successful and unsuccessful validation paths, including:

• identifiers from multiple countries;
• special and supranational prefixes;
• GraphQL variables;
• inline GraphQL string literals;
• invalid input types;
• incorrect lengths;
• unsupported prefixes;
• incorrect check digits.

The implementation also includes a mock value and initial scalar documentation.

Open-source process

I first opened an upstream issue describing:

• the product motivation;
• the proposed scalar;
• the expected format;
• country-code validation;
• Luhn check-digit validation.

I then prepared an implementation in my fork so that the approach could be reviewed and later converted into an upstream pull request if the proposal is accepted.

At present:

• the upstream issue remains open;
• no upstream pull request has been created;
• the implementation exists only in my fork;
• the scalar is not part of an official GraphQL Scalars release.

Key takeaway

The main result was not simply another input validator.

The more important architectural lesson was that a business identifier used across a financial system should have one reusable and explainable validation rule, rather than several slightly different implementations in frontend forms, backend services and other API clients.