Hi there,

It would be beneficial to have a standard set of test cards / JSONs so that we could easily verify if the code implements the spec correctly. Also, a way to validate the output V2 card to see if it was formatted correctly.

Following a conversation on Discord with @malfoyslastname, here is a list of fields suggestions, their format, and why.

Spec version

It is possible to add new fields or compatible values in the future without creating a completely different spec. If the spec includes a version number, future versions of the spec can be easily detected and supported, and if an importing software does not support the provided version, it can gracefully inform the user that some fields may not be imported, instead of just silently dropping them.

Valid values:

2.0, 2.1

Example:

{
  "spec": "chara_card_v2",
  "version": "2.1"
}

Culture

Cards are written in a certain language, and I hope people will feel comfortable creating characters in their own language.

It can also be used for:

• Auto-correct in input fields
• Speech recognition
• Voice

Valid values:

Strings following RFC 5646 such as en or en-GB.

Example:

{
  "data": {
    "culture": "en-us"
  }
}

Tags

We need a simple way to find imported characters and to make them discoverable.

Valid values:

A list of strings, all lowercase, numbers and underscores only.

A set of tags would be considered standard, but that list will grow independently of the spec itself:

• nsfw: Adult content
• female, male (if gender is not accepted)

Example:

{
  "data": {
    "tags": [
      "nsfw",
      "adventure",
      "custom_tag_123"
    ]
  }
}

Author

Who made that character, good motivation for character builders and easier to find more by the same author in the future.

Valid values:

A username, and potentially a URL to get more or contribute (e.g. patreon)

Example:

{
  "data": {
    "author": {
      "name": "johndoe",
      "url": "https://..."
    }
  }
}

Version

If a character was updated (typos fixed, more details added, more lore created, etc) we need to know which is which.

Valid values:

A single sequential number, OR semver.

Example:

{
  "data": {
    "version": "1.0"
  }
}

Origin

Where the character was uploaded to first, so if you get a character from someone, it's possible to track it down. That field could be auto-populated by boorus, or by the author, but it's completely optional. I expect people will use it to point to their Discord server, Patreon, Twitter, etc.

Valid values:

A valid https url.

Example:

{
  "data": {
    "origin": "https://twitter.com/whatever"
  }
}

Extensions

We need a way to add useful fields such as gender, age, and eventually custom fields such as visual novel software requiring animation data for example.

The difference between extensions and root fields like personality is that this is NOT meant to be sent as a prompt, but rather for supporting the software using the card.

This can also be useful to avoid custom export formats, e.g. "exported by software version", etc.

NOTE: Any field that is suggested in extensions that is NOT software-specific could eventually (or already) be migrated to a root field in future versions of the spec. For example, culture, gender, age, voice, llm, etc. The objective is for anyone who needs additional data to have a way to do so.

Valid values:

Keys must be strings, values are any (object, string, number, boolean)

Example:

{
  "data": {
    "extensions": {
      "text_color": "#ff3333",
      "agnai/voice": { "service": "elevenlabs", "id": "Bella" }
    }
  }
}

Use this thread for general discussion and debate regarding the Character Card Spec V2. Anyone may freely use this thread to discuss the spec. However, if you are an owner or representative for a project in the ecosystem (frontend, card editor, card repository...) please identify yourself in your first post, as we hope to achieve a consensus before validating the spec.

I may also be contacted by email at [email protected] or through your own dev discussion channels (email me a link if I'm not already there).

• Spec (shorter, read first)
• Explainer (longer, justifies technical decisions)

Project positions expressed

Current state of the spec/explainer approved (this is where we'd like everyone to be)

• RisuAI (@kwaroran)
• characterhub.org (@lloorree)
• Agnai (@sceuick)
• SillyTavern (@Cohee1207)
• Pygmalion booru (devh8)
• TavernAI (@TavernAI)

Conditional or partial approval, details included

Will not support the spec

Pending

• ZoltanAI (@ZoltanAI potentially impossible to contact)

If your project has been omitted, please get in contact.

Note: The main Tavern branch and their character repository Characloud have already drifted from this ecosystem, so although we aim to remain compatible with their ecosystem, consensus between V1-compatible projects is the main priority.

If you are a regular user or developer with questions about this spec, feel free to post them in this thread.
I can also be contacted at [email protected] if you don't have a GitHub account, but questions in this thread are more likely to get noticed.