@dicebear/schema

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. Components can also be declared as aliases of another component via extends, producing an independently-randomized instance.
• 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.

Additional documentation

https://www.dicebear.com/specification/definition-schema/

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 (1 to 4096) | | title | string | Accessible title rendered as <title> and aria-label | | flip | string \| array | Mirror direction: none, horizontal, vertical, or both | | scale | number \| [min, max] | Scaling factor (0 to 10, 1 = original size) | | rotate | number \| [min, max] | Rotation in degrees (−360 to 360) | | translateX | number \| [min, max] | Horizontal offset (−1000 to 1000) | | translateY | number \| [min, max] | Vertical offset (−1000 to 1000) | | 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 2) | | *ColorAngle | number \| [min, max] | Gradient angle (−360 to 360) |

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).

Usage

JavaScript

npm install @dicebear/schema

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

PHP

composer require dicebear/schema

$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);

Python

pip install dicebear-schema

import json
from importlib.resources import files

definition = json.loads(files("dicebear_schema").joinpath("definition.json").read_text("utf-8"))
options    = json.loads(files("dicebear_schema").joinpath("options.json").read_text("utf-8"))

Rust

cargo add dicebear-schema

The schemas are embedded at compile time and exposed as raw JSON (&'static str). Parse them with serde_json and validate with the jsonschema crate:

use dicebear_schema::{DEFINITION, OPTIONS};

let definition: serde_json::Value = serde_json::from_str(DEFINITION)?;
let options: serde_json::Value = serde_json::from_str(OPTIONS)?;

// Or look one up by name (None if unknown); all() lists the names:
let schema = dicebear_schema::get("definition");
let all = dicebear_schema::all();

Go

go get github.com/dicebear/schema

The schemas are embedded at compile time and exposed as raw JSON (string). Parse them with encoding/json and validate with a library such as jsonschema:

import (
	"encoding/json"

	"github.com/dicebear/schema"
)

var definition map[string]any
_ = json.Unmarshal([]byte(schema.Definition), &definition)

var options map[string]any
_ = json.Unmarshal([]byte(schema.Options), &options)

// Or look one up by name (ok is false if unknown); All() lists the names:
raw, ok := schema.Get("definition")
all := schema.All()

Dart

dart pub add dicebear_schema

The schemas are embedded as Dart string constants. Parse them with dart:convert and validate with a package such as json_schema:

import 'dart:convert';

import 'package:dicebear_schema/dicebear_schema.dart' as schema;

final definitionSchema = jsonDecode(schema.definition);
final optionsSchema = jsonDecode(schema.options);

// Or look one up by name (null if unknown); `all` lists the names:
final raw = schema.get('definition');
final names = schema.all;

CDN

The schemas are available directly via CDN, so no installation is 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

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.