# mikrovalid

> MikroValid is the JSON validator that cuts out all the bullshit.

Latest version **2.0.2** (published 2026-09-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install mikrovalid
pnpm add mikrovalid
yarn add mikrovalid
bun add mikrovalid
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.2 |
| Published | 2026-09-30 |
| First published | 2024-02-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 80.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 5 |
| Author | Mikael Vesavuori |
| Maintainers | mikaelvesavuori |
| Keywords | json, schema, validation, validator, schema-validation, object-validator |

## Links

- npm: https://www.npmjs.com/package/mikrovalid
- Repository: https://github.com/mikaelvesavuori/mikrovalid
- Homepage: https://github.com/mikaelvesavuori/mikrovalid#readme
- Issues: https://github.com/mikaelvesavuori/mikrovalid/issues
- npm.io page: https://npm.io/package/mikrovalid

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.0.2 (latest) — 2026-09-30
- 2.0.1 — 2026-09-30
- 2.0.0 — 2026-09-30
- 1.0.23 — 2024-07-10
- 1.0.22 — 2024-07-10
- 1.0.21 — 2024-06-18
- 1.0.20 — 2024-06-10
- 1.0.19 — 2024-05-07
- 1.0.18 — 2024-05-07
- 1.0.17 — 2024-04-27
- 1.0.16 — 2024-04-22
- 1.0.15 — 2024-04-21
- 1.0.14 — 2024-04-10
- 1.0.13 — 2024-04-05
- 1.0.12 — 2024-04-01
- … 13 more at https://npm.io/package/mikrovalid/versions

## README

# mikrovalid

**MikroValid is the minimalist, smart, and easy way to validate objects on both the client and server-side.**

![Build Status](https://github.com/mikaelvesavuori/mikrovalid/workflows/main/badge.svg)

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=mikaelvesavuori_mikrovalid&metric=alert_status)](https://sonarcloud.io/dashboard?id=mikaelvesavuori_mikrovalid)

[![Maintainability](https://api.codeclimate.com/v1/badges/d42f8b255d893431050f/maintainability)](https://codeclimate.com/github/mikaelvesavuori/mikrovalid/maintainability)

---

MikroValid is the JSON validator that cuts out all the bullshit:

- Dead easy, no proprietary stuff — uses simple JSON objects for schemas and input
- Doesn't pollute your code with "convenient" APIs
- Minimalist approach that will work for the majority of conventional-type objects
- Meant to work effortlessly in both client- and server-side environments
- Tiny (~2.2 KB gzipped), which is ~7-80x smaller than common, popular options
- Zero dependencies
- Has 100% test coverage

## Usage

### Basic importing and usage

```typescript
// ES5 format
const { MikroValid } = require('mikrovalid');
// ES6 format
import { MikroValid } from 'mikrovalid';

const mikrovalid = new MikroValid();

const schema = {
  properties: {
    personal: {
      name: {
        type: 'string'
      },
      required: ['name']
    },
    work: {
      office: {
        type: 'string'
      },
      currency: {
        type: 'string'
      },
      salary: {
        type: 'number'
      },
      required: ['office']
    },
    required: ['personal', 'work']
  },
};

const input = {
  personal: {
    name: 'Sam Person'
  },
  work: {
    office: 'London',
    currency: 'GBP',
    salary: 10000
  }
};

const generatedSchema = mikrovalid.schemaFrom(input); // <-- OPTIONAL: You can also generate a schema directly from your input!

const { success, errors } = mikrovalid.test(schema, input);

console.log('Was the test successful?', success);
```

### Warnings and silent mode

By default you will get warnings and non-critical message output. If you want to silence these message, you can instantiate MikroValid by passing `true` for the `isSilent` option, like so:

```ts
const mikrovalid = new MikroValid(true);
```

### Errors

The `errors` object includes an aggregation of any errors, both those relating to field-level validation and for inline failures emitted when not having required keys or having excess keys.

Since version `1.0.3` both error formats have the same shape:

```json
[{ "key": "blip", "value": 123, "success": false, "error": "Invalid type" }]
```

### Using schemas

The format is inspired by (but is not the same as, nor compliant with) [JSON Schema](https://json-schema.org).

The general shape it uses is:

```json
{
  "properties": {
    "username": {
      "type": "string"
    },
    "required": ["username"]
  }
}
```

A valid input for this particular schema is:

```json
{
  "username": "Sam Person"
}
```

Using the `schemaFrom()` method, you can easily generate schemas for your input. This is especially useful in a programmatic environment in which you can't decide or know before-hand what schema to create. Note that the generated schemas should work for the majority of cases, but you should try this functionality out before relying fully on it.

#### Properties

`properties` is the only **required** root-level object. Each key describes a property of the expected input. In the example, `name` is of the type `string`. Note that you never repeat the `properties` keyword—it's used only in the root.

#### Allowing or disallowing additional properties

By default, unknown properties will be allowed and valid. Setting `additionalProperties` to `false` enables you to disallow any unlisted properties.

Since version `1.0.10` it _only_ works in the direct scope of its location, as per below:

```json
{
  "properties": {
    "first": {
      "type": "string"
    },
    "second": {
      "type": "string"
    },
    "third": {
      "type": "string"
    },
    "additionalProperties": false
  }
}
```

A payload like this...

```json
{
  "first": "the first",
  "second": "the second",
  "third": "the third",
  "fourth": "the fourth"
}
```

...would therefore break the validation.

The same can be done with nested objects, by setting `additionalProperties` in the scope of the object:

```json
{
  "properties": {
    "blip": {
      "type": "string"
    },
    "inside": {
      "type": "object",
      "thing": {
        "type": "string"
      },
      "additionalProperties": false
    }
  }
}
```

So this would not work:

```json
{
  "blip": "beep bloop",
  "inside": {
    "thing": "scary monster",
    "somethingThatIsNotAllowed": "...?"
  }
}
```

#### Required

For each level of nesting, including within objects, a `required` key with an array of strings _may_ be used to describe properties that must exist at that location.

Even the lowest-level `required` will be _within_ the `properties` key after version `1.0.10`.

This example requires both the `personal_data` object, as well as the inner `name` string:

```json
{
  "properties": {
    "personal_data": {
      "type": "object",
      "name": { "type": "string" },
      "required": ["name"]
    },
    "required": ["personal_data"]
  }
}
```

#### Types

The `type` is the only **required** item-level object. Allowed types are:

- `string`
- `number`
- `boolean`
- `object`
- `array`

You can require basic validation of `array` items by setting the expected type in `items.type`:

```json
{
  "properties": {
    "books": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  }
}
```

For this schema, a valid input could for example be something like:

```json
{
  "books": [{ "author": "Cormac McCarthy" }, { "author": "William Blake" }]
}
```

Note that this will not work for mixed arrays or for any deeper inspection of object properties.

#### Multiple types

You can also pass in an array of types if you want to verify that the input corresponds to at least one valid type.

```json
{
  "properties": {
    "field": {
      "type": ["string", "boolean", "number"]
    }
  }
}
```

#### Formats

You can use a number of special keywords to specify expectations on the input. These are:

- `alphanumeric`
- `date` (YYYY-MM-DD)
- `email`
- `hexColor`
- `numeric`
- `url`

Usage is as simple as:

```json
{
  "properties": {
    "username": {
      "type": "string",
      "format": "email"
    }
  }
}
```

#### Deeply nested objects

This example shows 3 levels of nesting with objects.

```json
{
  "properties": {
    "things": {
      "type": "object",
      "required": ["nestedThings"],
      "nestedThings": {
        "type": "object",
        "required": ["deeperThings"],
        "deeperThings": {
          "type": "object",
          "required": ["something"],
          "something": "number"
        }
      }
    },
    "required": ["things"]
  },
}
```

#### Minimum length

```json
{
  "properties": {
    "username": {
      "type": "string",
      "minLength": 20
    }
  }
}
```

#### Maximum length

```json
{
  "properties": {
    "username": {
      "type": "string",
      "maxLength": 2
    }
  }
}
```

#### Minimum value

```json
{
  "properties": {
    "phone": {
      "type": "number",
      "minValue": 1000
    }
  }
}
```

#### Maximum value

```json
{
  "properties": {
    "phone": {
      "type": "number",
      "minValue": 1000
    }
  }
}
```

#### Matches regular expression pattern

You can provide your own regular expressions to match for.

```json
{
  "properties": {
    "runtime": {
      "type": "string",
      "matchesPattern": /^(nodejs20|python3.7)$/
    }
  }
}
```

## License

MIT. See `LICENSE` file.

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