Registry / serialization / protodef-validator

protodef-validator

library1.4.0jsnpmunverified

ProtoDef-validator is a Node.js library specifically engineered to validate protocol definitions structured using the ProtoDef schema language. It offers a programmatic interface for verifying that custom data types and complete protocol schemas adhere to established structural and semantic rules. Currently stable at version 1.4.0, the package demonstrates an active release cadence with minor updates and dependency bumps, indicating ongoing maintenance. Its core utility lies in preempting issues in protocol definition files by programmatically enforcing their correctness, a critical function for ensuring data integrity and compatibility in binary serialization and network communication. A key differentiator is its singular focus on validating the structural soundness of the schema itself, rather than performing data serialization or deserialization, thereby acting as a foundational tool for developers working within the ProtoDef ecosystem.

serialization http-networking

npm install protodef-validator

github ↗package ↗

INSTALL

IMPORT

SIG · PROTODEF-VALIDATOR

protodef-validator

serializationjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Validator

✓ import { Validator } from 'protodef-validator';

✗ import Validator from 'protodef-validator';

The `Validator` class is a named export. Default imports will typically not work for this package in ESM contexts.

Validator (CommonJS)

✓ const { Validator } = require('protodef-validator');

✗ const Validator = require('protodef-validator');

While older CommonJS packages often export a default, `protodef-validator` exports `Validator` as a named property on its `module.exports` object. Direct `require('protodef-validator')` returns the module object, not the class directly.

CLI Usage

✓ npm install -g protodef-validator protodef-validator myProtocol.json

The package also provides a command-line interface for global installation and direct validation of protocol JSON files.

This quickstart demonstrates how to instantiate a Validator, add a custom type, define a simple protocol, and then validate both the custom type and the full protocol schema.

import { Validator } from 'protodef-validator'; const validator = new Validator(); // Add a custom type definition validator.addType('varint', ['pstring', { countType: 'i32' }]); // Define a simple protocol schema const simpleProtocol = { 'main': [ { 'name': 'id', 'type': 'i32' }, { 'name': 'value', 'type': 'varint' }, { 'name': 'items', 'type': ['array', { countType: 'i32', type: 'pstring' }] } ] }; try { // Validate the defined protocol validator.validateProtocol(simpleProtocol); console.log('Protocol validation successful!'); // Validate an individual type definition (e.g., 'varint') validator.validateType(['pstring', { countType: 'i32' }]); console.log('Individual type validation successful!'); // Example of an invalid type definition (will throw) // validator.validateType(['nonExistentType']); } catch (error) { console.error('Protocol validation failed:', error.message); }

Debug

Known issues

gotchaProtoDef-validator is tightly coupled with the ProtoDef specification. Breaking changes in the core ProtoDef specification (not necessarily this validator's API) can render existing protocol definitions invalid or cause unexpected validation behavior, requiring updates to your `.json` protocol files.

fix

Refer to the ProtoDef specification for the version you are targeting and update your protocol definition JSON files accordingly. Monitor the ProtoDef-io/ProtoDef repository for major changes.

affects: >=1.0.0

gotchaThis library relies on `ajv` for JSON schema validation. Upgrades to `ajv` (e.g., as seen in `protodef-validator` v1.2.1) could introduce stricter validation rules or changes in error reporting, potentially flagging previously valid but non-standard definitions as errors.

fix

When upgrading `protodef-validator`, review the `ajv` changelog for any breaking changes in schema validation behavior. Test your protocol definitions thoroughly against the new version.

affects: >=1.2.1

gotchaThe `addType` method with an unspecified schema defaults to a basic validation. For complex custom types, always provide an explicit schema to ensure precise validation behavior.

fix

Always explicitly define the schema when adding complex custom types using `Validator.addType(name, schema)` to prevent generic validation that might miss specific structural requirements.

affects: >=1.1.0

Errors

Common errors & fixes

Error: Type 'myCustomType' is not defined

Attempting to validate a protocol or type that references a custom type that has not been added to the Validator instance.

fix

Before validating, ensure all referenced custom types are added using `validator.addType(name, schema)` or `validator.addTypes(schemas)`.

Protocol validation failed: 'fieldName' is not a valid property in type 'parentType'

A field in the protocol definition does not conform to the expected schema for its parent type or an invalid property is used in a type definition.

fix

Review your protocol definition JSON for `fieldName` and its surrounding structure. Ensure all properties and their values adhere to the ProtoDef schema specification (e.g., `type`, `name`, `countType`, `endian`).

Error: Data path '.some.path' must NOT have additional properties

The protocol definition includes properties or attributes within a type definition that are not recognized or allowed by the underlying JSON schema validator (AJV).

fix

Check for typos or extraneous properties in your ProtoDef JSON. Ensure you are only using properties (like `name`, `type`, `countType`) that are valid within the ProtoDef schema context.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

ajvrequiredUsed internally for robust JSON Schema validation of ProtoDef definitions. Updates to AJV are noted in past releases (e.g., 1.2.1), indicating its role as a core dependency for the validation logic.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/ProtoDef-io/node-protodef-validator ↗

packagehttps://www.npmjs.com/package/protodef-validator ↗