Registry / devops / semantic-schema

semantic-schema

library0.4.5jsnpmunverified

A library for writing JSON Schema definitions in a more concise, semantic way. Current stable version 0.4.5. It reduces verbosity by allowing schema declarations using familiar JavaScript patterns (e.g., regex for strings, numbers with method chaining). Key differentiators include built-in sugar for common patterns (like arrays of allowed values), a validator class that wraps AJV, and the ability to normalize schemas to standard JSON Schema. Released as an npm package with infrequent updates, it is primarily aimed at developers who find raw JSON Schema too verbose.

devops

npm install semantic-schema

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SEMANTIC-SCHEMA

semantic-schema

devopsjavascriptv0.4.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

integer

✓ import { integer } from 'semantic-schema'

✗ const integer = require('semantic-schema').integer

CommonJS style works but ESM is preferred; named export from schema namespace

object

✓ import { object } from 'semantic-schema'

✗ const object = require('semantic-schema').schema.object

object is a top-level export from the package

Validator

✓ import { Validator } from 'semantic-schema'

✗ const Validator = require('semantic-schema').Validator

Validator is a named export, not default

Creates an object schema with required properties using sugar syntax, then validates data.

import { integer, string, object, Validator } from 'semantic-schema'; const schema = object().properties({ name: /^[A-Za-z]{5}$/, age: integer().min(0).max(120), gender: ['m', 'f'] }).requiredAll(); const validator = new Validator(schema); console.log(validator.validate({ name: 'Alice', age: 30, gender: 'f' })); // true console.log(validator.errorsText()); // '' console.log(validator.validate({ name: 'Bob', age: 200, gender: 'x' })); // false console.log(validator.errorsText()); // '...'

Debug

Known issues

gotchaThe Validator class uses AJV under the hood; AJV must be installed separately as a peer dependency.

fix

Run npm install ajv alongside semantic-schema.

affects: >=0.0.0

gotchaSugar syntax like integer().enum(1) creates a schema that only allows the exact value; but integer().enum(1,2) creates an enum of those values. This may be surprising when using arrays for enum: [1,2] actually means integer().enum(1,2).

fix

Be explicit about chaining, and note that array sugar is shorthand for enum.

affects: >=0.0.0

deprecatedThe method .validate() on Validator returns boolean; to get error details must call .errorsText() after validation. This is misleading because validate returns true/false but does not throw.

fix

Always check the return value and then call .errorsText() to get error messages.

affects: >=0.0.0

gotchaThe sugar for regex pattern is /^...$/; be careful with start/end anchors because by default pattern does not anchor, but sugar implicitly adds them.

fix

Use regex with ^ and $ explicitly; otherwise don't use regex sugar.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'validate')

Validator instance not created correctly, or schema passed is not a valid schema object.

fix

Ensure you create a new Validator from a schema: const validator = new Validator(schema);

Ajv is not defined

Missing peer dependency ajv.

fix

Install ajv: npm install ajv

schema.normalize is not a function

Calling normalize on a plain object or a sugar like string() without proper schema builder.

fix

Use schema builders (e.g., integer()) and chain methods; sugar objects like /regex/ cannot be normalized directly.

Upgrade

Version history

0.4.5latest on npm

Audit

Dependencies

ajvrequiredUsed internally for validation in the Validator class

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/magnuslim/semantic-schema ↗

packagesemantic-schema ↗

homepagehttps://github.com/magnuslim/semantic-schema#readme ↗