@IsISIN

Декоратор @IsISIN в библиотеке class-validator применяется для проверки строкового значения на соответствие формату ISIN (International Securities Identification Number). ISIN используется для однозначной идентификации ценных бумаг и представляет собой стандарт ISO 6166.

ISIN всегда состоит из 12 символов и включает:

  • двухбуквенный код страны (ISO 3166-1 alpha-2),
  • девятисимвольный национальный идентификатор,
  • одну контрольную цифру.

Контрольная цифра вычисляется по алгоритму Луна, что позволяет выявлять большинство ошибок ввода.

Формат ISIN и требования к значению

Строка считается валидной ISIN при соблюдении следующих условий:

  • длина строго 12 символов;
  • первые две позиции — латинские буквы;
  • последующие символы — заглавные латинские буквы или цифры;
  • последняя позиция — контрольная цифра;
  • отсутствуют пробелы и разделители;
  • регистр фиксируется как верхний (lowercase обычно приводит к нормализации внутри проверки).

Пример корректных значений:

US0378331005
GB0002634946
DE000BASF111

Синтаксис декоратора

Базовая форма использования:

import { IsISIN } from 'class-validator';

class InstrumentDto {
  @IsISIN()
  isin: string;
}

Поведение валидации

Декоратор выполняет несколько уровней проверки:

  1. Проверка типа значения Значение должно быть строкой. Объекты, числа и null отклоняются.

  2. Проверка длины Строго 12 символов без исключений.

  3. Проверка алфавитно-цифрового состава Допускаются только латинские символы и цифры.

  4. Проверка структуры ISIN Первые два символа — код страны.

  5. Проверка контрольной цифры Применяется алгоритм Луна, учитывающий преобразование букв в числа.

Алгоритмическая основа проверки контрольной цифры

ISIN преобразуется в числовую последовательность:

  • буквы заменяются на числа (A = 10, B = 11, …, Z = 35);

  • полученная строка разбивается на отдельные цифры;

  • применяется алгоритм Луна:

    • каждая вторая цифра справа удваивается,
    • при результате больше 9 выполняется разбиение на сумму цифр,
    • суммируются все значения,
    • итог должен делиться на 10 без остатка.

Это обеспечивает устойчивость к опечаткам и перестановкам.

Сообщения об ошибках

При нарушении правил валидации библиотека возвращает стандартное сообщение:

  • isin must be a valid ISIN number

Сообщение может быть переопределено через параметры декоратора.

Кастомизация сообщений

Поддерживается передача объекта настроек:

import { IsISIN } from 'class-validator';

class InstrumentDto {
  @IsISIN({ message: 'Некорректный ISIN код инструмента' })
  isin: string;
}

Сообщение может быть динамическим:

@IsISIN({
  message: ({ property, value }) =>
    `Поле ${property} содержит недопустимое значение: ${value}`,
})
isin: string;

Использование в DTO-структурах

Типичный сценарий — валидация входных данных финансовых API:

class CreateBondDto {
  @IsISIN()
  bondIsin: string;

  @IsISIN()
  underlyingAssetIsin: string;
}

Каждое поле валидируется независимо, ошибки группируются по свойствам объекта.

Нормализация входных данных

Декоратор не выполняет автоматическую трансформацию строки. Перед проверкой важно учитывать:

  • пробелы не удаляются автоматически;
  • lowercase не приводится к uppercase;
  • символы-разделители (например, -) приводят к ошибке.

Для подготовки данных обычно применяется явная нормализация:

class InstrumentDto {
  @Transform(({ value }) => value?.replace(/\s+/g, '').toUpperCase())
  @IsISIN()
  isin: string;
}

Совместное использование с другими декораторами

@IsISIN часто комбинируется с другими валидаторами:

class InstrumentDto {
  @IsString()
  @Length(12, 12)
  @IsISIN()
  isin: string;
}

или

class InstrumentDto {
  @IsNotEmpty()
  @IsISIN()
  isin: string;
}

Комбинация позволяет уточнить семантику поля до применения специализированной проверки.

Группы валидации

Поддерживается использование validation groups:

class InstrumentDto {
  @IsISIN({ groups: ['create'] })
  isin: string;
}

Это позволяет различать сценарии:

  • создание сущности;
  • обновление;
  • частичная валидация.

Особенности строгой проверки

ISIN-валидация считается строгой и не допускает «похожих» значений:

  • строка с правильной длиной, но неверной контрольной цифрой отклоняется;
  • корректная структура без проверки контрольной суммы также отклоняется;
  • любые лишние символы (даже невидимые) приводят к ошибке.

Типичные причины ошибок

Частые источники невалидных значений:

  • наличие пробелов в начале или конце строки;
  • использование строчных букв без нормализации;
  • копирование из PDF/Excel с невидимыми символами;
  • перепутанные цифры в контрольной позиции;
  • использование локальных идентификаторов вместо ISIN.

Применение в финансовых моделях

ISIN как поле используется в доменных моделях:

  • облигации;
  • акции;
  • деривативы;
  • паевые инструменты;
  • ETF.

Валидация на уровне DTO позволяет отсекать некорректные данные до попадания в бизнес-логику.

Производственные аспекты использования

Проверка ISIN:

  • имеет детерминированную сложность O(n), где n = 12;
  • не требует внешних сервисов;
  • безопасна для массовой валидации списков инструментов;
  • подходит для высоконагруженных API без оптимизационных ограничений.

Поведение при null и undefined

Значения null и undefined не проходят проверку, если не применены дополнительные декораторы:

class InstrumentDto {
  @IsOptional()
  @IsISIN()
  isin?: string;
}

Без @IsOptional() отсутствие значения приводит к ошибке валидации.

Оглавление