# @trezor/schema-utils

Latest version **10.0.1** (published 2026-09-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @trezor/schema-utils
pnpm add @trezor/schema-utils
yarn add @trezor/schema-utils
bun add @trezor/schema-utils
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 10.0.1 |
| Published | 2026-09-25 |
| First published | 2024-01-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 24.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Maintainers | prusnak, tsusanka-sl, trezor-ci, trezor-admin |

## Links

- npm: https://www.npmjs.com/package/@trezor/schema-utils
- Repository: https://github.com/trezor/trezor-suite
- npm.io page: https://npm.io/package/@trezor/schema-utils

## Dependencies (3)

- [ts-mixer](https://npm.io/package/ts-mixer.md) ^6.0.4
- [@trezor/utils](https://npm.io/package/@trezor/utils.md) 10.0.1
- [@sinclair/typebox](https://npm.io/package/@sinclair/typebox.md) ^0.34.49

## Recent versions

- 10.0.1 (latest) — 2026-09-25
- 10.0.0-beta.3 (beta) — 2026-09-17
- 10.0.0-alpha.1 (alpha) — 2026-05-15
- 10.0.0 — 2026-09-22
- 10.0.0-beta.2 — 2026-09-16
- 10.0.0-beta.1 — 2026-07-30
- 1.4.0 — 2025-12-16
- 1.3.5-beta.1 — 2025-12-09
- 1.3.4 — 2025-07-11
- 1.3.4-beta.1 — 2025-07-07
- 1.3.3 — 2025-05-15
- 1.3.3-beta.1 — 2025-05-08
- 1.3.2 — 2025-03-19
- 1.3.2-beta.1 — 2025-03-18
- 1.3.1 — 2025-03-06
- … 20 more at https://npm.io/package/@trezor/schema-utils/versions

## README

# @trezor/schema-utils

A schema definition and validation library for TypeScript, based on [TypeBox](https://github.com/sinclairzx81/typebox).

## Example usage

### Schema definition

Let's say we have a TypeScript type that we want to convert to a schema.

```typescript
export interface Example {
    coordinator: string;
    coin?: string;
    maxRounds: number;
    maxFeePerKvbyte: Uint;
    data: ArrayBuffer;
    path: DerivationPath;
}
```

The schema for this type can be defined as follows:

```typescript
import { Type, Static } from '@trezor/schema-utils';
// ...

export const Example = Type.Object({
    coordinator: Type.String(),
    coin: Type.Optional(Type.String()),
    maxRounds: Type.Number(),
    maxFeePerKvbyte: Type.Uint(),
    data: Type.ArrayBuffer(),
    path: DerivationPath, // Reference to another schema
});

// Inferred TS type
export type Example = Static<typeof schema>;
```

We can see that primitive and common types are defined using the `Type` object. This is also used for constructs such as unions, intersects, etc. The full list of available types can be found in the [TypeBox documentation](https://github.com/sinclairzx81/typebox/blob/master/readme.md)

If done correctly, the new schema should be equivalent to the old TypeScript type.
Since the inferred TypeScript type is exported with the same name, it can be used both as a type and for runtime validation.

### Validation

We have two main functions for validation: `Assert` and `Validate`.

Assert throws an error if the payload does not match the schema, also functioning as a type assertion.

```typescript
import { Assert } from '@trezor/schema-utils';

Assert(Example, payload);
// payload now must be of type Example
```

Validate does not throw, but simply returns a boolean. It can also be used as a type guard.

```typescript
import { Validate } from '@trezor/schema-utils';

if (Validate(Example, payload)) {
    // payload now must be of type Example
}
```

## Code generation

To generate schemas from TypeScript types automatically, you can use the code generation tool.

```bash
yarn workspace @trezor/schema-utils codegen <file>
```

This tool is also used in Protobuf code generation to generate schemas for the messages.

## Custom types

There are a few behavior changes and custom types that are used in the schemas.

### Enums

```typescript
enum MyExample {
    Foo = 'foo',
    Bar = 'bar',
}

const EnumMyExample = Type.Enum(MyExample);
```

To use an enum as a schema, you need to use the `Type.Enum` function.
The convention is to prefix the name of the schema with `Enum`.
That way, the original enum can be used as a TypeScript type, and the schema can be used for validation.

To get the schema for the keys of the enum, you can use the `KeyOfEnum` type. The parameter it takes is directly the original Enum, not the schema. Don't use Typebox's `Type.KeyOf` function for this, as it will not work correctly.

```typescript
const MyExampleKey: Type.KeyOfEnum(MyExample);
```

### Uint

```typescript
Type.Uint();

// Can also be used for Sint
Type.Uint({ allowNegative: true });
```

The `Uint` type is a custom type that is used in the Protobuf messages.
It is a unsigned integer that can be represented as a string or a number.
By using the `allowNegative` option, it can also be used for signed integers.

### ArrayBuffer and Buffer

```typescript
Type.ArrayBuffer();
Type.Buffer();
```

Instances of the `ArrayBuffer` JS built-in object and `Buffer` in Node.js.

---
_Source: https://npm.io/package/@trezor/schema-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._