# Definition schema reference Every DiceBear avatar style is a JSON file that follows the [DiceBear Definition Schema](https://github.com/dicebear/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 ```json { "$schema": "https://...", "$id": "https://...", "$comment": "Optional comment", "meta": { ... }, "canvas": { ... }, "components": { ... }, "colors": { ... }, "attributes": { ... } } ``` | Property | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------------- | | `$schema` | No | URL to the definition schema for editor validation | | `$id` | No | Canonical identifier for this definition (typically the URL it is hosted at, max 256 chars) | | `$comment` | No | Free-text comment, e.g. "Generated by Figma" (max 4096 chars) | | `meta` | No | License, creator, and source metadata | | `canvas` | **Yes** | Canvas dimensions and root element tree | | `components` | No | Named, randomizable SVG components (up to 512 entries) | | `colors` | No | Named color palettes for dynamic coloring (up to 512 entries) | | `attributes` | No | Global SVG attributes for the root `` element | ## `meta` Metadata about the style, used in license comments, the CLI banner, and the documentation. ```json { "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. ```json { "canvas": { "width": 100, "height": 100, "elements": [ { "type": "component", "name": "background" }, { "type": "component", "name": "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 (up to 1024 top-level entries) | ## Elements Elements are the building blocks of the SVG. Three types are supported: ### `element`: SVG tag Renders an SVG element like ``, ``, ``, etc. ```json { "type": "element", "name": "circle", "attributes": { "cx": "50", "cy": "50", "r": "40", "fill": { "type": "color", "name": "skin" } }, "children": [] } ``` Only [whitelisted SVG elements](https://github.com/dicebear/schema/blob/main/src/definition.json) are allowed (e.g. `circle`, `path`, `g`, `rect`, `text`, `defs`, `filter`, `linearGradient`, `radialGradient`, etc.). Elements like `script`, `foreignObject`, and `a` are blocked for security. A node may have at most 1024 children. The element with `name: "defs"` has special semantics (see [Reusable `` entries](#reusable-defs-entries) below). ### `text`: text content Renders raw text inside an SVG element. Supports variable references. ```json { "type": "text", "value": "Hello" } ``` Or with a variable: ```json { "type": "text", "value": { "type": "variable", "name": "initials" } } ``` Only `initial` and `initials` are accepted in a text `value`. Other variables (`fontFamily`, `fontWeight`) are only valid in their dedicated attributes (see [Variable references](#variable-references)). ### `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. ```json { "type": "component", "name": "eyes" } ``` A component reference can carry its own `attributes` map. They are written verbatim onto the emitted `` element, which is how you place an instance of a component on the canvas: ```json { "type": "component", "name": "eyes", "attributes": { "transform": "translate(10 20)" } } ``` A user-supplied `transform` is prepended to the per-component rotate/translate/scale picked by the renderer, so it acts as the outer (placement) transform. ### The `