FAQ

What is UEC?

UEC is a universal JSON format for characters and personas. It’s designed to be portable across apps and stable over time.

Why not just use JSON without a wrapper?

The wrapper (schema, kind) enables versioning and unambiguous type detection, which makes long‑term compatibility safer.

Is UEC only for AI apps?

No. It’s meant for any tool that needs portable character or persona data: roleplay tools, assistants, games, and more.

Can I store app‑specific settings?

Yes. Use app_specific_settings for non‑canonical UI or UX preferences.

Can I add my own fields?

Yes. Put vendor‑specific data under extensions and use a namespace key.

Are all fields required?

Only a few are required by default (id, name/title). Strict validation requires additional fields (like description, scenes, createdAt, etc.).

How do I reference prompt templates?

Use systemPrompt with _ID:<id> to reference a template. Plain text means it’s a full prompt.

Can I use local file paths for images?

No. The current spec expects avatar and chatBackground to be https URLs or base64 data URIs.

Is there an official schema file?

Not yet (unless you add one). The JS/Python/Rust validators are the current reference.

Can I downgrade or upgrade versions?

Yes. Use schema.version and schema.compat to decide whether to accept or reject a file.

What time unit should createdAt/updatedAt use?

Use unix seconds (recommended) or clearly document if your app uses milliseconds.

Can I store multiple characters in one file?

No. One UEC file contains a single entity. Bundle multiple files outside the spec.

Should I store conversation history in UEC?

No. UEC is for static definitions. Chat history should live elsewhere.

Should I include both a template ID and full prompt?

Prefer one. If you must keep both, store the extra copy in extensions.

Can I use local file paths?

No. Use https URLs or base64 data URIs so the card stays portable.