PHPackages                             dicebear/schema - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. dicebear/schema

ActiveLibrary[Utility & Helpers](/categories/utility)

dicebear/schema
===============

JSON Schema definitions for DiceBear avatar styles and options

v0.9.0(1mo ago)0531MITJavaScriptCI failing

Since Feb 26Pushed 1mo agoCompare

[ Source](https://github.com/dicebear/schema)[ Packagist](https://packagist.org/packages/dicebear/schema)[ Docs](https://github.com/dicebear/schema)[ RSS](/packages/dicebear-schema/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (16)Used By (1)

@dicebear/schema
================

[](#dicebearschema)

JSON Schema definitions for [DiceBear](https://dicebear.com) avatar styles and options.

Schemas
-------

[](#schemas)

This package exports two JSON Schemas (Draft 2020-12):

### `definition.json`

[](#definitionjson)

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.
- **`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 `` 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.

### `options.json`

[](#optionsjson)

Validates the options object passed by users when generating an avatar. Supported properties include:

PropertyTypeDescription`seed``string`PRNG seed for reproducible avatars`size``integer`Output size in pixels`flip``string | array`Mirror direction: `none`, `horizontal`, `vertical`, or `both``scale``number | [min, max]`Scaling factor (1 = original size)`rotate``number | [min, max]`Rotation in degrees (−360 to 360)`translateX``number | [min, max]`Horizontal offset (−100 to 100)`translateY``number | [min, max]`Vertical offset (−100 to 100)`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 1)`*ColorAngle``number | [min, max]`Gradient angle (−360 to 360)`*Rotate``number | [min, max]`Component rotation in degrees (−360 to 360)`*TranslateX``number | [min, max]`Component horizontal offset (−100 to 100)`*TranslateY``number | [min, max]`Component vertical offset (−100 to 100)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).

Installation
------------

[](#installation)

**npm**

```
npm install @dicebear/schema
```

**Composer**

```
composer require dicebear/schema
```

**CDN**

The schemas are available directly via CDN — no installation required. We recommend using a specific version to ensure stability:

```
https://cdn.hopjs.net/npm/@dicebear/schema@0.9.0/dist/definition.min.json
https://cdn.hopjs.net/npm/@dicebear/schema@0.9.0/dist/options.min.json

```

Usage
-----

[](#usage)

**JavaScript**

```
import definitionSchema from '@dicebear/schema/definition.json' assert { type: 'json' };
import optionsSchema from '@dicebear/schema/options.json' assert { type: 'json' };
```

**PHP**

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

Development
-----------

[](#development)

```
# Install dependencies
npm install

# Run tests
npm test

# Format code
npm run format
```

Publishing
----------

[](#publishing)

**npm**

Releases are published to npm automatically via GitHub Actions when a version tag is pushed.

```
npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

git push origin main --follow-tags
```

`npm version` updates `package.json`, creates a commit, and creates the Git tag in one step. The [publish workflow](.github/workflows/publish.yml) will then install dependencies, run the tests, and publish the package to npm with provenance.

**Packagist**

Once the repository is linked on [packagist.org](https://packagist.org), new releases are picked up automatically from the same Git tags — no separate step needed.

Sponsors
--------

[](#sponsors)

Advertisement: Many thanks to our sponsors who provide us with free or discounted products.

[    ![bunny.net](https://camo.githubusercontent.com/4ae34db3dad914c12edc4dc985f9c62d3d4cde77d4d6de3471bd9211c42ac5c2/68747470733a2f2f7777772e64696365626561722e636f6d2f73706f6e736f72732f62756e6e792d6461726b2e737667) ](https://bunny.net/)

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance90

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 80.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

15

Last Release

47d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d0f19a1a330129371d1655dc823c112265472923f15f8d56ea84777d71c21fcc?d=identicon)[FlorianKoerner](/maintainers/FlorianKoerner)

---

Top Contributors

[![FlorianKoerner](https://avatars.githubusercontent.com/u/647303?v=4)](https://github.com/FlorianKoerner "FlorianKoerner (42 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (10 commits)")

---

Tags

schemajson-schemaavatarDiceBear

### Embed Badge

![Health badge](/badges/dicebear-schema/health.svg)

```
[![Health](https://phpackages.com/badges/dicebear-schema/health.svg)](https://phpackages.com/packages/dicebear-schema)
```

###  Alternatives

[league/config

Define configuration arrays with strict schemas and access values with dot notation

564302.2M24](/packages/league-config)[laravolt/avatar

Turn name, email, and any other string into initial-based avatar or gravatar.

2.0k5.4M31](/packages/laravolt-avatar)[torann/json-ld

Extremely simple JSON-LD markup generator.

149620.7k1](/packages/torann-json-ld)[yohang88/letter-avatar

Generate user avatar using name initials letter.

126529.5k2](/packages/yohang88-letter-avatar)[brick/schema

Schema.org library for PHP

5163.7k1](/packages/brick-schema)[ptrofimov/matchmaker

Ultra-fresh PHP matching functions

27167.7k](/packages/ptrofimov-matchmaker)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)