Fundraising data validations

This internal CRUKorg package provides regular expressions to validate commonly collected supporter data in fundraising products, ensuring the data meets the minimum requirements for downstream systems.

The motivation for creating this package is to standardise these validation rules to avoid duplicated interpretation of them in multiple products and minimise risks of passing invalid data downstream. This package is designed to be used in frontend forms and on backend services accepting any payloads of data to be sent downstream.

Usage

To install the package locally

1. Run npm install @crukorg/fundraising-data-validations in your terminal.
2. Import the relevant schema into your validation files, e.g.

import { supporterSchema } from "@crukorg/fundraising-data-validations";

const isValidFirstName =
  supporterSchema.firstName.allowedCharacters.regex.test(inputFirstName);

if (!isValidFirstName) {
  return supporterSchema.firstName.allowedCharacters.errorMessage;
}

Zod example:

import { z } from "zod";
import { supporterSchema } from "@cruk/fundraising-data-validations";

const isValidSupporter = z
  .object({
    firstName: z
      .string()
      .trim()
      .regex(
        supporterSchema.firstName.minMaxLength?.regex,
        supporterSchema.firstName.minMaxLength?.errorMessage,
      )
      .regex(
        supporterSchema.firstName.allowedCharacters.regex,
        supporterSchema.firstName.allowedCharacters.errorMessage,
      ),
  })
  .required({
    firstName: supporterSchema.firstName.isRequired?.required,
  });

try {
  isValidSupporter.parse(inputSupporter);
} catch (error) {
  if (error instanceof ZodError) {
    const errorMessages = prettifyError(error);
    console.error(errorMessages);
  }
}

1. You may add additional, stricter rules on top of these validations, but these rules should form the foundation of any validations for form data.

Required and optional validation

Each field has several rules available for use. In each case, required and allowedCharacters regexes are the minimum required rules. Most of the fields also have a minMaxLength rule, the only current exception being the createdAt field.

• firstName and lastName: forbiddenSubstrings should be enforced.
• phoneNumber: forbiddenSubstrings are optional depending on if your validation requires phoneNumber to be a landline.
• dateOfBirth: only the YYYY-MM-DD format is validated by this package. Semantic checks such as "must be in the past" or age-based rules (e.g. 18+) are intentionally out of scope and must be applied by consumers on top of this foundation.

Limitations

• The regular expressions are written to be language agnostic, but they have only been tested in TypeScript applications.
• The regular expressions are compatible with AWS tools that allow regular expressions for string comparison, such as Step Functions, since allowed regex in AWS have some limitations.

Transformations

[!IMPORTANT] The following data transformation must be handled by the products, as they is not included in the validations package to minimise friction to the user journey.

firstName

• remove whitespace before or after a hyphen or an apostrophe, e.g. " - " is converted to "-"
• must be in Proper Case

lastName

• remove whitespace before or after a hyphen or an apostrophe, e.g. " - " is converted to "-"

email

• must be in lowercase

phoneNumber / mobileNumber

• remove whitespace

address lines

• replace comma with space
• must be no duplicates across lines

postcode

• must be UPPERCASE

Validation Error Messages

Title

| Validation | Error Message | | ------------- | ---------------------------------------------------- | | Invalid title | Enter one of 'Dr', 'Mr', 'Mrs', 'Miss', 'Ms', 'Mx' |

First Name

| Validation | Error Message | | ------------------------------------------------------------- | ---------------------------------------------------------------- | | Required | First name is required. | | Invalid characters | First names can only contain letters, hyphens and apostrophes. | | Length | First name must be between 2 and 40 characters. | | Invalid value (and, plus, test, undefined, unknown) | First name must be a valid name and must be an individual. |

Last Name

| Validation | Error Message | | ------------------------------------------------------------- | --------------------------------------------------------------- | | Required | Last name is required. | | Invalid characters | Last names can only contain letters, hyphens and apostrophes. | | Length | Last name must be between 2 and 50 characters. | | Invalid value (and, plus, test, undefined, unknown) | Last name must be a valid name and must be an individual. |

Date of Birth

| Validation | Error Message | | -------------- | ------------------------------------------------- | | Invalid format | Date of birth must be in the format YYYY-MM-DD. |

Address Line 1

| Validation | Error Message | | ------------------ | --------------------------------------------------------------------------------------------------------- | | Required | First line of address is required. | | Invalid characters | The first line of address can only contain letters, numbers and the following special characters '-/.&. | | Length | The first line of address must be between 1 and 200 characters. |

Address Line 2

| Validation | Error Message | | ------------------ | ---------------------------------------------------------------------------------------------------------- | | Invalid characters | The second line of address can only contain letters, numbers and the following special characters '-/.&. | | Length | The second line of address must be under 100 characters. |

Address Line 3

| Validation | Error Message | | ------------------ | --------------------------------------------------------------------------------------------------------- | | Invalid characters | The third line of address can only contain letters, numbers and the following special characters '-/.&. | | Length | The third line of address must be under 100 characters. |

Address Line 4

| Validation | Error Message | | ------------------ | ---------------------------------------------------------------------------------------------------------- | | Invalid characters | The fourth line of address can only contain letters, numbers and the following special characters '-/.&. | | Length | The fourth line of address must be under 100 characters. |

Town

| Validation | Error Message | | ------------------ | ---------------------------------------------------------------------------------------- | | Required | Town is required. | | Invalid characters | Town can only contain letters, numbers and the following special characters ' - / . &. | | Length | Town must be between 1 and 40 characters. |

UK Postcode

| Validation | Error Message | | ------------------ | ------------------------------------------------------------ | | Required | Postcode is required. | | Invalid characters | The postcode can only contain letters, numbers and spaces. | | Length | The postcode must be between 2 and 8 characters. |

International Postcode

| Validation | Error Message | | ------------------ | ------------------------------------------------------------ | | Required | Postcode is required. | | Invalid characters | The postcode can only contain letters, numbers and spaces. | | Length | The postcode must be between 2 and 10 characters. |

Country

| Validation | Error Message | | ------------------ | -------------------------------------------------- | | Required | Country is required. | | Invalid characters | The country can only contain letters and spaces. | | Length | The country must be between 1 and 60 characters. |

Email Address

| Validation | Error Message | | -------------- | ------------------------------------------------------------------------------------ | | Required | An email address is required. | | Invalid format | This email address doesn't follow the correct format - for example [email protected] | | Length | The email address is too long. |

Phone Number

| Validation | Error Message | | ---------------------- | -------------------------------------------------------------------------------- | | Invalid characters | The phone number can only contain numbers, spaces and plus sign. | | Length | The phone number must be between 1 and 16 numbers, optionally starting with +. | | Mobile number supplied | Mobile numbers are not allowed. |

UK Mobile Number

| Validation | Error Message | | ------------------ | --------------------------------------------------------------------------------- | | Invalid characters | The phone number can only contain numbers, spaces and plus sign. | | Length | The mobile number must be between 1 and 16 numbers, optionally starting with +. |

Notes

Address line 1-4 and town fields support Latin-script characters with diacritics, including examples such as:

• São Paulo
• München
• Łódź
• Québec
• Thành phố Hồ Chí Minh

Non-Latin scripts (e.g. Cyrillic, Greek, Arabic, Chinese, Japanese and Korean) are not supported.