@dicebear/schema

JSON Schema definitions for DiceBear avatar styles and options.

Schemas

This package exports two JSON Schemas (Draft 2020-12):

definition.json

Validates avatar style definitions — the files that describe how a DiceBear avatar style is structured. A definition includes:

• canvas (required) — The SVG canvas dimensions and root element tree
• components — Named, reusable SVG components with variants. At render time, a PRNG selects one variant per component.
• colors — Named color palettes. Colors can define constraints such as notEqualTo (must differ from another color) or contrastTo (picks the highest-contrast value).
• attributes — Global SVG attributes applied to the root <svg> element
• meta — License, creator, and source metadata

Only a safe subset of SVG elements and attributes is permitted. Event handlers, external URL references, and CSS injection patterns are explicitly blocked.

options.json

Validates the options object passed by users when generating an avatar. Supported properties include:

| Property | Type | Description | |---|---|---| | seed | string | PRNG seed for reproducible avatars | | size | integer | Output size in pixels | | flip | string \| array | none, horizontal, vertical, or both | | scale | number \| [min, max] | Scaling factor (1 = original size) | | rotate | number \| [min, max] | Rotation in degrees (−360 to 360) | | translateX | number \| [min, max] | Horizontal offset (−100 to 100) | | translateY | number \| [min, max] | Vertical offset (−100 to 100) | | borderRadius | number \| [min, max] | Corner radius (0 = sharp, 50 = circle) | | idRandomization | boolean | Randomize SVG IDs to avoid conflicts | | fontFamily | string \| array | Font family for text rendering | | fontWeight | integer \| array | Font weight (1–1000) | | *Probability | number | Display probability for a component (0–100) | | *Variant | string \| array | Selectable variants for a component | | *Color | string \| array | Selectable hex colors for a component |

When an option accepts an array, the PRNG either picks from the list (for discrete values) or picks a value within the range (for numeric min/max pairs).

Installation

npm

npm install @dicebear/schema

Composer

composer require dicebear/schema

CDN

The schemas are available directly via CDN — no installation required. We recommend using a specific version to ensure stability:

https://cdn.hopjs.net/npm/@dicebear/[email protected]/dist/definition.min.json
https://cdn.hopjs.net/npm/@dicebear/[email protected]/dist/options.min.json

Usage

JavaScript

import definitionSchema from '@dicebear/schema/definition.json' assert { type: 'json' };
import optionsSchema from '@dicebear/schema/options.json' assert { type: 'json' };

PHP

$definition = json_decode(file_get_contents(__DIR__ . '/vendor/dicebear/schema/src/definition.json'), true);
$options    = json_decode(file_get_contents(__DIR__ . '/vendor/dicebear/schema/src/options.json'), true);

Development

# Install dependencies
npm install

# Run tests
npm test

# Format code
npm run format

Publishing

npm

Releases are published to npm automatically via GitHub Actions when a version tag is pushed.

npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

git push origin main --follow-tags

npm version updates package.json, creates a commit, and creates the Git tag in one step. The publish workflow will then install dependencies, run the tests, and publish the package to npm with provenance.

Packagist

Once the repository is linked on packagist.org, new releases are picked up automatically from the same Git tags — no separate step needed.

Sponsors

Advertisement: Many thanks to our sponsors who provide us with free or discounted products.