# @dcl/schemas

> Decentraland data structure interfaces and validators for TypeScript-based projects.

Latest version **27.1.0** (published 2026-08-11) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @dcl/schemas
pnpm add @dcl/schemas
yarn add @dcl/schemas
bun add @dcl/schemas
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 27.1.0 |
| Published | 2026-08-11 |
| First published | 2021-02-11 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Maintainers | decentralandbot, imazzara |

## Links

- npm: https://www.npmjs.com/package/@dcl/schemas
- Repository: https://github.com/decentraland/schemas
- Homepage: https://github.com/decentraland/schemas#readme
- Issues: https://github.com/decentraland/schemas/issues
- npm.io page: https://npm.io/package/@dcl/schemas

## Recent versions

- 27.1.0 (latest) — 2026-08-11
- 27.1.1-20260917155347.commit-2f30650 (next) — 2026-09-17
- 7.3.2-5257178677.commit-14f408d (ci) — 2023-06-13
- 6.19.1-20230515183007.commit-decfb22 (tag-outfits-2) — 2023-05-15
- 6.18.3-20230511113725.commit-c5c3fb1 (tag-publish-to-npm) — 2023-05-11
- 6.18.3-20230510200936.commit-01d2ae3 (tag-outfits) — 2023-05-10
- 6.17.1-20230428182545.commit-81ff481 (tag-bloom-filter-opt) — 2023-04-28
- 6.1.1-20230105152235.commit-8e7a916 (tag-fast-bootstrapping-6) — 2023-01-05
- 5.29.1-20221110202018.commit-b02a4b7 (tag-fast-bootstrapping-5) — 2022-11-10
- 5.29.1-20221110184735.commit-ea138a1 (tag-fast-bootstrapping-4) — 2022-11-10
- 5.28.1-20221108204939.commit-131a7d3 (tag-fast-bootstrapping-3) — 2022-11-08
- 5.28.1-20221108203808.commit-3da75ad (tag-fast-bootstrapping-2) — 2022-11-08
- 5.28.1-20221108202320.commit-a93fe13 (tag-fast-bootstrapping) — 2022-11-08
- 5.13.2-20220829183340.commit-a539bbf (tag-5.14) — 2022-08-29
- 4.14.2-20220608182026.commit-46a9277 (tag-add-emotes) — 2022-06-08
- … 700 more at https://npm.io/package/@dcl/schemas/versions

## README

# common-schemas

Decentraland data structure interfaces and validators for TypeScript-based projects.

Install it with:
```bash
npm i @dcl/schemas
```

## Design Guidelines

- Prevent type problems across projects
- Fail as early as possible, aim for compile-time
- Preserve user optionality through runtime helpers
- Prefer no-cost implementations and allow no-dependency import
- Code is written once, read hundreds of times

Implementation decisions:

- The main entrypoint should only export types
- Every type is also a namespace
- Type names are PascalCase
- Validators and schemas are camelCase

### Collaborator's Guide

#### Generating types, validators and schemas

This library export types that also act as values. This is achieved through TypeScript's [`namespaces`](https://www.typescriptlang.org/docs/handbook/namespaces.html). This means that every type imported from this library can also be used as a JS object. These types will include two properties named `schema` and `validate`. `namespaces` in typescript can be considered "`cost` imports".

#### Example Type Definition

```ts
// Declare type
export type MyType = {
  value: number;
};

// Declare namespace for the type
export namespace MyType {
  export const schema: Schema<MyType> = {
    type: "object",
    properties: {
      value: { type: number },
    },
    additionalProperties: false,
    required: ["value"],
  };

  export const validate = generateValidator<MyType>(schema);
}
```

MyType can now be both used as type `const a: MyType` or as an object `MyType.validate(a)`.

Beware that `validate` has type `ValidateFunction<T>` which `ajv` creates automatically. When writing new validations always try to implement it as an ajv validation, even if custom code is needed. See [here](https://ajv.js.org/keywords.html#define-keyword-with-code-generation-function).

Particularly, beware of using the library like this, because reports by the `validator.validate` function are lost and never returned to the caller.

```ts
const validator = generateValidator<MyType>(schema);
export const validate = (mt: MyType) =>
  validator.validate(mt) && otherValidations(mt);
```

#### Code ownership

Please add types and schemas of your domain into the `src/<team>` folder, also add your team to the [CODEOWNERS](.github/CODEOWNERS) repository to make sure nobody accidentally changes it without your team noticing it.

#### Informing changes

Please notify about changes to the schemas to relevant teams by adding the whole team (i.e. `@decentraland/dapps`) as reviewers of the pull requests.

It is recommended to subscribe to this repository (using the `Watch` function) if you use any internal part of the Decentraland ecosystem.

#### Making changes

To make sure the relevant persons and groups are aware of changes in these types, there's an api-extraction process executed with https://api-extractor.com that creates [a report file](report/schemas.api.md) for review between commits. It gets included as part of PRs for easier read.

To generate the file before submitting a PR, run `npm run refresh-api`. This is executed by the CI by runnig `npm run check-api`. It also verifies that the generated file matches the exported types.

## Versioning and Publishing

Versions are handled manually using Github releases and semver.

Main branch is automatically published to the `@next` dist tag to test integrations before final releases happen.

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