# @mikrojs/schema

> Schema DSL for Mikro.js: declare a shape once, infer its type, validate against it, and publish it for a registry to render a form from

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

## Install

```sh
npm install @mikrojs/schema
pnpm add @mikrojs/schema
yarn add @mikrojs/schema
bun add @mikrojs/schema
```

## Health

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

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

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.22.0 |
| Published | 2026-09-30 |
| First published | 2026-08-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=24.0.0 |
| Dependencies | 0 |
| Unpacked size | 139.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 16 |
| Author | Bjørge Næss <bjoerge@gmail.com> |
| Maintainers | bjoerge |
| Keywords | esp32, mikrojs, schema, validation |

## Links

- npm: https://www.npmjs.com/package/@mikrojs/schema
- Repository: https://github.com/mikrojs/mikro
- Homepage: https://github.com/mikrojs/mikro#readme
- Issues: https://github.com/mikrojs/mikro/issues
- npm.io page: https://npm.io/package/@mikrojs/schema

## Alternatives

- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads

## Recent versions

- 0.22.0 (latest) — 2026-09-30
- 0.21.1-next.20260928214050 (next) — 2026-09-28
- 0.21.0-pr-431.20260921210123 (pr-431) — 2026-09-21
- 0.19.0-pr-352.20260829215534 (pr-352) — 2026-08-29
- 0.21.1-next.20260927212749 — 2026-09-27
- 0.21.1-next.20260926222438 — 2026-09-26
- 0.21.0 — 2026-09-21
- 0.21.0-pr-431.20260920213100 — 2026-09-20
- 0.21.0-next.20260913195055 — 2026-09-13
- 0.20.2-next.20260907205905 — 2026-09-07
- 0.20.1 — 2026-09-05
- 0.20.0 — 2026-09-05
- 0.20.0-next.20260904225731 — 2026-09-04
- 0.19.0 — 2026-08-30
- 0.0.0 — 2026-08-29

## README

# @mikrojs/schema

The schema DSL behind [Mikro.js](https://mikrojs.dev): declare a shape once, infer its
TypeScript type, validate values against it, and serialize it as plain JSON for something
else to read. Zero dependencies, no Node APIs, so it runs on Node, Bun, Deno, Cloudflare
Workers and in a browser.

Apps on a device import `mikro/schema` instead, which is this same DSL backed by a native
module plus a `Result`-returning `parse()`. This package is the host half: the CLI evaluating
`mikro.config.ts`, a registry validating what an operator saves, and anything else that needs
to read a published schema.

```js
import {number, object, string, validate} from '@mikrojs/schema'

const Config = object({
  mqttUrl: string({title: 'Broker URL', format: 'url'}),
  interval: number({title: 'Publish interval', unit: 's', default: 60, min: 1, max: 3600}),
})

validate(Config, {mqttUrl: 'mqtt://box.local', interval: 60}, '') // => null
validate(Config, {mqttUrl: 'mqtt://box.local', interval: 0}, '')
// => {ok: false, error: {name: 'ValidationFailed', message: 'below the minimum of 1', path: '.interval'}}
```

`validate()` returns `null` when the value is good, and covers shape plus every numeric and
length bound. `format` is not checked here; see `@mikrojs/schema/config`.

## Annotations

Nodes carry annotations, and they divide in two. **Display** annotations (`title`,
`description`, `mask`) describe how a value should be presented and never change what
validates, so a consumer may ignore any it does not recognise. **Constraints** (`min`, `max`,
`integer`, `minLength`, `maxLength`, `minItems`, `maxItems`, `format`, `unit`) do change what
validates, and a consumer must not ignore one it does not recognise: ignoring a constraint
means accepting a value the author ruled out.

`unit` is a closed enum following [SenML](https://www.rfc-editor.org/rfc/rfc8428) with ASCII
keys. It is a display hint and constrains nothing. Never convert a stored value through a
unit's scale — see the note beside `UNITS`.

## `@mikrojs/schema/config`

The host-side machinery for Mikro.js OTA config, which is what a registry needs:

- `validateConfig(schema, value)` — `validate()` plus `format`, returning `{ok, value}` or
  `{ok: false, error}`
- `parseConfigSchema(value)` — validate a schema that arrived as JSON, rejecting malformed
  annotations and unknown `format` or `unit` values
- `deriveOverlay` / `parseEffective` / `materializeDefaults` — the sparse-overlay model, where
  a registry stores only deviations from the author's defaults and serves the complete document
- `diffConfigSchemas(previous, next)` — what changed between two releases, and whether it needs
  an operator's attention
- `UNITS`, `FORMATS` — the unit table and the format names

`format` lives here rather than in the main entry for two reasons: the expressions are a
denial-of-service surface a device should not carry, and a device has no regular-expression
engine to carry them with.

The wire format is the contract. It is specified in the
[OTA Registry Spec](https://mikrojs.dev/registry-spec) under "The config schema", and that
document, not this package's version number, is what a third-party registry should build
against.

## Documentation

[mikrojs.dev/api/schema](https://mikrojs.dev/api/schema)

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