dicebear_schema 2.0.2

JSON Schema definitions for DiceBear avatar styles and options, embedded as Dart string constants.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

This repository holds the JSON Schema that defines the DiceBear avatar style definition format (distributed via npm, Composer, PyPI, crates.io, Go modules, and pub.dev). Versions track the schema itself, independently of the DiceBear library release line.

Unreleased

2.0.2 - 2026-09-03

Changed

• definition.json: animations are rejected below defs and clipPath, and on elements a group cannot wrap: stop, tspan, textPath, mpath and the filter primitives. The renderer plays an animation by wrapping the element in a group, which never reaches a <use> instance of a def, is no valid clipPath content, and breaks a gradient or a filter chain. Such an animation could not play, so a definition carrying one is invalid now.

• Release script: scripts/version.sh refuses to tag while the Go module path and the version disagree, so a major bump cannot ship a tag the Go module proxy rejects.

2.0.1 - 2026-09-03

Changed

• Go: The module path is github.com/dicebear/schema/v2, as Go requires for a major version above 1. Import it with go get github.com/dicebear/schema/v2. The 2.0.0 tag is not fetchable as a Go module because it still carried the old path.

2.0.0 - 2026-09-03

Changed

• options.json: The *ColorOrder description follows the DiceBear 11 behaviour: with fixed, the style's palette keeps its definition order like user colors do, and the contrast sort is skipped.

• options.json: animation is a boolean. The name and list forms are gone, an animation is switched by name through its own *Animation option instead. This is a breaking change for anyone who passed names to animation.

• options.json: rotate, translateX, and translateY sit under properties instead of being exact-match patterns, and the file is ordered by topic. Validation is unchanged.

Added

• options.json: *Animation options, such as blinkAnimation, switch one animation on or off by name and win over animation for it.
• options.json: *AnimationSpeed options, such as blinkAnimationSpeed, set the playback speed of one animation by name, as a factor or a [min, max] range. They win over animationSpeed for that animation.
• options.json: animationDelay and *AnimationDelay add a start offset in seconds, as a value or a [min, max] range the PRNG picks from, so avatars rendered next to each other do not move in step. The named form wins over the global one for that animation.

1.6.1 - 2026-08-30

1.6.0 - 2026-08-30

Added

• Declarative animations: Generic elements and component references accept an animations array. Each entry is one timeline with a duration in seconds, optional delay (negative values shift the phase), iterations, direction, fill, a default easing, a transform origin, an optional camelCase name, and per property keyframe tracks for translateX, translateY, rotate, scaleX, scaleY, and opacity. Keyframes place their at position as a percentage of the duration, and easings are either a named CSS keyword or a cubic bezier. Renderers translate the data to CSS when the new animation render option is enabled. The previous approach, raw CSS in a <style> element, stays valid.
• animation render option: Enables a style's declarative animations. true plays all of them, while a timeline name or a list of names plays only the timelines carrying those names. Defaults to false, so SVG output and raster conversions stay static and deterministic.
• animationSpeed render option: A playback speed multiplier between 0.1 and 10, as a single value or a [min, max] range the PRNG picks from. Durations and delays are divided by the resolved value.

1.5.1 - 2026-08-22

Changed

• Injection filter: The separator between a blocked token and what follows is now written out as [ \t\n\f\r] instead of \s. Regex engines disagree on what \s covers, so the same definition was valid in one language and invalid in another. The new class holds the characters a URL or CSS parser actually discards, which loosens the filter in one place and tightens it in another. Loosened: a non-breaking space between javascript and its colon is valid now, and such a string is inert because a URL scheme cannot hold one. Tightened: url( followed by a non-breaking space and a fragment is rejected now, because the space reads as the start of the URL instead of a separator.

1.5.0 - 2026-08-22

1.5.0-rc.2 - 2026-08-22

1.5.0-rc.1 - 2026-08-22

Added

• C#: The schemas are now available as a DiceBear.Schema package on NuGet, targeting netstandard2.0. MSBuild embeds definition.json and options.json into the assembly as resources. The shim in schema.cs exposes them as the string properties Definition and Options, plus Get(name) and All(), the same API the other shims carry.

Changed

• *ColorOrder render option: The description no longer claims that fixed without a *Color option makes the result seed-independent. It only skips the shuffle; constraints from the style definition, such as a contrast sort against another color group, still resolve with the seed. The schema shape itself is unchanged.

1.4.0 - 2026-08-09

Added

• *ColorOrder render option: New per-color option with the values random and fixed. random matches the previous behavior: the PRNG shuffles the colors before use. fixed keeps the colors of the *Color option in exactly the specified order; gradient fills apply them as color stops from first to last, and solid fills always use the first color. With fixed and no *ColorFillStops value, the number of gradient stops defaults to the number of specified colors instead of 2. Without a *Color option, fixed only makes the result seed-independent: the style's default palette is used in a deterministic sorted order.

Changed

• tags render option: The option description now documents that a bare category include requires the category — it drops variants that carry no tag there, but only in components where the category is in use. A bare include used to be a no-op. The schema shape itself is unchanged.

1.3.0 - 2026-06-19

1.3.0-rc.1 - 2026-06-18

Added

• Variant tags: Component variants may now carry an optional tags array, such as hairLength:long or facialHair:beard. Each tag is a category or category:value token in camelCase.
• tags render option: The options schema now defines a tags option that filters which variants the PRNG may select. A token is category or category:value, optionally prefixed with ! to exclude. An include narrows its own category, an exclude removes the matching variants, and a *Variant option for the same component adds its named variants to that pool. Accepts a single string or an array.

1.2.0 - 2026-06-08

Added

• Dart: The schemas are now available as a dicebear_schema package on pub.dev. The Dart shim landed after the v1.2.0 tag, so the pub.dev release of this version came from a later commit. Dart has no compile-time file embedding, so scripts/build.sh generates lib/dicebear_schema.dart with definition.json and options.json embedded as string constants (definition, options), plus get(name) and all; the Dart, Rust and Go shims share one API. The generated lib/ is git-ignored (like the npm dist/) and built fresh by the test and publish workflows; tool/check_parity.dart proves in CI that the embedded constants are byte-identical to their src/*.json sources.
• Go: The schemas are now available as a Go module (github.com/dicebear/schema). definition.json and options.json are embedded and exposed as string variables (Definition, Options) and via Get(name)/All().
• Rust: Added get(name) and all() helpers, so the Rust and Go shims share one API (DEFINITION/OPTIONS constant or variable + get(name) + all()), matching the dicebear-styles/@dicebear/styles shims.

1.1.0 - 2026-06-03

Added

• Rust distribution: A dicebear-schema crate is now published to crates.io, alongside the existing npm, Composer, and PyPI distributions. It embeds the same JSON Schemas via include_str! and exposes them as &'static str constants (DEFINITION, OPTIONS).

Fixed

• Canvas and component dimensions (canvas.width/height and the component base width/height) now have an upper bound of 1000000 in addition to the existing minimum: 1. Without it, extreme values could diverge across the language ports' number-to-string formatting. The bound never rejects a real avatar (official styles use ~100) and matches the precedent already set on the weight field.

1.1.0-rc.2 - 2026-05-31

Changed

• Prerelease versions are now published to npm under the next dist-tag, so npm install @dicebear/schema continues to resolve the latest stable release.

1.1.0-rc.1 - 2026-05-31

Added

• Python distribution: A dicebear-schema package is now published to PyPI, alongside the existing npm and Composer distributions, exposing the same JSON Schema to Python consumers.

1.0.0 - 2026-05-17

First stable release of the DiceBear style definition schema.

Added

• A versioned JSON Schema (draft-07) describing avatar style definitions and their options, with a build step that injects the matching $id and publishes minified output.
• Color fills: colorFill (solid, linear, and radial), colorFillStops, and colorRotate for gradient configuration.
• Weighted variants: per-variant weight to control how frequently each component variant is selected.
• Component aliases via extends, and a component-level scale option.
• Distribution via npm and Composer (Packagist), plus a CDN with automatic versioning.