schiva 0.1.0 → 0.2.0

package/README.md

@@ -1,20 +1,56 @@
 # schiva
 
+[![npm](https://img.shields.io/npm/v/schiva.svg)](https://www.npmjs.com/package/schiva)
+[![CI](https://github.com/jesus-seijas-sp/schiva/actions/workflows/ci.yml/badge.svg)](https://github.com/jesus-seijas-sp/schiva/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
+
 Fast schema validation for JavaScript. Describe data with a small schema DSL or with JSON Schema (draft-07), and
 schiva compiles it into a JavaScript function generated for that schema, so validating is several times faster than
 walking the schema for every value.
 
-- Passes the whole draft-07 [JSON-Schema-Test-Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
-  (929 of 929 tests), including `$ref` to other documents.
-- Readable error messages with the path of each field: `lines[12].price must be a number`.
-- Three modes: every error, the first error only, or just `true`/`false`.
-- No dependencies. Unknown or unsupported keywords throw instead of being silently ignored.
+**Documentation: [schiva.js.org](https://schiva.js.org)**
+
+## Contents
+
+- [Features](#features)
+- [Install](#install)
+- [Getting started](#getting-started)
+- [Modes](#modes)
+- [Compile once](#compile-once)
+- [Schema DSL](#schema-dsl)
+- [JSON Schema](#json-schema)
+- [Errors](#errors)
+- [Types of your own](#types-of-your-own)
+- [Security considerations](#security-considerations)
+- [Performance](#performance)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Two schema languages, one engine**: a small DSL (`String()`, `Integer({ min: 18 })`...) and JSON Schema draft-07
+  compile to the same types and the same generated code.
+- **Complete draft-07**: passes the whole [JSON-Schema-Test-Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
+  for draft-07 (929 of 929 tests), including `$ref` with JSON pointers, `$id` base URIs, anchors, recursive schemas
+  and references to other documents.
+- **Readable errors** with the path of each field: `lines[12].price must be a number`.
+- **Three modes**: every error, the first error only, or just `true`/`false`.
+- **Fast**: faster than ajv in every [benchmark](#performance) we run, and about 50 times faster at compiling.
+- **Strict**: unknown or unsupported keywords throw when compiling instead of being silently ignored.
+- **No dependencies**, CommonJS and ESM, Node.js 18 and later, and browsers through any bundler.
+- **Extensible**: classes of your own with a `validate()` method work inside compiled schemas.
+
+## Install
 
 ```sh
 npm install schiva
 ```
 
-## Quick start
+## Getting started
+
+With the schema DSL:
 
 ```js
 const { ClosedSchema, String, Integer, ArrayOf } = require('schiva');
@@ -36,7 +72,7 @@ validatePerson({ id: 1, age: 10, extra: 1 });
 With JSON Schema:
 
 ```js
-const { compileJsonSchema } = require('schiva');
+import { compileJsonSchema } from 'schiva';
 
 const validate = compileJsonSchema({
   type: 'object',
@@ -48,6 +84,8 @@ validate({ id: 'AB' }); // []
 validate({ id: 'ab' }); // ['id does not match the required pattern']
 ```
 
+`require('schiva')` and `import { ... } from 'schiva'` export the same names.
+
 ## Modes
 
 `compile(options)` (on schemas and on every type) and `compileJsonSchema(json, options)` return a function:
@@ -58,6 +96,14 @@ validate({ id: 'ab' }); // ['id does not match the required pattern']
 | `{ allErrors: false }` | only the first error message, `[]` when valid | one message is enough; stops at the first failing check |
 | `{ errors: false }` | `true` or `false` | only validity matters; builds no messages |
 
+```js
+const isPerson = person.compile({ errors: false });
+
+if (!isPerson(body)) {
+  // reject the request
+}
+```
+
 Schemas and types also have `validate(value)`, which checks without compiling (10 to 25 times slower), and
 `isValid(value)`.
 
@@ -68,27 +114,43 @@ The compiled function is a snapshot of the schema: changes made to the schema or
 again if it changes. Compiling takes about 0.1 ms for a schema of moderate size, so compile when the program starts
 (or cache the function), not for every value.
 
+```js
+// Good: compiled once, reused for every request.
+const validateOrder = orderSchema.compile();
+app.post('/orders', (req, res) => {
+  const errors = validateOrder(req.body);
+  if (errors.length) return res.status(400).json({ errors });
+  // ...
+});
+```
+
 The generated code uses `new Function`, so it does not run where code generation is forbidden (for example with a
-strict Content Security Policy).
+strict Content Security Policy). See [Security considerations](#security-considerations).
 
 ## Schema DSL
 
 A `Schema` takes an object whose keys are the expected properties. Plain objects inside it become nested schemas.
 
 ```js
-const { Schema, String, Float, Enum } = require('schiva');
+const { Schema, String, Float, Enum, ArrayOf, Integer } = require('schiva');
 
 const order = new Schema(
   {
     id: String({ pattern: /^ORD-\d{8}$/ }),
     status: Enum({ options: ['draft', 'placed'] }),
     customer: { name: String({ min: 1 }), email: String({ isMandatory: false }) },
+    lines: ArrayOf({ type: { sku: String(), qty: Integer({ min: 1 }) }, min: 1 }),
     total: Float({ min: 0 }),
   },
   { isOpen: false }
 );
 ```
 
+Wherever a type is expected (`ArrayOf`, `AnyOf`, `Not`, `additionalType`...), a plain object stands for
+`new Schema(object)`, as `lines` shows above. That schema is open even inside a `ClosedSchema`; write
+`new ClosedSchema({ ... })` to reject unknown keys there too. A value that is neither a type nor an object of types
+throws when the type is built.
+
 Every type takes `isMandatory` (default `true`: `undefined` is an error) and `isNullable` (default `false`: `null` is
 an error), and has `.optional()`, `.required()`, `.nullable()` and `.notNull()`.
 
@@ -111,11 +173,27 @@ Schema options: `isOpen` (default `true`; `ClosedSchema` sets it to `false` and
 `dependencies` (`[{ key, required: [...] }]` or `[{ key, type }]`), `isMandatory`, `isNullable`.
 
 Short helpers are also exported: `str`, `int`, `float`, `bool`, `arrOf`, `obj`, `any`, `anyOf`, `allOf`, `oneOf`,
-`not`, `enumt`, and optional versions prefixed with `o` (`ostr`, `oint`...).
+`not`, `enumt`, and optional versions prefixed with `o` (`ostr`, `oint`...). `arrOf(String())` and
+`arrOf({ sku: String() })` take the type of the elements; `arrOf({ type, min, ... })` takes the options.
 
 Declared keys are read as own properties only, so `{}.toString` or a key added to `Object.prototype` never counts as
 present.
 
+### Recursive schemas
+
+Create the `Ref` first and point it at the schema once the schema exists:
+
+```js
+const { Schema, Integer, ArrayOf, Ref } = require('schiva');
+
+const child = Ref();
+const node = new Schema({ value: Integer(), children: ArrayOf({ type: child, isMandatory: false }) });
+child.target = node;
+
+node.compile()({ value: 1, children: [{ value: 2, children: [{ value: 'x' }] }] });
+// ['children[0].children[0].value must be a number']
+```
+
 ## JSON Schema
 
 `fromJsonSchema(json, options)` converts a JSON Schema (draft-07) into the same types, and
@@ -123,6 +201,19 @@ present.
 `definitions` and `$ref` (JSON pointers, `$id` base URIs and anchors, recursive schemas). String lengths count Unicode
 code points, as the specification says.
 
+A keyword schiva does not know throws when compiling, with the place where it was found:
+
+```js
+compileJsonSchema({ type: 'string', maxLenght: 10 });
+// Error: Unsupported JSON Schema keyword "maxLenght" at #
+```
+
+Annotations (`title`, `description`, `default`, `examples`, `$comment`, `readOnly`, `writeOnly`, `deprecated`) are
+accepted and ignored. So is **`format`**: draft-07 makes checking it optional, and schiva does not check it. Use
+`pattern`, or a [type of your own](#types-of-your-own), for values such as emails or dates.
+
+### Several documents
+
 References to other documents resolve against the documents given in `options.schemas`, as `{ uri: schema }` or as an
 array of schemas with `$id`. Nothing is loaded from the network, and a reference that cannot be resolved throws when
 compiling:
@@ -136,16 +227,68 @@ const validateOrder = compileJsonSchema(orderSchema, {
 To validate schemas against the draft-07 meta-schema, register it in `schemas` (ajv ships a copy as
 `ajv/dist/refs/json-schema-draft-07.json`).
 
+## Errors
+
+Errors are plain strings that start with the path of the field, so they can be logged or returned as they are:
+
+```js
+[
+  'customer.name is mandatory',
+  'lines[1].sku must be a string',
+  'lines[1].price must be at least 0',
+  'Unexpected key: extra',
+];
+```
+
+A value checked on its own (not inside a schema) is called `Value`: `Integer().compile()('x')` returns
+`['Value must be a number']`.
+
 ## Types of your own
 
 Classes that extend `ValidateType` (or a built-in type) with their own `validate()` or `isValid()` keep working when
-compiled: the generated code calls them for their part of the schema.
+compiled: the generated code calls them for their part of the schema. `validate()` returns `undefined` when the value
+is valid and an error message otherwise.
+
+```js
+const { Schema, ValidateType } = require('schiva');
+
+class Even extends ValidateType {
+  validate(value, fieldName = 'Value') {
+    const presence = super.validate(value, fieldName); // isMandatory and isNullable
+    if (presence !== undefined || value === undefined || value === null) return presence;
+    return value % 2 === 0 ? undefined : `${fieldName} must be even`;
+  }
+}
+
+new Schema({ n: new Even() }).compile()({ n: 3 }); // ['n must be even']
+```
 
-## Speed
+## Security considerations
+
+- **Schemas are code.** Compiling turns a schema into JavaScript, so treat schemas like the code of your program:
+  compile schemas you wrote or trust, not schemas sent by users. A large or deeply nested schema is slow to compile
+  and to validate.
+- **Regular expressions.** `pattern`, `patternProperties` and `String({ pattern })` run the regular expression you
+  give them on the data. A badly written one can take exponential time on some inputs
+  ([ReDoS](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS)). Keep them simple,
+  and limit the length of strings (`maxLength`, `String({ max })`) before matching long input.
+- **Every error or the first one.** Collecting every error keeps checking after the first failure, so an invalid
+  value costs more. For untrusted input where one message is enough, use `{ allErrors: false }` or `{ errors: false }`.
+- **Large inputs.** `uniqueItems`/`unique` compares items with each other, so limit the size of arrays
+  (`maxItems`, `ArrayOf({ max })`) that come from outside.
+- **Content Security Policy.** The generated code is created with `new Function`, which needs `'unsafe-eval'` in the
+  `script-src` of a Content Security Policy. Where that is not allowed, use `validate()` and `isValid()`, which do not
+  generate code.
+- **Circular data.** Values that contain themselves (`a.self = a`) are not supported.
+
+Report security problems privately through [GitHub security advisories](https://github.com/jesus-seijas-sp/schiva/security/advisories/new),
+not in public issues.
+
+## Performance
 
 Compared with ajv and the other validators of
 [json-schema-benchmark](https://github.com/ebdrup/json-schema-benchmark), each measurement in its own process
-(see `bench/`):
+(see [`bench/`](bench)):
 
 | | schiva | ajv | @exodus/schemasafe |
 |---|---|---|---|
@@ -161,6 +304,32 @@ pnpm run bench         # every validator in its own process (about 8 minutes)
 pnpm run bench:quick   # every validator in one process (about a minute)
 ```
 
+## FAQ
+
+**Should I use the DSL or JSON Schema?** Use JSON Schema when the schema is shared with other languages or tools
+(OpenAPI, forms, other services). Use the DSL when the schema lives in your JavaScript code: it is shorter, and
+`RegExp` patterns and types of your own fit in directly. Both compile to the same code, so the speed is the same.
+
+**Why are errors strings and not objects?** Most errors end up in a log or an HTTP response. Strings with the path in
+front are ready for that, and building them is cheap. If you only need to know whether a value is valid, use
+`{ errors: false }`.
+
+**Does it support draft 2019-09 or 2020-12?** Not yet: schiva implements draft-07. Keywords from later drafts, such as
+`unevaluatedProperties` or `$defs`, throw when compiling.
+
+**Does it check `format`?** No, see [JSON Schema](#json-schema).
+
+**Does it include TypeScript types?** Not yet.
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/jesus-seijas-sp/schiva](https://github.com/jesus-seijas-sp/schiva).
+
+```sh
+pnpm install
+pnpm test        # ESLint and Jest with coverage
+```
+
 ## License
 
-MIT
+[MIT](LICENSE)

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "schiva",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Fast schema validation for JavaScript: a schema DSL and JSON Schema (draft-07), compiled to generated code",
+  "homepage": "https://schiva.js.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jesus-seijas-sp/schiva.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jesus-seijas-sp/schiva/issues"
+  },
   "main": "./src/index.js",
   "type": "commonjs",
   "files": [
@@ -14,7 +22,11 @@
     "json-schema",
     "draft-07",
     "compiler",
-    "fast"
+    "fast",
+    "jsonschema",
+    "schema-validation",
+    "dsl",
+    "ajv-alternative"
   ],
   "author": "Jesús Seijas <jseijas@gmail.com>",
   "license": "MIT",

package/src/index.js

@@ -1,13 +1,151 @@
-const closedSchema = require('./closed-schema');
-const compile = require('./compile');
-const jsonSchema = require('./json-schema');
-const schema = require('./schema');
-const types = require('./types');
+const { ClosedSchema } = require('./closed-schema');
+const { compileErrors, compileFirstError, compileIsValid, compileType } = require('./compile');
+const { fromJsonSchema, compileJsonSchema } = require('./json-schema');
+const { Schema } = require('./schema');
+const {
+  AllOfType,
+  AllOf,
+  allOf,
+  oallOf,
+  AnyType,
+  Any,
+  any,
+  oany,
+  AnyOfType,
+  AnyOf,
+  anyOf,
+  oanyOf,
+  ArrayOfType,
+  ArrayOf,
+  arrOf,
+  oarrOf,
+  BooleanType,
+  Boolean,
+  bool,
+  obool,
+  ConditionalType,
+  Conditional,
+  EnumType,
+  Enum,
+  enumt,
+  oenumt,
+  oenum,
+  FloatType,
+  Float,
+  float,
+  ofloat,
+  num,
+  onum,
+  IntegerType,
+  Integer,
+  int,
+  oint,
+  NeverType,
+  Never,
+  never,
+  NotType,
+  Not,
+  not,
+  onot,
+  ObjType,
+  Obj,
+  obj,
+  oobj,
+  OneOfType,
+  OneOf,
+  oneOf,
+  ooneOf,
+  RefType,
+  Ref,
+  StringType,
+  String,
+  str,
+  ostr,
+  ValidateType,
+  hasErrors,
+  toErrors,
+  ValuesType,
+  Values,
+  Const,
+  WhenType,
+  When,
+  isJsonType,
+} = require('./types');
 
 module.exports = {
-  ...closedSchema,
-  ...compile,
-  ...jsonSchema,
-  ...schema,
-  ...types,
+  ClosedSchema,
+  compileErrors,
+  compileFirstError,
+  compileIsValid,
+  compileType,
+  fromJsonSchema,
+  compileJsonSchema,
+  Schema,
+  AllOfType,
+  AllOf,
+  allOf,
+  oallOf,
+  AnyType,
+  Any,
+  any,
+  oany,
+  AnyOfType,
+  AnyOf,
+  anyOf,
+  oanyOf,
+  ArrayOfType,
+  ArrayOf,
+  arrOf,
+  oarrOf,
+  BooleanType,
+  Boolean,
+  bool,
+  obool,
+  ConditionalType,
+  Conditional,
+  EnumType,
+  Enum,
+  enumt,
+  oenumt,
+  oenum,
+  FloatType,
+  Float,
+  float,
+  ofloat,
+  num,
+  onum,
+  IntegerType,
+  Integer,
+  int,
+  oint,
+  NeverType,
+  Never,
+  never,
+  NotType,
+  Not,
+  not,
+  onot,
+  ObjType,
+  Obj,
+  obj,
+  oobj,
+  OneOfType,
+  OneOf,
+  oneOf,
+  ooneOf,
+  RefType,
+  Ref,
+  StringType,
+  String,
+  str,
+  ostr,
+  ValidateType,
+  hasErrors,
+  toErrors,
+  ValuesType,
+  Values,
+  Const,
+  WhenType,
+  When,
+  isJsonType,
 };

package/src/schema.js

@@ -1,4 +1,4 @@
-const { ObjType, ValidateType } = require('./types');
+const { ObjType, ValidateType, toType } = require('./types');
 
 // Declared keys are read as own properties only: {}.toString or {}.constructor must not count as present.
 // A value read from a plain object is its own unless Object.prototype has the key, which avoids the slower
@@ -22,16 +22,21 @@ class Schema {
     this.isMandatory = options.isMandatory === undefined ? true : options.isMandatory;
     this.isNullable = options.isNullable === undefined ? false : options.isNullable;
     // Type that keys not declared in the schema must satisfy (only used when the schema is open).
-    this.additionalType = options.additionalType;
+    this.additionalType = toType(options.additionalType, 'Schema additionalType');
     // [{ pattern, type }]: keys matching a pattern must satisfy its type, and are not checked by additionalType.
-    this.patternTypes = options.patternTypes || [];
+    this.patternTypes = (options.patternTypes || []).map((item, i) => ({
+      ...item,
+      type: toType(item.type, `Schema patternTypes[${i}].type`),
+    }));
     this.minProperties = options.minProperties;
     this.maxProperties = options.maxProperties;
     // [{ key, required: [properties] } or { key, type }]: when key is present, the properties must be present too,
     // or the whole object must satisfy type.
-    this.dependencies = options.dependencies || [];
+    this.dependencies = (options.dependencies || []).map((item, i) =>
+      item.type === undefined ? item : { ...item, type: toType(item.type, `Schema dependencies[${i}].type`) }
+    );
     // Type every key must satisfy, reported as "Key <name>".
-    this.propertyNameType = options.propertyNameType;
+    this.propertyNameType = toType(options.propertyNameType, 'Schema propertyNameType');
     this.visitObjs();
     this.keys = Object.keys(this.schema);
     this.keySet = new Set(this.keys);

package/src/types/all-of.js

@@ -1,10 +1,10 @@
-const { ValidateType } = require('./validate-type');
+const { ValidateType, toTypes } = require('./validate-type');
 
 // Value must satisfy every type; reports the errors of the first type that fails.
 class AllOfType extends ValidateType {
   constructor(options = {}) {
     super(options);
-    this.types = options.types || [];
+    this.types = toTypes(options.types, 'AllOf types') || [];
   }
 
   validate(value, fieldName = 'Value') {

package/src/types/any-of.js

@@ -1,9 +1,9 @@
-const { ValidateType } = require('./validate-type');
+const { ValidateType, toTypes } = require('./validate-type');
 
 class AnyOfType extends ValidateType {
   constructor(options = {}) {
     super(options);
-    this.types = options.types;
+    this.types = toTypes(options.types, 'AnyOf types');
   }
 
   validate(value, fieldName = 'Value') {

package/src/types/array-of.js

@@ -1,18 +1,20 @@
 const { hasDuplicates } = require('./has-duplicates');
-const { ValidateType } = require('./validate-type');
+const { ValidateType, isPlainObject, toType, toTypes } = require('./validate-type');
 
 class ArrayOfType extends ValidateType {
   constructor(options = {}) {
     super(options);
     // A type for every element, or an array of types for the elements at each position (a tuple).
-    this.type = options.type;
+    this.type = Array.isArray(options.type)
+      ? toTypes(options.type, 'ArrayOf type')
+      : toType(options.type, 'ArrayOf type');
     this.min = options.min;
     this.max = options.max;
     this.unique = options.unique;
     // At least one element must satisfy it.
-    this.contains = options.contains;
+    this.contains = toType(options.contains, 'ArrayOf contains');
     // With a tuple, the elements after its last position must satisfy it.
-    this.additionalType = options.additionalType;
+    this.additionalType = toType(options.additionalType, 'ArrayOf additionalType');
   }
 
   hasMatch(value) {
@@ -115,15 +117,27 @@ function ArrayOf(options) {
   return new ArrayOfType(options);
 }
 
+const OPTION_KEYS = ['type', 'min', 'max', 'unique', 'contains', 'additionalType', 'isMandatory', 'isNullable'];
+
+// The first argument of arrOf() is the options when it is a plain object that is empty or has an option key;
+// otherwise it is the type of the elements (a type, a schema, or a plain object of types).
+function isOptions(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  return keys.length === 0 || keys.some((key) => OPTION_KEYS.includes(key));
+}
+
 function arrOf(type, min, max, isMandatory = true, isNullable = false) {
-  if (type !== undefined && type !== null && typeof type === 'object') {
+  if (isOptions(type)) {
     return new ArrayOfType(type);
   }
   return new ArrayOfType({ type, min, max, isMandatory, isNullable });
 }
 
 function oarrOf(type, min, max, isMandatory = false, isNullable = false) {
-  if (type !== undefined && type !== null && typeof type === 'object') {
+  if (isOptions(type)) {
     return new ArrayOfType({ isMandatory: false, ...type });
   }
   return new ArrayOfType({ type, min, max, isMandatory, isNullable });

package/src/types/conditional.js

@@ -1,13 +1,13 @@
-const { ValidateType } = require('./validate-type');
+const { ValidateType, toType } = require('./validate-type');
 
 // When the value satisfies `ifType` it must satisfy `thenType`, otherwise `elseType`; a missing branch accepts
 // anything. Only the errors of the branch are reported, like JSON Schema if/then/else.
 class ConditionalType extends ValidateType {
   constructor(options = {}) {
     super(options);
-    this.ifType = options.ifType;
-    this.thenType = options.thenType;
-    this.elseType = options.elseType;
+    this.ifType = toType(options.ifType, 'Conditional ifType');
+    this.thenType = toType(options.thenType, 'Conditional thenType');
+    this.elseType = toType(options.elseType, 'Conditional elseType');
   }
 
   branch(value) {

package/src/types/not.js

@@ -1,10 +1,10 @@
-const { ValidateType } = require('./validate-type');
+const { ValidateType, toType } = require('./validate-type');
 
 // Value must not satisfy `type`.
 class NotType extends ValidateType {
   constructor(options = {}) {
     super(options);
-    this.type = options.type;
+    this.type = toType(options.type, 'Not type');
   }
 
   validate(value, fieldName = 'Value') {

package/src/types/one-of.js

@@ -1,10 +1,10 @@
-const { ValidateType } = require('./validate-type');
+const { ValidateType, toTypes } = require('./validate-type');
 
 // Value must satisfy exactly one of the types. When none does, reports the errors of every type, like AnyOfType.
 class OneOfType extends ValidateType {
   constructor(options = {}) {
     super(options);
-    this.types = options.types || [];
+    this.types = toTypes(options.types, 'OneOf types') || [];
   }
 
   // Number of types the value satisfies, counting up to 2.

package/src/types/ref.js

@@ -1,4 +1,4 @@
-const { ValidateType } = require('./validate-type');
+const { ValidateType, toType } = require('./validate-type');
 
 // Validates with the type it refers to, which is set once references are resolved; recursive schemas refer back to a
 // type that contains the reference. Only undefined is handled here (isMandatory); null and other values go to the
@@ -7,7 +7,7 @@ class RefType extends ValidateType {
   constructor(options = {}) {
     super(options);
     this.ref = options.ref;
-    this.target = options.target;
+    this.target = toType(options.target, 'Ref target');
   }
 
   getTarget() {

package/src/types/validate-type.js

@@ -91,8 +91,46 @@ function toErrors(result) {
   return result ? [result] : [];
 }
 
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+// Normalizes an option that holds a type. A plain object stands for new Schema(object), as it does for a key of a
+// Schema; other objects (types, schemas) are kept; anything else throws now instead of failing when validating.
+function toType(value, name) {
+  if (value === undefined || value instanceof ValidateType) {
+    return value;
+  }
+  if (isPlainObject(value)) {
+    // eslint-disable-next-line global-require -- schema.js requires this module
+    const { Schema } = require('../schema');
+    return new Schema(value);
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${name} must be a type or an object of types`);
+  }
+  return value;
+}
+
+function toTypes(values, name) {
+  if (values === undefined) {
+    return values;
+  }
+  if (!Array.isArray(values)) {
+    throw new TypeError(`${name} must be an array of types`);
+  }
+  return values.map((value, i) => toType(value, `${name}[${i}]`));
+}
+
 module.exports = {
   ValidateType,
   hasErrors,
   toErrors,
+  isPlainObject,
+  toType,
+  toTypes,
 };

package/src/types/when.js

@@ -1,4 +1,4 @@
-const { ValidateType } = require('./validate-type');
+const { ValidateType, toType } = require('./validate-type');
 
 const JSON_TYPES = ['object', 'array', 'string', 'number'];
 
@@ -25,7 +25,7 @@ class WhenType extends ValidateType {
       throw new Error(`WhenType jsonType must be one of: ${JSON_TYPES.join(', ')}`);
     }
     this.jsonType = options.jsonType;
-    this.type = options.type;
+    this.type = toType(options.type, 'When type');
   }
 
   validate(value, fieldName) {