Character Card V2 vs V3: what changed and how to migrate.Character Card V2 vs V3:
what changed and how to migrate.

If you’ve ever exported a character card from one client, imported it into another, and watched half the fields vanish — greetings cropped, lorebook gone, custom prompts silently dropped — you’ve already met the V1 / V2 / V3 problem. The Tavern card format is community heritage. There is no single committee, no versioned schema registry, and no host that implements every key the same way.

For most creators that wouldn’t matter — until you start maintaining a library that needs to live on Chub.ai, inside RisuAI, and on a friend’s self-hosted SillyTavern at the same time. Send the wrong version and you lose work that took hours to write. This guide walks through what each version adds, where it’s safe to lean on V3, and how to migrate without breaking anything.

V1 cards were the original Tavern format: a single JSON payload embedded into a PNG via a tEXt chunk named chara, with the JSON itself Base64-encoded. The schema was flat and minimal — essentially name, description, personality, scenario, first_mes, and a few sibling fields. It carried the community for years, and most hosts still accept it as a fallback.

But V1 left no room for lorebooks, alternate greetings, or any structured metadata about who made the card or which model it was tuned against. Anything beyond the basics had to be smuggled into the description prose. That’s the gap V2 set out to close.

V2 keeps the same PNG tEXt delivery, but wraps the payload in a top-level envelope:

{
  "spec": "chara_card_v2",
  "spec_version": "2.0",
  "data": {
    "name": "...",
    "description": "...",
    /* every real field lives under data */
  }
}

That nesting is the headline change — older clients that only read the flat shape will see nothing useful, which is why V2 cards almost always include a duplicated V1-style top level as a compatibility shim.

Inside data, V2 introduced a list of fields that creators have come to rely on:

• character_book — a lorebook embedded directly in the card, with its own entries, keys, trigger order, and insertion depth.
• alternate_greetings — an array of additional opening messages, picked randomly or by the user.
• tags and creator, character_version — structured metadata for galleries and provenance.
• system_prompt and post_history_instructions — explicit slots for the system message and jailbreak-style trailing instructions, replacing the older convention of cramming them into description.
• Kept-from-V1 fields with cleaner semantics: personality, scenario, mes_example, first_mes.
• extensions — a free-form object where any host can stash private settings. This is the escape hatch that V3 later builds on.

Host-side, V2 is broadly the safe default in 2026. SillyTavern treats it as canonical. Chub.ai both stores and serves V2. RisuAI supports most of the V2 surface, with a few fields it interprets through its own UI conventions. If you have to pick one format for cross-platform distribution today, V2 is still the answer.

V3 (carried under spec: "chara_card_v3") is best understood as refinement, not rewrite. It layers a small set of new affordances on the V2 envelope and tightens the rules around what was previously under-specified. The new surface most creators will run into includes:

• assets — a way to declare additional media (expressions, alt portraits, audio) alongside the card, rather than relying on host-specific sidecar files.
• group_only_greetings — opening lines that should only appear when the character is loaded into a group chat, not a 1:1.
• nickname — a short, in-chat display name distinct from the canonical character name.
• creator_notes_multilingual — a keyed map of creator notes by locale, so the same card can present author commentary in EN, JA, ZH without picking one and hiding the rest.
• source — an explicit attribution URL (or list of URLs) for when a card derives from, or remixes, an existing one.
• Slightly stricter typing across the schema — arrays are arrays, optionals are explicit, and a few legacy string-or-array ambiguities from V2 are pinned down.

The honest caveat: V3 is still settling. Different hosts implement different subsets, and the spec itself continues to evolve in public. SillyTavern leads in V3 coverage; other hosts ship partial support and quietly fall back to V2 semantics for keys they don’t recognise. This is exactly why a linter that knows which keys survive which hosts is useful — and it’s the niche we’re building tavernai.cards into.

Most V2 → V3 migrations are mechanical: bump spec, add the new optional keys, ship. The places it goes wrong are predictable:

1. Custom keys under extensions. V2 lets any host write anything here. When you migrate to V3, some of those custom keys now have first-class equivalents (e.g. asset references) and others don’t. A naive merge leaves you with the same data in two places, and hosts may prefer one over the other unpredictably.
2. Multilingual fields. creator_notes_multilingual is a V3 addition. Hosts that don’t know about it fall back to the plain creator_notes string. If you only populate the multilingual map and leave the plain field empty, older clients will display nothing.
3. PNG tEXt encoding. The historical convention is Base64-encoded UTF-8 JSON inside a chara keyword. A surprising number of bugs come from tools that write raw UTF-8 (no Base64), or that strip non-ASCII characters before embedding. If your card opens cleanly in one host and silently corrupts in another, this is usually why.
4. Embedded vs external lorebooks. character_book travels with the card — great for portability, painful for shared world-state. If three cards share a lorebook and you maintain it inline, you now have three copies to keep in sync. Most teams end up wanting a canonical external lorebook plus a thin embedded copy as a fallback.
5. Relative paths in assets. V3’s asset references can be relative or absolute, and the spec doesn’t fully nail down the resolution base. Different hosts make different assumptions. If your card travels, absolute URLs (or content hashes) are the safer bet.

tavernai.cards is being built for exactly this workflow: keep a single source of truth for your roster, lint it against both the V2 and V3 specs, and export to whichever shape a given host actually understands.

• Lint — catches missing greetings, stale references, and host-incompatible fields before you publish.
• Auto-migrate — V1 to V2 to V3, with a diff you can review rather than a black-box rewrite.
• Multi-platform sync — push the same card to Chub, RisuAI, and SillyTavern in the dialect each one expects.
• Bidirectional V2 / V3 export — ship a V3 card and a V2 compatibility build from the same source.