Card formats, briefly

Reference notes · what the workbench reads and writes

Three shapes of character card are in circulation, and most tools do not tell you which one you are holding. This page is the short version of what differs and what you lose going between them.

Where the JSON lives

A character card PNG is an ordinary image. The card data rides along in tEXt chunks — key/value metadata blocks the image format has always allowed. Two keywords matter:

• chara — base64-encoded UTF-8 JSON. The original slot; still written by nearly everything.
• ccv3 — same encoding, V3 payload. When both are present, ccv3 wins.

V3 also allows embedded assets under chara-ext-asset_:{path} chunks. Larkbench reports these and carries them through untouched on export, but does not currently unpack them.

Because the data is metadata rather than pixels, re-embedding does not need to re-encode the image. Larkbench rewrites only the text chunks and copies every other byte verbatim — so your artwork comes out bit-identical, not recompressed. Tools that round-trip a card through a canvas quietly degrade the image every save.

V1

Flat JSON with the original key names: char_name, char_persona, char_greeting, world_scenario, example_dialogue. That is the whole format. No worldbook, no alternate greetings, no system prompt, no metadata.

Converting to V1 is lossy and always will be — the slots simply do not exist. Larkbench offers it because some older tooling still expects it, but it will drop everything the format cannot hold.

V2

Modern key names (name, description, first_mes …) plus the things V1 lacked: system_prompt, post_history_instructions, alternate_greetings, creator, creator_notes, character_version, tags, an embedded character_book, and a free-form extensions object.

V2 is written two ways in practice: wrapped as { spec: "chara_card_v2", data: {…} }, or as a bare flat object with the fields at top level. Both are read here, and both are offered on export — V2 JSON is the wrapped form, V2 flat is the bare one.

V3

Always wrapped: { spec: "chara_card_v3", spec_version: "3.0", data: {…} }. Everything V2 has, plus nickname, group_only_greetings, creator_notes_multilingual, source, assets, and creation/modification timestamps.

Going V3 → V2 loses the V3-only fields and nothing else. Going V2 → V3 is safe: it is a superset.

Fields your model sees on every turn

Four fields are prepended to the prompt for the entire conversation: description, personality, scenario and system_prompt — plus any worldbook entry marked constant (always-on). Everything else is situational: first_mes is sent once, mes_example is often trimmed as the conversation grows, and keyed worldbook entries only appear when a keyword matches.

That distinction is what the workbench's permanent context figure measures. A card with a 3,000-token description is not "a big card" — it is a card that spends 3,000 tokens of every request, forever. Moving background detail out of description and into keyed worldbook entries is usually the single largest saving available.

Non-standard keys

Plenty of cards carry keys no spec mentions, written by one tool and read by another. Larkbench keeps them: anything unrecognised is preserved verbatim and written back out on export, so a round-trip through this page does not silently strip someone else's data.