Subjects, languages and decks

All of Verso’s cards live in JSON files in the site’s source, grouped into four collections: languages, subjects, categories and decks. Cards live inside their deck. A fifth collection, packs, groups decks for Play. Each file’s path is its id, and the ids make the addresses:

Files point at each other by id: a subject names its languages, a category its subject, a deck its category, and a pack its decks and categories. A reference to a file that doesn’t exist fails the build.

Languages

A language describes how text in it is written and read. Subjects use languages for their cards’ sides.

{
  "name": "Chinese",
  "nativeName": "中文",
  "locale": "zh-Hans",
  "font": "han",
  "reading": { "name": "Pinyin", "locale": "zh-Latn-pinyin" }
}

The han font is a Chinese serif. A reading is never set in it, so pinyin stays in the site’s monospaced font. Verso has three languages today: English (en), Chinese (zh-Hans) and Hawaiian (haw).

Subjects

A subject is a body of cards, such as a language you’re learning.

{
  "name": "Hawaiian",
  "categoryLabel": "Topics",
  "front": { "language": "haw" },
  "back": [{ "language": "en" }, { "language": "zh-Hans" }]
}

Each side’s label, font, locale and reading come from its language. A side’s name overrides the label. Chinese names its front 汉字, so the Prompt side buttons read “汉字 first” and “English first”.

When a subject’s name matches its front language’s name, as Chinese and Hawaiian do, its title is shown in that language: 中文, ʻŌlelo Hawaiʻi.

The back list is what makes learning through another language possible. Every card needs a back in the first language on the list; the others are optional.

Categories

A category is a part of a subject: one HSK level, or one topic.

Decks

A deck is about 25 cards from one category, named like “HSK 1 · Deck 3”. A short topical list can use smaller decks named by theme, like “Hula and hālau · Attire”.

An available deck must have cards; an empty one has to be marked coming-soon. A deck tag that none of its cards carry applies to the whole deck when searching.

Cards

A card has a front (the word) and a back (its meaning), with the back keyed by language.

{
  "front": { "text": "kāʻai", "alt": "ka'ai" },
  "back": {
    "en": {
      "text": "sash, waistband",
      "note": "Tied around the waist over the pāʻū"
    },
    "zh-Hans": {
      "text": "腰带",
      "reading": "yāodài",
      "note": "系在腰间，压在 pāʻū 外面",
      "review": "machine"
    }
  },
  "tags": ["clothes"]
}

The front:

• text is the word itself, written the standard way, such as kāʻai with its ʻokina and kahakō.
• alt is another spelling or form, such as ka'ai the way it was first typed.
• reading is the word in its language’s reading, such as pinyin for Chinese.

Each back:

• text is the meaning in that language. Several meanings are separated by commas, and search treats each one as its own answer.
• reading is the meaning in that language’s reading, such as pinyin under a Chinese meaning.
• note is context or usage in that language, shown on the answer side and in the word list.
• review is left out for text written by hand. "machine" marks a machine draft no speaker has checked yet, and "checked" marks one that has been.
• source records where that language’s text came from. It’s kept with the content but not shown; the card’s own source is the one shown.

Packs

A pack is a ready-made selection for Play, such as every deck in HSK 1.

{
  "title": "A taste of both",
  "summary": "The first deck of Chinese and the first of ʻŌlelo Hawaiʻi, dealt together in one hand.",
  "order": 3,
  "featured": true,
  "decks": ["chinese/hsk-1/deck-01", "hawaiian/hula-and-halau/deck-01"]
}

A pack needs at least one deck or category. Its decks are played in catalog order, whatever order the file lists them in. Packs you save yourself aren’t content: they live in your browser (see Privacy and storage).

Sources

A source is { "name": "…", "url": "…" }, and the url is optional. It goes on a category when the whole category comes from one list, as the HSK levels do, and on a card when that card has its own origin. Words picked up in everyday life have nothing to cite, so they have no source. A category page, and a card’s answer side and word-list row, show a Source line only when there is one.

The Chinese cards come from the new HSK word-list tables published by MandarinBean: the simplified word, pinyin, part of speech and English gloss. The ʻŌlelo Hawaiʻi cards are a personal list from a hula hālau, with spellings checked against the Pukui–Elbert Hawaiian Dictionary. Decks only hold words from their subject’s own language.

Status

Subjects, categories and decks can each be marked coming-soon. A deck can be played only when it has cards and it, its category and its subject are all available. Everything else still shows up while you browse, with a Coming soon badge, but has no study page and can’t be picked on the Play page. A category or subject with no playable decks is shown as coming soon too.

Checks at build time

The site isn’t built if the content has a mistake. Besides each field’s type and the references between files, the build checks that:

• every available deck has cards
• every pack names at least one deck or category, and each of them is playable
• every card has a back in its subject’s default language
• every back is in a language its subject offers
• no subject offers its own front language as a back, or the same back twice
• ʻŌlelo Hawaiʻi text uses the ʻokina (U+02BB), not an apostrophe standing in for it, on the front and in Hawaiian backs and notes
• a card’s kind uses only these words: noun, verb, adjective, adverb, pronoun, number, classifier, number-classifier, preposition, conjunction, auxiliary, interjection, onomatopoeia, prefix, suffix

Each build also prints, for every subject, how many cards have a back in each language and how many of those are machine drafts.