# @deconz-community/ddf-validator

> Validating DDF files for deconz

Latest version **2.37.0** (published 2026-10-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install @deconz-community/ddf-validator
pnpm add @deconz-community/ddf-validator
yarn add @deconz-community/ddf-validator
bun add @deconz-community/ddf-validator
```

## 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 | 2.37.0 |
| Published | 2026-10-21 |
| First published | 2023-03-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16.0.0 |
| Dependencies | 1 |
| Unpacked size | 181.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | Zehir |
| Maintainers | mimiix, zorimyll |
| Keywords | bundle, conbee, ddb, ddf, deconz, drezden |

## Links

- npm: https://www.npmjs.com/package/@deconz-community/ddf-validator
- Repository: https://github.com/deconz-community/ddf-tools
- Homepage: https://github.com/deconz-community/ddf-tools/tree/main/packages/validator
- Issues: https://github.com/deconz-community/ddf-tools/issues/
- Funding: https://github.com/sponsors/Zehir
- npm.io page: https://npm.io/package/@deconz-community/ddf-validator

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^4.6.7

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 2.37.0 (latest) — 2026-10-21
- 2.36.1 — 2026-04-22
- 2.36.0 — 2026-04-22
- 2.35.0 — 2026-02-24
- 2.34.0 — 2026-01-18
- 2.33.2 — 2025-10-21
- 2.32.0 — 2024-10-16
- 2.31.1 — 2024-09-08
- 2.31.0 — 2024-06-17
- 2.30.2 — 2024-05-31
- 2.30.1 — 2024-05-28
- 2.30.0 — 2024-05-25
- 2.29.0 — 2024-05-08
- 2.28.0 — 2024-05-01
- 2.27.2 — 2024-04-28
- … 38 more at https://npm.io/package/@deconz-community/ddf-validator/versions

## README

# DDF validator

The complete solution for validating DDF File.

- [Installation](#installation)
- [Quick Start](#quick-start)

## Installation

```sh
npm install @deconz-community/ddf-validator
```

## Quick Start

You can validate all DDF in a specefic directory using the example below. The validate method will return the validated data or will throw a [Zod Error](https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md). You can use the package `zod-validation-error` to format the error for the user.

Example :

```js
import { readFile } from 'node:fs/promises'
import glob from 'fast-glob'
import { fromZodError } from 'zod-validation-error'
import { createValidator } from '@deconz-community/ddf-validator'

(async () => {
  const validator = createValidator()

  const genericFiles = await glob('test-data/generic/**/*.json')
  const ddfFiles = await glob('test-data/**/*.json', {
    ignore: '**/generic/**',
  })

  const genericFilesData = await Promise.all(genericFiles.map(
    async (filePath) => {
      const data = await readFile(filePath, 'utf-8')
      const decoded = JSON.parse(data)
      return { path: filePath, data: decoded }
    },
  ))

  // Sort to load consts first
  genericFilesData.sort((a, b) => a.data.schema.localeCompare(b.data.schema))

  genericFilesData.forEach((file) => {
    try {
      const result = validator.loadGeneric(file.data)
      console.log(`Loaded generic file${file.path}`)
    }
    catch (error) {
      console.error(`Error while loading file ${file.path} : ${fromZodError(error).message}`)
    }
  })

  ddfFiles.forEach((filePath) => {
    const data = await readFile(filePath, 'utf-8')
    const decoded = JSON.parse(data)
    try {
      const result = validator.validate(decoded)
      console.log(`Validated file ${file.path}`)
    }
    catch (error) {
      console.error(`Error while validating file ${file.path} : ${fromZodError(error).message}`)
    }
  })
})()
```

## API

### createValidator()

Main function to validate the DDF data object.

#### Arguments

- `generics` - : GenericsData; Base generic data to validate DDF.

#### Return

Return a new validator instance.

#### Example

```typescript
import { createValidator } from '@deconz-community/ddf-validator'

const validator = createValidator({
  attributes: ['attr/id']
  manufacturers: { "$MF_FOO": "Foo inc." }
  deviceTypes: { "$TYPE_COLOR_LIGHT": "Color light" }
})

```

### validator.generics

Currently loaded generics.

#### Return

- `generics` - : GenericsData; Generic data to validate DDF.

### validator.loadGeneric()

Load generic data from an object.
Support files with schema `constants1.schema.json`, `constants2.schema.json`, `resourceitem1.schema.json` and `subdevice1.schema.json`.

#### Arguments

- `data` - : object; File data.

#### Return

- `data` - : object; File data.

Or throw [Zod Error](https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md)

#### Example

```typescript
import { createValidator } from "@deconz-community/ddf-validator";

const validator = createValidator();
validator.loadGeneric({
  schema: "constants1.schema.json",
  manufacturers: {
    $MF_FOO: "Foo inc.",
  },
  "device-types": {
    $TYPE_COLOR_LIGHT: "Color light",
  },
});
```

### validator.validate()

Validate DDF data from an object.
Support files with schema `constants1.schema.json`, `constants2.schema.json`, `resourceitem1.schema.json`, `subdevice1.schema.json` and `devcap1.schema.json`.
Make sure to load any need generic first.

#### Arguments

- `data` - : object; File data.

#### Return

- `data` - : object; File data.

Or throw [Zod Error](https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md)

#### Example

```typescript
import { createValidator } from "@deconz-community/ddf-validator";

const validator = createValidator();
validator.validate({
  schema: "constants1.schema.json",
  manufacturers: {
    $MF_FOO: "Foo inc.",
  },
  "device-types": {
    $TYPE_COLOR_LIGHT: "Color light",
  },
});
```

### validator.bulkValidate()

Validate both generic and DDF data from two arrays

#### Arguments

- `genericFiles` - : FileDefinition[]; Generic files data.
- `ddfFiles` - : FileDefinition[]; DDF files data.
- `callbacks` - : object; Options.
  - `onSectionStart` - : function; Called when a section start.
  - `onSectionProgress` - : function; Called when a section progress.
  - `onSectionEnd` - : function; Called when a section end.

#### Return

- `errors` - : FileDefinitionWithError[]; File definition with errors.

#### Example

```typescript
validator.bulkValidate(genericFiles, ddfFiles, {
  onSectionStart: (type, total) => {
    spinner.start(chalk.blue(`Parsing ${typeFilesText(type, total)} 1 of ${total}`));
  },
  onSectionProgress: (type, current, total) => {
    spinner.text = chalk.blue(`Parsing ${typeFilesText(type, total)} ${current} of ${total}`);
    spinner.render();
  },
  onSectionEnd(type, total, errorFiles) {
    if (errorFiles.length === 0)
      return spinner.succeed(
        chalk.green(`No errors found in ${files.length} ${typeFilesText(type, total)}`),
      );

    spinner.fail(
      chalk.red(
        `Found ${errorFiles.length} ${plural("error", "errors", errorFiles.length)} in ${files.length} ${typeFilesText(type, total)}`,
      ),
    );

    errorFiles.forEach(({ path, error }) => {
      let message = "";
      try {
        message = fromZodError(error, {
          issueSeparator: "\n    ",
          prefix: null,
        }).message;
      } catch (e) {
        message = error.toString();
      }
      console.log(`  ${chalk.cyan("File:")}`, path);
      console.log(`    ${chalk.red(message)}`);
    });
  },
});
```

### validator.getSchema()

Return Zod schema with loaded generic data.

#### Return

- `schema` - : ZodType<DDF>; Zod Schema.

#### Example

```typescript
import { createValidator } from "@deconz-community/ddf-validator";
import { toJSONSchema } from "zod";

const validator = createValidator();
const schemaJson = toJSONSchema(validator.getSchema(), { unrepresentable: "any" });
```

### Type definition

### DDF

The type definition of a valid DDF file. Contain union type for `constants1.schema.json`, `resourceitem1.schema.json`, `subdevice1.schema.json` and `devcap1.schema.json`.

#### Example

```typescript
import type { DDF } from "@deconz-community/ddf-validator";

const data = {} as DDF;
```

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