simpl-schema

library3.4.7jsnpmunverified

SimpleSchema is a mature, isomorphic JavaScript object validation library (v3.4.7, 2025) that validates and cleans objects, including MongoDB update modifier documents. Written in TypeScript with ESM and CJS support, it has been maintained for 10+ years, features nearly 500 tests, and is used by Mailchimp Open Commerce and Meteor packages. Key differentiators: direct validation of MongoDB update documents, automatic cleaning (type conversion, removal of unsupported properties), powerful customizable error messages with i18n support, and TypeScript types. Slower and more complex than alternatives like Joi or yup, but offers unique MongoDB modifiers support and a mature ecosystem.

database

npm install simpl-schema

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIMPL-SCHEMA

simpl-schema

databasejavascriptv3.4.7

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.

SimpleSchema

✓ import SimpleSchema from 'simpl-schema'

✗ const SimpleSchema = require('simpl-schema')

Default export; both ESM and CJS supported. The require pattern works in Node, but ESM is preferred for modern projects.

MongoObject

✓ import { MongoObject } from 'simpl-schema'

✗ import MongoObject from 'simpl-schema'

Named export, not default. Used internally for MongoDB modifier support.

SimpleSchemaValidationContext

✓ import type { SimpleSchemaValidationContext } from 'simpl-schema'

✗ import { SimpleSchemaValidationContext } from 'simpl-schema'

TypeScript type import. Do not use as value.

Shows schema definition, validation (with throw and error collection), MongoDB update modifier validation, and automatic cleaning.

import SimpleSchema from 'simpl-schema'; const schema = new SimpleSchema({ name: String, age: { type: Number, min: 0 }, }); // Validate and throw on error const obj = { name: 'Alice', age: 30 }; try { schema.validate(obj); console.log('Valid!'); } catch (e) { console.error(e.message); } // Validate and get errors (no throw) const context = schema.newContext(); context.validate(obj); if (!context.isValid()) { console.log(context.validationErrors()); } // Validate a MongoDB update modifier const modifier = { $set: { name: 'Bob', age: 25 } }; schema.validate(modifier, { modifier: true }); // Clean before validation const dirty = { name: ' Alice ', age: '30' }; schema.clean(dirty); // trims string, converts type schema.validate(dirty);

Debug

Known issues

gotchaWhen using MongoDB modifier validation, you must pass { modifier: true } option, otherwise validation treats the modifier as a regular object and will fail.

fix

Always pass { modifier: true } to schema.validate() or schema.clean() when validating or cleaning MongoDB update modifier objects.

affects: >0.0.0

gotchaIn v3, SimpleSchema no longer extends native objects. Use 'extend' method instead of 'extend' on the constructor.

fix

Use schema.extend(subschema) instead of SimpleSchema.extend(subschema).

affects: >=3.0.0

deprecatedDirect use of SimpleSchema constructor as a function without 'new' is deprecated.

fix

Always use 'new SimpleSchema(...)' to instantiate.

affects: >=2.0.0

breakingIn v2.0.0, the package was renamed from 'simpl-schema' (formerly 'simple-schema'). Ensure package name is 'simpl-schema'.

fix

Update import/require statements to use 'simpl-schema'.

affects: >=2.0.0

gotchaWhen using custom validation, errors must be thrown or added to the context. Returning a string does not automatically add an error.

fix

Use context.addInvalidError(...) or throw a validation error inside custom validation functions.

affects: >0.0.0

Errors

Common errors & fixes

SimpleSchema is not a constructor

Using SimpleSchema without 'new' or importing default incorrectly in ESM.

fix

Ensure you use 'new SimpleSchema(...)' and import correctly: import SimpleSchema from 'simpl-schema'

Cannot find module 'simpl-schema'

Package not installed or incorrect import path.

fix

Run 'npm install simpl-schema' and verify import: import SimpleSchema from 'simpl-schema'

Validation error: Object did not match modifier schema

Missing { modifier: true } option when validating a MongoDB update modifier.

fix

Pass { modifier: true } to schema.validate() or schema.clean().

Context validation errors array is empty even though object is invalid

Using schema.validate() that throws errors instead of using schema.newContext().

fix

Use schema.newContext() to get a context, then call context.validate(obj) to collect validation errors without throwing.

TypeError: schema.clean is not a function

Using schema.clean without calling 'clean' method on an instance (e.g., calling SimpleSchema.clean statically).

fix

Schema must be instantiated with 'new SimpleSchema()' and then call schema.clean().

Upgrade

Version history

3.4.7latest on npm

Audit

Dependencies

lodashrequiredUsed internally for object operations (merge, clone, etc.).

bsonoptionalRequired for MongoDB ObjectID support and modifier validation.

Agent activity

8 hits · last 30 days

node