Deck records

A deck names a collection of cards and defines its ordered fields, visibility, and study-mode settings. Cards refer to it by deckId; the filename is not the deck's identity.

Location and basic example

Place one JSON object per physical line in any content/decks/*.jsonl file, for example content/decks/tokyo.jsonl or content/decks/my-decks.jsonl. Filenames are arbitrary; the reader discovers all files directly in that canonical directory. Do not add another enclosing directory. The collection may be omitted when the package contains no decks and nothing references a deck.

This complete JSONL line defines a deck. It requires the folder-languages record shown under Review folders:

{"id":"deck-tokyo","folderId":"folder-languages","name":"Tokyo Phrases","fields":[{"id":"field-front","name":"Front","side":"front","type":"text"},{"id":"field-back","name":"Back","side":"back","type":"text"},{"id":"field-image","name":"Image","side":"back","type":"image"},{"id":"field-audio","name":"Audio","side":"back","type":"audio"}]}

To use this deck at the root without a folder, omit folderId or set it to null. The media fields do not require media until a card supplies a mediaPath.

Full example

Copy the runnable content/decks/00000.jsonl, or read its expanded records below. Each object occupies one physical line in the file; the formatting here is for reading.

These two decks collectively define all 11 field types. Both include every deck and study-mode setting. Their folder companions are in review folders, and their values are shown in full cards. TTS references a field ID in the same layout.

Language deck: seven field types

{
  "id": "deck-japanese-travel",
  "aiInstructionPresetId": "preset-ai-japanese",
  "folderId": "folder-japanese",
  "name": "Japanese Travel",
  "createdAt": "2026-03-01T09:00:00.000000Z",
  "updatedAt": "2026-03-02T09:00:00.000000Z",
  "fields": [
    {
      "id": "field-ja-word",
      "name": "Word",
      "side": "front",
      "type": "japanese",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {
        "showPitchAccent": true,
        "showFurigana": true,
        "showRomaji": true,
        "annotationSetting": "hint",
        "furiganaOverrides": [
          {
            "sourceIndex": 0,
            "expectedKanji": "駅",
            "rubyOverride": "えき"
          }
        ],
        "romajiOverride": "eki",
        "romajiType": "ascii",
        "pitchOverridePattern": [
          "H",
          "L"
        ]
      }
    },
    {
      "id": "field-ja-meaning",
      "name": "Meaning",
      "side": "back",
      "type": "text",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {}
    },
    {
      "id": "field-ja-audio",
      "name": "Audio",
      "side": "note",
      "type": "audio",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {
        "autoplay": true
      }
    },
    {
      "id": "field-ja-photo",
      "name": "Photo",
      "side": "note",
      "type": "image",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {}
    },
    {
      "id": "field-ja-speak",
      "name": "Speak",
      "side": "note",
      "type": "tts",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {
        "autoplay": true,
        "sourceType": "field_reference",
        "contentSourceId": "field-ja-word",
        "locale": "ja-JP"
      }
    },
    {
      "id": "field-zh-word",
      "name": "Chinese",
      "side": "front",
      "type": "chinese",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {
        "chineseType": "simplified",
        "showPinyin": true,
        "annotationSetting": "hint",
        "pinyinOverrides": [
          {
            "tokenIndex": 0,
            "pinyin": "zhan4"
          }
        ]
      }
    },
    {
      "id": "field-ja-map",
      "name": "Map",
      "side": "both",
      "type": "image_occlusion",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {}
    }
  ],
  "deckSettings": {
    "showTags": false
  },
  "modeSettings": {
    "flashcard": {
      "cardOrientation": "reverse",
      "cardsPerSession": 8,
      "shuffleCards": false,
      "autoAdvance": true,
      "timeBeforeShowingAnswer": 4,
      "timeBeforeNextCard": 2,
      "defaultAnswer": "pass",
      "showElapsedTime": true
    },
    "matching": {
      "matchSideA": "field-ja-word",
      "matchSideB": "field-ja-meaning",
      "numberOfPairs": "three",
      "showElapsedTime": true
    }
  }
}

Programming deck: remaining field types

{
  "id": "deck-dart-fundamentals",
  "folderId": "folder-programming",
  "name": "Dart Fundamentals",
  "createdAt": "2026-03-01T09:00:00.000000Z",
  "updatedAt": "2026-03-02T09:00:00.000000Z",
  "fields": [
    {
      "id": "field-dart-prompt",
      "name": "Prompt",
      "side": "front",
      "type": "text",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {}
    },
    {
      "id": "field-dart-code",
      "name": "Code",
      "side": "note",
      "type": "code",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {
        "selectedLanguage": "dart",
        "showLineNumbers": true,
        "wrapLines": true,
        "forceDarkMode": true,
        "showLanguageHeader": true,
        "fitToContent": false,
        "minLines": 3,
        "maxLines": 12
      }
    },
    {
      "id": "field-dart-cloze",
      "name": "Cloze",
      "side": "both",
      "type": "cloze",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {}
    },
    {
      "id": "field-dart-notes",
      "name": "Notes",
      "side": "back",
      "type": "rich_text",
      "generalSettings": {
        "isHidden": false
      },
      "settings": {}
    },
    {
      "id": "field-dart-formula",
      "name": "Formula",
      "side": "note",
      "type": "tex",
      "generalSettings": {
        "isHidden": true
      },
      "settings": {
        "autoSize": false
      }
    }
  ],
  "deckSettings": {
    "showTags": true
  },
  "modeSettings": {
    "flashcard": {
      "cardOrientation": "reverse",
      "cardsPerSession": 8,
      "shuffleCards": false,
      "autoAdvance": true,
      "timeBeforeShowingAnswer": 4,
      "timeBeforeNextCard": 2,
      "defaultAnswer": "pass",
      "showElapsedTime": true
    },
    "matching": {
      "matchSideA": "field-dart-prompt",
      "matchSideB": "field-dart-notes",
      "numberOfPairs": "three",
      "showElapsedTime": true
    }
  }
}

Record properties

Property	Required	Values and default	Explicit `null`
`id`	No	Nonempty string when supplied, unique among decks. Readable IDs such as `deck-tokyo` are valid. Omission creates a temporary source identity and always imports as a new deck. Nested field IDs stay required.	Invalid
`folderId`	No	ID of a record in `content/review_folders/`; omission means the root. An empty string fails the folder reference check.	Root
`name`	Yes	Nonblank display name. Default package-validation limit: 40 UTF-16 code units after trimming; see app limits.	Invalid
`createdAt`	No	Timestamp with a timezone when supplied. Omission and null mean unavailable metadata.	Unavailable
`updatedAt`	No	Timestamp with a timezone when supplied. Omission and null mean unavailable metadata.	Unavailable
`fields`	Yes	Ordered array of field definitions; see layout rules below.	Invalid
`aiInstructionPresetId`	No	Explicit companion instruction-preset ID; omission preserves a selection on override and otherwise means None.	None
`deckSettings`	No	Optional `showTags` setting, detailed below. Omission gives its defaults.	Invalid
`modeSettings`	No	Optional `flashcard` and `matching` sections, both detailed below. Omission gives all mode defaults.	Invalid

Extra properties are ignored, including inside settings sections. Recognized settings retain their value and reference rules. Optional timestamps are not generated for you. See timestamp syntax for timezone offsets, precision, and import persistence.

Field layout

The order of fields is the display order. Each field requires id, name, side, and type; generalSettings and type-specific settings are optional. A field's ID is scoped to its owning deck or template preset, and names must be unique in that layout after trimming and lowercasing.

Every deck needs a front-capable field (front or both) and a back-capable field (back or both). A single both field is sufficient. A note field alone satisfies neither requirement. Cloze and image-occlusion fields must use both. The default package-validation limits are 20 fields per deck and 30 UTF-16 code units per trimmed field name. The schema also allows 20 fields, but its field-name length counts untrimmed Unicode code points. The app configures different metadata limits; see limits.

The field reference gives the values, settings, defaults, null behavior, and examples for all 11 types. The same definitions are used in card-template presets.

Deck settings

deckSettings contains only:

Property	Values	Default when omitted or `null`
`showTags`	Boolean; show card tags.	`true`

Omitting deckSettings, writing {}, or writing {"showTags":null} all gives showTags:true. Writing "deckSettings":null is invalid.

Study-mode settings

The file format preserves two optional sections in modeSettings: flashcard and matching. Omit a section or use {} to keep that mode's defaults. A section explicitly set to null is invalid.

`modeSettings.flashcard`

Property	Values	Default	Explicit `null`
`cardOrientation`	`normal` (front first), `reverse` (back first), or `random`	`normal`	Invalid
`cardsPerSession`	Integer; number of cards per session.	`10`	Default
`shuffleCards`	Boolean	`true`	Default
`autoAdvance`	Boolean	`false`	Default
`timeBeforeShowingAnswer`	Integer seconds; delay before revealing the answer during auto-advance.	`5`	Default
`timeBeforeNextCard`	Integer seconds; delay before advancing to the next card.	`5`	Default
`defaultAnswer`	`fail` or `pass`; default for an unanswered card.	`fail`	Invalid
`showElapsedTime`	Boolean	`false`	Default

Counts and delays are parsed as integers. The format does not impose additional numeric bounds on these mode settings; use positive session counts and nonnegative delays when authoring.

`modeSettings.matching`

Property	Values	Default	Explicit `null`
`matchSideA`	String; field ID for the first matching column.	`""` (not selected)	Default
`matchSideB`	String; field ID for the second matching column.	`""` (not selected)	Default
`numberOfPairs`	`two`, `three`, `four`, `five`, or `six`	`four`	Invalid
`showElapsedTime`	Boolean	`false`	Default

Pair counts are words, not numbers. Use IDs from this deck's fields for selected columns. The format parses the selection strings without checking that the referenced fields exist; choose valid field IDs for useful imported settings.

Complete settings example

This expanded JSON is an explanatory nested fragment, not a complete JSONL record. Its keys belong inside a deck record. It shows every deck/mode property, using the basic deck's field IDs:

{
  "deckSettings": {"showTags": true},
  "modeSettings": {
    "flashcard": {
      "cardOrientation": "normal",
      "cardsPerSession": 10,
      "shuffleCards": true,
      "autoAdvance": false,
      "timeBeforeShowingAnswer": 5,
      "timeBeforeNextCard": 5,
      "defaultAnswer": "fail",
      "showElapsedTime": false
    },
    "matching": {
      "matchSideA": "field-front",
      "matchSideB": "field-back",
      "numberOfPairs": "four",
      "showElapsedTime": false
    }
  }
}

Relationships and additional examples

folderId refers to an explicit review folder, not an SRS folder.
Each card names its deck with an explicit deckId; keys in the card's values must belong to this deck's fields and have matching types.
SRS sets may include this deck's explicit ID in deckIds. A deck that omitted id cannot be a relationship target. Nested field IDs remain required. Under Override Existing, an anonymous deck still receives new nested field IDs.
Field-referenced TTS settings may refer only to supported fields in the same deck; see the TTS rules.

An anonymous deck, which cannot be a deckId or deckIds target. Its field IDs stay required:

{"name":"Scratch","fields":[{"id":"field-front","name":"Front","side":"front","type":"text"},{"id":"field-back","name":"Back","side":"back","type":"text"}]}

A complete, independent deck with one cloze field is valid because that field covers both sides. This is one JSONL record:

{"id":"deck-cloze","name":"Geography","createdAt":"2026-01-01T00:00:00Z","updatedAt":"2026-01-01T00:00:00Z","fields":[{"id":"field-sentence","name":"Sentence","side":"both","type":"cloze"}]}

An empty deck may have no cards, but fields:[] is invalid because it supplies neither side. Omitting the entire decks collection is different from supplying an invalid empty layout.

Schemas: deck record, field definition, and field settings. Layout and relationship checks described here are enforced by the reader in addition to the schema's structural checks.

AI instruction preset selection

aiInstructionPresetId is optional. A nonempty string selects a companion in preferences/ai_instruction_presets/*.jsonl; that record must provide an explicit ID. Null selects None. Omission preserves an existing selection on override, while new decks default to None. Unknown IDs, empty strings and non-string values are invalid. The full Japanese deck above requires the companion instruction preset.

#Deck records

#Location and basic example

#Full example

#Language deck: seven field types

#Programming deck: remaining field types

#Record properties

#Field layout

#Deck settings

#Study-mode settings

#modeSettings.flashcard

#modeSettings.matching

#Complete settings example

#Relationships and additional examples

#AI instruction preset selection