schema

README

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

Documentation

Overview

Package schema embeds the DiceBear JSON Schema definitions.

It is a pure-data package, mirroring the npm (@dicebear/schema), Composer (dicebear/schema), PyPI (dicebear-schema), crates.io (dicebear-schema) and pub.dev (dicebear_schema) packages: the same source schemas under src/, with no logic. Consumers parse and validate (e.g. with github.com/santhosh-tekuri/jsonschema); this package only ships the bytes.

Unlike the npm build, which serves the minified dist/, Go embeds and parses the unminified src/ JSON, matching the Python, PHP, Rust and Dart packages.

Index

• Variables
• func All() []string
• func Get(name string) (string, bool)

Variables

var Definition string

Definition is the JSON Schema for DiceBear style definition files.

var Options string

Options is the JSON Schema for DiceBear avatar options.

Functions

func All

func All() []string

All returns the names of every embedded schema ("definition", "options").

func Get

func Get(name string) (string, bool)

Get returns the raw JSON for the named schema ("definition" or "options"), or ("", false) if the name is unknown.

Companion to All: All lists the names, Get fetches one.