@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	Mirror direction: 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	SVG ID randomization to avoid conflicts
fontFamily	string | array	Font family for text rendering
fontWeight	integer | array	Font weight (1 to 1000)
*Probability	number	Component display probability (0 to 100)
*Variant	string | string[] | object	Component variant filter and weights
*Color	string | array	Hex colors
*ColorFill	string | array	Color fill: solid, linear, or radial
*ColorFillStops	integer | [min, max]	Gradient color stops (min 1)
*ColorAngle	number | [min, max]	Gradient angle (−360 to 360)
*Rotate	number | [min, max]	Component rotation in degrees (−360 to 360)
*TranslateX	number | [min, max]	Component horizontal offset (−100 to 100)
*TranslateY	number | [min, max]	Component vertical offset (−100 to 100)

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/schema@0.8.0/dist/definition.min.json
https://cdn.hopjs.net/npm/@dicebear/schema@0.8.0/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.