This is an old revision of the document!
Table of Contents
CharaCard
The CharaCard specification covers three formats and describes its interaction with the PNG specification. As with any community-defined specification, the precise meanings and definitions are somewhat fluid and determined only by a specific implementation. The most common implementations being SillyTavern and Character Hub. This page documents the CharaCard specification, as generally implemented by the myriad of archives and interfaces which interact with these items - not just the most popular.
Overall Structure
Character Cards are usually distributed as PNG images or JSON text documents. The JSON document directly contains the CharaCard JSON structure, while the PNG contains the same JSON CharaCard structure as metadata. Note that the PNG is not a polymorphic JSON/PNG hybrid file, but a fully standards-compliant (if unusually constructed) PNG, with metadata which can be decoded back into a JSON CharaCard structure.
CCv1
Version 1 was created with TavernAI, and is long obsolete. This standard is not backwards compatible and provided as a matter of historical interest. All fields are required and utilized as part of prompt generation.
JSON Structure
| Field Name | Type | Description |
|---|---|---|
| description | String | Overall description of setting/background of the Card. |
| first_mes | String | The initial message presented by the Card on first chat. |
| mes_example | String | Example Card messages to align Card response style. |
| name | String | Name of card and character within card. |
| personality | String | Description of Card Character nature specifically. |
| scenario | String | Specific scenario that the Card and user are engaging with. |
CCv2
CCv3
CharaCard Version 3 is backwards compatible, adding only optional, additional fields.
When parsing these fields, note that many implementations omit unsupported fields from generated output. It is recommended to handle invalid/missing fields as gracefully as possible.
JSON Structure
| Field Name | Type | Description |
|---|---|---|
| spec | String | Either 'chara_card_v2' or 'chara_card_v3' depending on version. |
| spec_version | String | Either '2.0' or '3.0' depending on version. |
| data | Object | This object is described below. |
Data Object
| Field Name | Type | Description | |
|---|---|---|---|
| name | String | Name of card and character within card. | |
| description | String | Overall description of setting/background of the Card. | |
| personality | String | Description of Card Character nature specifically. | |
| scenario | String | Specific scenario that the Card and user are engaging with. | |
| first_mes | String | The initial message presented by the Card on first chat. | |
| mes_example | String | Example Card messages to align Card response style. | |
| creator_notes | String | Notes about the card. Not used in prompt generation. | |
| system_prompt | String | System prompt replacement. Rarely superior to the one configured by your interface. | |
| post_history_instructions | String | Placed after chat messages in history. Traditionally used for jailbreak instructions, but this is no longer recommended. | |
| alternate_greetings | String | Extra first_mes for users to select between when starting the chat. | |
| character_book | Object | CharacterBook object, see Lorebooks below for more information. | |
| tags | String Array | Short strings describing genres in the card. | |
| creator | String | Name of the Card author. Not used in prompt generation. | |
| character_version | String | Version provided by the Card author. Not used in prompt generation. | |
| extensions | Object | Can be anything the generator populates here. | |
| New CCv3 Fields | |||
| assets | Asset Array | Array of Asset objects (see below). Uncommon. | |
| nickname | String | When present, nickname is the name of the character in the Card, and name can be a different name for the Card itself. | |
| creator_notes_multilingual | Object | An object of <language code>:<creator notes in that language>. Uncommon. | |
| source | String Array | Various URLs constituting the 'source' of the card. Uncommon. | |
| group_only_greetings | String Array | Like alternate_greetings, but only shown when the card is in a group chat. | |
| creation_date | Number | Unix timestamp in ms. | |
| modification_date | Number | Unix timestamp in ms. | |
Asset object
| Field Name | Type | Description |
|---|---|---|
| type | String | |
| uri | String | |
| name | String | |
| ext | String |
There are more details to be added here, especially with regards to RisuAI's divergent implementations.
Lorebook
Lorebook specifications in-progress.
PNG
PNG metadata description coming soon.