Validation SDK

The Validation SDK package provides a set of utilities for validating data and enforcing constraints in applications. It offers a collection of functions and types that help developers ensure data integrity and enforce business rules effectively.

This is used mostly internally by other SDK packages, but it can also be used directly in your application to validate data. It uses Zod under the hood to provide a robust and type-safe validation experience.

Installation

To integrate the SDK Validation package into your project, use the following command with your preferred package manager:

npm install @sdk/validation

Available Validators

Entity Name Platform Compatibility

The isCloudCompatibleEntityName validator checks if a given string is a valid entity name that can be used with the HxDR platform. An Entity in the platforms context can be a Folder, an Asset or a Project. It enforces the following constraints:

• Must not contain any of the following characters: < > : | ? * # $ + % ! & ' { } " = @ ^ NULL \
• Must not contain any of the following device names: CON, PRN, AUX, NUL, COM0, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM¹, COM¹, COM³, LPT0, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, LPT¹, LPT², LPT³
• Must not contain two dots in a row
• Must not contain leading or trailing whitespace
• Must not contain trailing dot

File Name Platform Compatibility

The isCloudCompatibleFileName validator inherits all checks from isCloudCompatibleEntityName and adds an additional constraint that the name must only include latin characters. This is used for validating asset uploads through the HxDR platform.

Usage Examples

import { z } from 'zod';
import { isCloudCompatibleEntityName } from '@sdk/validation';
 
const mySchema = z.object({
  title: isCloudCompatibleEntityName,
});
 
const result = mySchema.safeParse({ title: 'COM1' });

For more information on how to use Zod validators, check out the Zod documentation (opens in a new tab).

Customizing Error Messages

Often it is necessary to provide custom error messages when a validation fails. This can be done by leveraging the zod ErrorMap feature. Here is an example of how to customize the error message for the isCloudCompatibleEntityName validator:

import { z } from 'zod';
import { isCloudCompatibleEntityName, CloudCompatibleFileNameIssue } from '@sdk/validation';
 
isCloudCompatibleEntityName.parse('COM1', {
  errorMap: (issue, ctx) => {
    // Customize the error message for the required value
    if (issue.code === z.ZodIssueCode.too_small) {
      return { message: 'The entity name is required.' };
    }
    // Customize the error message for the contains_win_device_name issue
    if (
      issue.code === z.ZodIssueCode.custom &&
      issue.params.customCode === CloudCompatibleFileNameIssue.contains_win_device_name
    ) {
      return { message: 'The entity name must not contain a Windows device name.' };
    }
    // Provide a default error message for all other file-system issues
    if (issue.code === z.ZodIssueCode.custom) {
      return { message: 'The entity name is invalid.' };
    }
    // Use the default error message for all other issues
    return { message: ctx.defaultError };
  },
});

In this example, we customize the error message for the contains_win_device_name (COM, LPT and others) issue and provide a more descriptive message.

To find out more about the zod ErrorMap feature, check out the Zod documentation (opens in a new tab).