Soul Spec v0.5.3 — Persona Avatar
v0.5.3 is a minor, additive extension of v0.5. It changes nothing in the
v0.5 spec — it fully documents the persona avatar. Every valid v0.5 soul is already a
valid v0.5.3 soul, and specVersion may remain "0.5".
files.avatar has existed since v0.5 as a bundled path; v0.5.3 formalizes its full
semantics so clients render personas consistently.
Persona Avatar
files.avatar gives a persona a visual "face" for marketplaces, playgrounds, and chat
clients. It is optional and additive — consumers that ignore it are unaffected.
Value
Either a package-relative path or an absolute URL:
{ "files": { "avatar": "avatar/avatar.png" } } // bundled path — PREFERRED
{ "files": { "avatar": "https://example.com/face.png" } } // absolute https URL
- Bundled path (preferred): keeps the soul package self-contained and portable — the
image travels with the package, with no external dependency or link rot. The path MUST
resolve inside the package; consumers MUST reject traversal (
../) and absolute filesystem paths. https://URL (allowed): for externally hosted images; carries availability / link-rot risk that the bundled path avoids.
Resolution order
At render time: bundled path (in package) → URL → generated identicon.
Default when absent
Consumers SHOULD render a deterministic identicon derived from author.name/name
(GitHub/GitLab style), so no persona ever shows an empty face. An avatar is never
required of the author.
Constraints
| Aspect | Rule |
|---|---|
| Formats | png, webp, jpg (webp preferred for size). svg allowed only if sanitized (strip scripts / foreignObject). No animated formats in this version. |
| Dimensions | ≤ 512×512 recommended, hard cap 1024×1024. Square (1:1); rendered rounded. |
| File size | ≤ ~256 KB, so packages stay light. |
| Accessibility | files.avatarAlt (optional) provides alt text; default is displayName. |
New optional field
| Field | Type | Default | Description |
|---|---|---|---|
files.avatarAlt | string | displayName | Accessibility alt text for the avatar |
Validation
A validator SHOULD accept avatar and MAY warn on a bad format, oversize image,
unreachable URL, or path escape. It MUST NOT hard-fail a soul for lacking an avatar.
Backward compatibility
Fully backward compatible with v0.5 (and forward-compatible with v0.6, which retains this
field). The extension only adds files.avatarAlt and documents existing behavior; no v0.5
soul needs to change.