Zod Schemas for apps on ICP

A collection of reusable Zod schemas and validators for common data patterns in Internet Computer applications.

Table of contents

• Installation
• Features

Installation

You can use the library by installing it in your project.

npm i @dfinity/zod-schemas

The bundle needs peer dependencies, be sure that following resources are available in your project as well.

npm i @dfinity/principal

Features

The library implements following features:

🧰 Functions

• createUrlSchema

⚙️ createUrlSchema

Creates a Zod schema for validating URLs. By default, it validates that the URL protocol is HTTPS and allow usage of HTTP only locally.

Parameters:

• options: - Configuration options for the schema.
• options.additionalProtocols: - Additional protocols to allow (e.g., "wss:" or "ftp:"). ⚠️ Usage of insecure protocols is discouraged.
• options.allowHttpLocally: - Whether to allow HTTP for localhost and 127.0.0.1. Default: true.

Returns:

• The Zod schema with URL validation.

Examples:

const schema = createUrlSchema({ additionalProtocols: ["wss:"], allowHttpLocally: false });

schema.parse("https://example.com"); // Valid schema.parse("wss://example.com"); // Valid schema.parse("http://localhost"); // Invalid if allowHttpLocally is false

🔗 Source

🔧 Constants

• PrincipalTextSchema
• UrlSchema

⚙️ PrincipalTextSchema

Zod schema to validate a string as a valid textual representation of a Principal.

This schema checks if the provided string can be converted into a Principal instance. If the conversion fails, validation will return an error message.

Examples:

const result = PrincipalTextSchema.safeParse("aaaaa-aa");
console.log(result.success); // true or false

🔗 Source

⚙️ UrlSchema

Default URL schema that enforces HTTPS and allows HTTP locally.

Examples:

UrlSchema.parse("https://example.com"); // Valid UrlSchema.parse("http://127.0.0.1"); // Valid (localhost exception)

🔗 Source