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.
When parsing these fields, many implementations omit unsupported fields from generated output. It is recommended to handle invalid/missing fields as gracefully as possible, while populating as many as possible when exporting/generating cards.
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.
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 |
|---|---|
| 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
A Lorebook is a simple, effective way to implement RAG, enhancing a Character Card without exploding token usage. Basically, when key words appear in the history, a Lorebook adds additional content to the prompt if token space is allowed.
Interfaces rarely implement all Lorebook features. It is recommended to rely on as few features as possible when writing these structures.
JSON Structure
| Field Name | Type | Description |
|---|---|---|
| name | String | This field is often missing! |
| description | String | Not used in prompt generation. |
| scan_depth | Number | How many messages to look back into for key matches. |
| token_budget | String | Limits the amount of tokens used by the lorebook. |
| recursive_scanning | String | Controls the ability of entries to trigger other entries. |
| extensions | Object | Can be anything the generator populates here. |
| entries | Entry Array |
Entry Object
| Field Name | Type | Description |
|---|---|---|
| keys | String Array | Text matches which trigger this entry. |
| content | String | The content which is added to the prompt when this entry is triggered. |
| extensions | Object | Can be anything the generator populates here. |
| enabled | Boolean | |
| insertion_order | Number | Sorts different entries when triggered - lower values inserted higher. |
| case_sensitive | Boolean | Controls case sensitivity when looking for key matches. |
| use_regex | Boolean | If true, keys contain valid regex which should be used for finding a match. |
| constant | Boolean | If true, always activated. |
| name | String | Name of this entry. Not used in prompt generation. |
| priority | Number | If token limits are reached, lower priority values are omitted first. |
| id | Number/String | Both Number and String values have been encountered. In either case, this is not used in prompt generation. |
| comment | String | Additional note or comment left by the author. Not used in prompt generation. |
| selective | Boolean | If true, require match from both keys and secondary_keys to trigger entry. |
| secondary_keys | String Array | Text matches referenced by selective to further restrict entry activation. |
| position | String | Either 'before_char' or 'after_char', determining position of entry relative to character definitions in prompt. |
PNG
PNG metadata description coming soon.
Other CharaCard "Standards"
malfoyslastname's specification collection here. Considers implementations of SillyTavern and agnai.
kwaroran's CCv3 specification here. Elements of this seem to be extremely aspirational and/or dubious. e.g. Decorators seem to have zero adoption.