Character card V2 vs V3: what actually changed

V3 did not replace V2. It added a handful of fields V2 has nowhere to put, kept every field V2 already had, and told apps that already understood the older format how to keep opening the same file. That is the whole change. Most arguments about "which version to use" are arguments about those extra fields, not about a new kind of character.

The names on the wire are chara_card_v2 and chara_card_v3, sitting next to a spec_version of 2.0 or 3.0. A PNG card hides that JSON in a text chunk: chara for V2, ccv3 for V3. A .json card is the same object without the picture. A .charx file is V3's bundle: a zip with card.json at the root and an assets/ folder beside it.

What V2 already had

A V2 card is a wrapper. The character lives under data, not at the root. The fields that have been there since V2 are the ones every app still fills in: name, description, personality, scenario, first message, example dialogue, a system prompt, post-history instructions, alternate greetings, tags, a creator name, a character version, and an optional lorebook (character_book). Unknown keys are supposed to be kept, not dropped.

V1 is older still: six fields at the root, no spec key at all. If a JSON file has no version marker, it is V1 by definition. Almost nobody ships a V1 card on purpose any more, but importers still have to read one, because a file from 2023 does not become invalid when a spec moves on.

What V3 actually added

The Character Card V3 spec lists the new fields in one TypeScript interface. They are not a rewrite of the character. They are the things people were already stuffing into extensions or losing on export.

nickname. Replaces {{char}} when it is set, so a full name in name can stay formal while the model addresses them as Ilse.
assets[]. A list of extra files: type, URI, name, extension. This is how a card carries more than one image, or a sound, without pretending the portrait PNG is the only container.
source[]. A provenance chain. Where the card came from, as URLs or ids, appended rather than overwritten when an app re-exports.
creator_notes_multilingual. The same creator notes in other languages, keyed by ISO 639-1 codes.
group_only_greetings. Openings that only make sense when more than one character is in the room.
creation_date and modification_date. Unix seconds, as the spec defines them, not display strings.
Lorebook decorators. Lines at the head of an entry's content that start with @@. They tell a V3-aware frontend how to insert the entry. A V2 lorebook has no slot for them.

Everything V2 has, V3 has. A V3 card that never uses the new fields is still a valid V3 card; it is just a V2 card wearing a newer wrapper.

There is also .charx. The spec is blunt about the URI scheme: embedded assets are addressed as embeded://… — that spelling, with one 'd', is in the document. A zip that has no card.json is a valid zip and not a card.

How to tell which one you are holding

You do not have to read the spec to find out. Drop the file on the character card viewer. It runs in the browser and uploads nothing.

Drop a PNG, a .json card or a .charx.
Read the detected spec at the top of the decode. v2 or v3 is the wrapper the file declared. A warning that names a dual chunk means the PNG carried both.
Scroll the fields. If you see a nickname, an assets list, a source chain, group-only greetings, dates, or @@ lines on a lorebook entry, you are looking at V3 data — even if a V2 copy of the same card is sitting in the other chunk.
If you need the other format, download it from the same page. V3 JSON is the lossless one. V2 JSON is the compatibility copy. PNG writes both chunks at once.

When a PNG carries both chunks, the warning this product shows is: "This card carries two copies of its data. We read the newer one, which has everything the older copy has and more." The V2 chunk is a lossy copy by construction — it has nowhere to put assets, source[] or decorators — so reading it would silently drop fields a V3 card had shipped.

A card that looks identical to the one you downloaded and still says "no character data" is almost always a picture that was re-saved. Cropping, resizing, screenshotting, or sending the file through an app that recompresses images all produce a valid PNG with no chara or ccv3 chunk. The picture survived. The character did not. Ask for a .json export, which has no metadata to lose.

What a dual-chunk PNG is for

V3-aware apps read ccv3. Older apps read chara. One file can carry both, which is how a card posted as a picture still opens in a V2-only importer. The V3 spec says that if both chunks are present, the application should use ccv3. That is not optional politeness. The V2 copy is the one that had to drop fields.

This site writes both chunks on every PNG export: the maker, the viewer, the Character.AI export viewer, the template gallery. The reason is practical rather than ideological. A file that only has ccv3 is invisible to anything that still looks for chara. A file that only has chara cannot carry a nickname or an assets list. Writing both is the one file that works everywhere, at the cost of a V2 copy that is allowed to be lossy.

If you take a V3 card and download it as V2 JSON from the viewer, these keys are dropped rather than smuggled in under names a V2 reader would not understand: assets, source, nickname, group_only_greetings, creation_date, modification_date, creator_notes_multilingual. Lorebook decorator lines are not a V2 concept either; they do not survive that download. Fields no version of the spec defines are kept in an unknown bucket and written back out, so a round trip through this parser does not invent a cleaner card than the one you had.

A newer spec_version than 3.0 is a warning here, not a failure. The next spec will add fields. An importer that rejected the file would be throwing away a character because it had not been updated yet.

What goes wrong

You saved the picture. The most common failure, and the one that looks like nothing is wrong. Use the original download.

You converted to V2 to "be safe". If the card used V3 fields, you just deleted them. Convert to V2 only for an app that cannot read V3, and keep the V3 file.

You edited the PNG in an image app. Same as saving the picture. The character lived in a text chunk, not in the pixels.

You expected a JPEG portrait to become a PNG card without being re-encoded. Writing a card into a PNG means appending chunks to an existing PNG. A JPEG has nowhere to put them. The character card maker transcodes the image in the browser first, which is why a JPEG or WebP works there. The viewer cannot re-encode a foreign portrait onto the PNG it exports; it will say so before you click.

You fetched a remote asset URI. Do not. A card can point assets[].uri at https://…. This parser records that URI, warns, and moves on. Fetching it would be an unscreened download from an address the card author chose.

Honest limits

The V3 spec describes more than this product uses. Lorebook decorators are preserved as opaque strings; nothing here honours @@depth yet. Non-avatar assets in a .charx — backgrounds, emotion packs, Live2D — are not imported as pictures. The maker's form does not show every V3 field; if you start from an existing card, the fields the form does not show are kept and written back untouched, so editing a greeting is not a way to quietly lose a twenty-entry world.

Token cost did not change with the spec version. Description, personality and scenario are still sent on every turn in most apps, V2 or V3. The character card token counter splits a card field by field so you can see that cost before you add more V3 furniture. A lorebook is still a keyed world, not a second memory; lorebook vs memory is the split.

If you want a filled-in starting point rather than a blank form, the template gallery is eight original V3 cards — mentor, rival, cozy companion, game master, language partner, study coach, noir detective, historical figure. Each one downloads as PNG or JSON, or opens in the maker. The historical-figure template is the same idea as the Icons shelf: a person out of the public domain, written as behaviour rather than as a Wikipedia stub.

V3 is the format to ask for when you can. V2 is the format to keep in the other chunk so yesterday's app still opens the file. The mistake is treating them as two different characters.