> For AI agents: the complete documentation index is available at https://docs.flashnerd.com/llms.txt, the full documentation bundle is available at https://docs.flashnerd.com/llms-full.txt.
# 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](https://docs.flashnerd.com/reference/flashnerd-format/folders-and-tags.md#review-folders):
```jsonl
{"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](https://docs.flashnerd.com/reference/flashnerd-format/folders-and-tags.md#review-folders), and their values are shown in [full cards](https://docs.flashnerd.com/reference/flashnerd-format/cards.md). TTS references a field ID in the same layout.
### Language deck: seven field types
```json
{
"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
```json
{
"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](https://docs.flashnerd.com/reference/flashnerd-format/package.md#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](https://docs.flashnerd.com/reference/flashnerd-format/fields.md); 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](https://docs.flashnerd.com/reference/flashnerd-format/package.md#timestamps-and-calendar-dates) 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](https://docs.flashnerd.com/reference/flashnerd-format/package.md#limits).
The [field reference](https://docs.flashnerd.com/reference/flashnerd-format/fields.md) gives the values, settings, defaults, null behavior, and examples for all 11 types. The same definitions are used in [card-template presets](https://docs.flashnerd.com/reference/flashnerd-format/presets.md#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:
```json
{
"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](https://docs.flashnerd.com/reference/flashnerd-format/folders-and-tags.md#review-folders), not an SRS folder.
- Each [card](https://docs.flashnerd.com/reference/flashnerd-format/cards.md) 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](https://docs.flashnerd.com/reference/flashnerd-format/srs.md#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](https://docs.flashnerd.com/reference/flashnerd-format/fields.md).
An anonymous deck, which cannot be a `deckId` or `deckIds` target. Its field IDs stay required:
```jsonl
{"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:
```jsonl
{"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](https://docs.flashnerd.com/reference/flashnerd-format/presets.md#ai-instruction-presets).