Skip to main content

RA.Utilities.Core.ValueObjects

· 4 min read
Redon Alla
Redon Alla
.NET, React, Angular Developer

Version 10.2.0​

Date Badge NuGet version

Feature release: introduces the IBAN value object for validated, normalized International Bank Account Numbers with ISO 7064 mod-97 check digits and ASP.NET Core minimal API binding.

✨ New Features​

  • IBAN value object: Validates and normalizes International Bank Account Numbers (IBAN). Guarantees that any instance in your domain is canonical, structurally sound, and mathematically verified.
  • Automatic paper format normalization: Strips grouping characters (spaces, hyphens, backslashes, apostrophes) and converts to upper case on creation ("gb82 west 1234-5698-7654-32" → "GB82WEST12345698765432").
  • ISO 13616 structural validation: Validates the 2-letter country code, 2 check digits, and 9–30 alphanumeric BBAN (13–34 total characters), reporting BaseErrorCode.IbanNotValid (NOT_VALID_IBAN) on structural failures.
  • ISO 7064 mod-97 check digit verification: Computes expected check digits and verifies them against the input, reporting BaseErrorCode.IbanCheckDigits (IBAN_CHECK_DIGITS) on checksum mismatches.
  • CountryCode property: Exposes the 2-letter ISO 3166-1 alpha-2 country code extracted from the first two characters (e.g. GB).
  • Minimal API binding: Implements IParsable<IBAN>, enabling route, query, and header binding in ASP.NET Core minimal APIs with automatic HTTP 400 responses on invalid input.
  • Built-in JSON converter: Preconfigured with ValueObjectJsonConverter<IBAN> for string-based JSON serialization and deserialization.

📝 Notes​

  • IBAN validates the general ISO 13616 structural range (13–34 characters) and ISO 7064 mod-97 check digits. Consumers wishing to enforce country-specific lengths can check CountryCode and report BaseErrorCode.IbanLength (IBAN_LENGTH).
  • The release is backward compatible; existing code compiles and behaves unchanged. See the Migration Guide for details.

Version 10.1.0​

Date Badge NuGet version

Feature release: adds Money.Subtract for currency-safe subtraction.

✨ New Features​

  • Money.Subtract(other): returns a new Money with the difference of the two amounts. Mirrors Add(other): throws a BadRequestException with a CurrencyMismatch validation error (AttemptedValue = the other currency, ExpectedValue = the instance currency) when the currencies differ.
var price = Money.PositiveMoney(19.99m, new Currency("EUR"));
var discount = Money.PositiveMoney(4.00m, new Currency("EUR"));

var net = price.Subtract(discount); // 15.99 EUR
// price.Subtract(new Money(4m, new Currency("USD"))) throws BadRequestException (CurrencyMismatch)

📝 Notes​

  • Money is immutable: Add and Subtract return new instances and never mutate the operands.

Version 10.0.0​

Date Badge NuGet version

This is the first stable release of RA.Utilities.Core.ValueObjects, introducing strongly-typed, validated value objects for .NET with built-in System.Text.Json support, structured validation errors via BadRequestException, and minimal API binding through IParsable<T>.

✨ New Features​

  • Email: A validated, normalized email value object. Trims and lowercases input, enforces a 254-character maximum, and exposes LocalPart and Domain properties.
  • Currency: A validated currency value object. Trims and uppercases input and enforces the 3-character ISO 4217 length.
  • SSN: A validated social-security-number value object. Trims, uppercases, and enforces the 10-character ^[A-Z][0-9]{8}[A-Z]$ format.
  • Money: A monetary amount pairing a decimal with a Currency, with a PositiveMoney factory and currency-safe Add.
  • IValueObject<TSelf>: A shared contract extending IParsable<TSelf> with a normalized Value property, making it easy to build your own validated value objects.
  • ValueObjectJsonConverter<T>: A generic System.Text.Json converter that serializes value objects as plain strings and validates them on deserialization, applied out of the box to Email, Currency, and SSN.
  • Structured validation errors: Every validation failure throws a BadRequestException carrying ValidationError entries with property name, message, error code, attempted value, and expected value — ready for the RA.Utilities API error pipeline.
  • Minimal API binding: Parse/TryParse implementations enable route, query, and header binding in ASP.NET Core minimal APIs, with failed bindings producing automatic 400 responses.

📝 Notes​

There are no breaking changes — 10.0.0 is the initial release. See the Getting Started guide to adopt the package.