Definition Schema Reference

Every DiceBear avatar style is a JSON file that follows the DiceBear Definition Schema. This page documents the complete structure of a style definition.

Overview

A style definition describes everything needed to generate an avatar: the canvas size, the SVG elements to render, the components that can be randomized, and the color palettes available. The definition is purely declarative — no code, no functions. The rendering logic lives in the DiceBear Core implementation.

Top-level structure

{
  "$schema": "https://...",
  "$comment": "Optional comment",
  "meta": { ... },
  "canvas": { ... },
  "components": { ... },
  "colors": { ... },
  "attributes": { ... }
}

Property	Required	Description
$schema	No	URL to the definition schema for validation
$comment	No	Free-text comment (e.g. "Generated by Figma")
meta	No	License, creator, and source metadata
canvas	Yes	Canvas dimensions and root element tree
components	No	Named, randomizable SVG components
colors	No	Named color palettes for dynamic coloring
attributes	No	Global SVG attributes for the root element

meta

Metadata about the style — used in license comments, the CLI banner, and the documentation.

{
  "meta": {
    "license": {
      "name": "CC0 1.0",
      "url": "https://creativecommons.org/publicdomain/zero/1.0/",
      "text": "Full license text..."
    },
    "creator": {
      "name": "DiceBear",
      "url": "https://www.dicebear.com"
    },
    "source": {
      "name": "Initials",
      "url": "https://github.com/dicebear/dicebear"
    }
  }
}

canvas

Defines the SVG viewport and the root element tree. The width and height determine the viewBox of the generated SVG.

{
  "canvas": {
    "width": 100,
    "height": 100,
    "elements": [
      { "type": "component", "value": "background" },
      { "type": "component", "value": "face" }
    ]
  }
}

Property	Type	Required	Description
width	number	Yes	Canvas width in pixels (>= 1)
height	number	Yes	Canvas height in pixels (>= 1)
elements	array	Yes	Root element tree

Elements

Elements are the building blocks of the SVG. Three types are supported:

element — SVG tag

Renders an SVG element like <circle>, <path>, <g>, etc.

{
  "type": "element",
  "name": "circle",
  "attributes": {
    "cx": "50",
    "cy": "50",
    "r": "40",
    "fill": { "type": "color", "value": "skin" }
  },
  "children": []
}

Only whitelisted SVG elements are allowed (e.g. circle, path, g, rect, text, defs, filter, linearGradient, radialGradient, etc.). Elements like script, foreignObject, and event handlers are blocked for security.

text — Text content

Renders raw text inside an SVG element. Supports variable references.

{
  "type": "text",
  "value": "Hello"
}

Or with a variable:

{
  "type": "text",
  "value": { "type": "variable", "value": "initials" }
}

component — Component reference

References a named component defined in the components section. The DiceBear Core will select a variant based on the seed and options.

{
  "type": "component",
  "value": "eyes"
}

components

Named, randomizable parts of the avatar. Each component defines a set of variants that the PRNG can choose from.

{
  "components": {
    "eyes": {
      "width": 80,
      "height": 40,
      "probability": 100,
      "rotate": [-10, 10],
      "translate": {
        "x": [0, 0],
        "y": [-5, 5]
      },
      "variants": {
        "happy": {
          "weight": 1,
          "elements": [...]
        },
        "surprised": {
          "weight": 1,
          "elements": [...]
        }
      }
    }
  }
}

Property	Type	Default	Description
width	number	—	Component canvas width (required)
height	number	—	Component canvas height (required)
probability	number	100	Chance the component appears (0-100)
rotate	array	—	[min, max] rotation range in degrees
translate	object	—	{ x: [min, max], y: [min, max] } offsets
variants	object	—	Named variant definitions (required)

Variants

Each variant contains an element tree and an optional weight:

Property	Type	Default	Description
elements	array	—	SVG element tree for this variant (required)
weight	number	1	Selection weight for the PRNG

Higher weights make a variant more likely to be selected. A weight of 0 means the variant is only chosen when all others are also 0.

colors

Named color palettes. The PRNG picks a color from the palette based on the seed.

{
  "colors": {
    "skin": {
      "values": ["#f5d6c3", "#d4a889", "#a67c5b", "#614335"]
    },
    "text": {
      "values": ["#ffffff", "#000000"],
      "contrastTo": "skin"
    },
    "hair": {
      "values": ["#2c1b18", "#b58143", "#d6b370", "#724133"],
      "notEqualTo": ["skin"]
    }
  }
}

Property	Type	Description
values	string[]	Array of hex colors (#RGB, #RRGGBB, #RRGGBBAA)
contrastTo	string	Pick the color with highest contrast to this color
notEqualTo	string[]	Filter out colors already used by these color groups

Color constraints

contrastTo bypasses random selection. Instead, the candidate colors are sorted by WCAG 2.1 contrast ratio against the referenced color, and the highest-contrast color is picked. This is useful for ensuring text readability.

notEqualTo filters out colors that were already selected for the referenced color groups. This prevents adjacent parts from having the same color.

Color references in attributes

Attributes can reference color groups instead of hardcoding colors:

{
  "fill": { "type": "color", "value": "skin" }
}

This is resolved at render time to the color selected by the PRNG for the skin color group.

Variable references

Text content and certain attributes support variable references:

Variable	Description
initial	First character of the initials derived from the seed
initials	Full initials (1-2 characters) derived from the seed
fontFamily	Font family from options (default: system-ui)
fontWeight	Font weight from options (default: 400)

{
  "type": "text",
  "value": { "type": "variable", "value": "initials" }
}

attributes

Global SVG presentation attributes applied to the root <svg> element.

{
  "attributes": {
    "fill": "none",
    "shape-rendering": "auto"
  }
}

Only safe SVG presentation attributes are allowed. See the schema source for the complete whitelist.

Example: Minimal style definition

A complete but minimal definition that renders a colored circle:

{
  "$schema": "https://cdn.hopjs.net/npm/@dicebear/schema@0.9.0/dist/definition.min.json",
  "canvas": {
    "width": 100,
    "height": 100,
    "elements": [
      {
        "type": "element",
        "name": "circle",
        "attributes": {
          "cx": "50",
          "cy": "50",
          "r": "45",
          "fill": { "type": "color", "value": "background" }
        }
      },
      {
        "type": "component",
        "value": "face"
      }
    ]
  },
  "components": {
    "face": {
      "width": 100,
      "height": 100,
      "variants": {
        "smile": {
          "elements": [
            {
              "type": "element",
              "name": "path",
              "attributes": {
                "d": "M 30 60 Q 50 80 70 60",
                "stroke": "#000000",
                "stroke-width": "3",
                "fill": "none"
              }
            }
          ]
        },
        "neutral": {
          "elements": [
            {
              "type": "element",
              "name": "line",
              "attributes": {
                "x1": "35",
                "y1": "65",
                "x2": "65",
                "y2": "65",
                "stroke": "#000000",
                "stroke-width": "3"
              }
            }
          ]
        }
      }
    }
  },
  "colors": {
    "background": {
      "values": ["#f9c74f", "#90be6d", "#43aa8b", "#577590", "#f94144"]
    }
  }
}

Validation

Validate definitions against the schema using the @dicebear/schema npm package or any JSON Schema Draft 2020-12 validator:

npm install @dicebear/schema

The schema files are:

• definition.json — validates style definitions
• options.json — validates user options passed to Avatar

Schema package

Package	npm	Composer
Schema	@dicebear/schema	dicebear/schema
Definitions	@dicebear/definitions	dicebear/definitions