README

JSON Schema definitions for DiceBear avatar styles and options.

Schemas

This package exports two JSON Schemas (Draft 07):

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:

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

$basePath = \Composer\InstalledVersions::getInstallPath('dicebear/schema');

$definition = json_decode(file_get_contents($basePath . '/src/definition.json'), true);
$options    = json_decode(file_get_contents($basePath . '/src/options.json'), true);

Contributing

See CONTRIBUTING.md for local development, testing, and the release process.

Sponsors

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