Skip to content

Home

Jump to bottom
Megalith edited this page Jan 9, 2026 · 1 revision

Welcome! This wiki documents the Unified Entity Card (UEC) format, a portable file that represents either a Character or a Persona in a consistent, shareable way.

Mission

UEC exists to make character and persona cards easy to share anywhere without losing detail. We want creators to move their characters across apps, keep long‑term compatibility, and develop a global standard together.

What is UEC?

UEC is a single JSON file that can represent:

  • a Character (full behavior, scenes, voice, etc.)
  • a Persona (a smaller identity profile)

Tools that only understand one type can still parse the file safely. Tools that support both can round‑trip without special handling.

File structure (top‑level)

{
  "schema": { "name": "UEC", "version": "1.0" },
  "kind": "character",
  "payload": {},
  "app_specific_settings": {},
  "meta": {},
  "extensions": {}
}

schema: global identity + versioning

  • name: fixed identifier (currently "UEC")
  • version: schema version string
  • compat (optional): minimum compatible version

kind: discriminated union

  • "character" → payload matches CharacterSchema
  • "persona" → payload matches PersonaSchema

payload: canonical data

Character payload typically includes:

  • identity & description
  • definitions (LLM‑facing explanation)
  • tags (search / grouping)
  • avatar (base64 data URI or https URL)
  • chatBackground (base64 data URI or https URL)
  • systemPrompt (prompt text, or _ID:<id> to reference a template)
  • rules, scenes, voice configuration

Persona payload typically includes:

  • title, description, avatar, and default flag

app_specific_settings

Opaque object reserved for UI/app defaults. Safe to ignore. Validation only checks it’s an object if present.

meta

Provenance + lifecycle fields (created/updated timestamps, source, authors, license).

extensions

Open object for vendor‑specific fields. Namespace keys (e.g. "com.vendor.product").

Scenes & variants

Scenes can include variants. A variant uses this structure:

{
  "id": "uuid",
  "content": "text",
  "createdAt": 1715100001
}

Additional fields are allowed, but id, content, and createdAt are required when validating.

Examples

Character example: examples/character.uec
Persona example: examples/persona.uec

System prompts & template IDs

systemPrompt accepts either:

  • plain prompt text, or
  • _ID:<id> to reference a prompt template

Library helpers support this with a flag:

  • JS: { systemPromptIsId: true }
  • Python: system_prompt_is_id=True
  • Rust: create_character_uec(..., system_prompt_is_id, ...)

Libraries

JavaScript / TypeScript

npm: https://www.npmjs.com/package/unified-entity-card

import { createCharacterUEC, validateUEC } from "unified-entity-card";

Python

PyPI: https://pypi.org/project/unified-entity-card/0.1.1/

from uec import create_character_uec, validate_uec

Rust

crates.io: https://crates.io/crates/unified-entity-card

use unified_entity_card::{assert_uec, validate_uec};

FAQ

Q: Why not just use JSON without a wrapper?
A: The schema and kind fields allow safe versioning and explicit type discrimination.

Q: Can I add custom fields?
A: Yes — use extensions with a namespace key.

Q: Are UI settings portable?
A: No. app_specific_settings is explicitly non‑canonical.

Clone this wiki locally