> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asakiri.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Content records

> Collections, field definitions, and records: the reusable source of truth.

Content is reusable semantic knowledge organized into **collections** that display as
tables. A collection defines fields; a record fills them in. Records carry globally
unique IDs, so a reference does not also need to carry a collection ID.

## Collections and fields

A collection has a stable ID, a name, and an ordered list of field definitions.

```ts theme={null}
type FieldKind = "text" | "asset";
type FieldCardinality = "one" | "many";

interface FieldDefinition {
  readonly id: string;
  readonly name: string;
  readonly kind: FieldKind;         // text or a reference to a media asset
  readonly cardinality: FieldCardinality; // "one" scalar, or "many" (a list)
  readonly required: boolean;
  readonly locale?: string;         // e.g. "ja", "en"
  readonly assetKind?: AssetKind;   // for asset fields: audio | image | video
}

interface Collection {
  readonly id: string;
  readonly name: string;
  readonly description?: string;
  readonly fields: readonly FieldDefinition[];
}
```

<Info>
  Field **IDs** are stable and independent from their visible **names**. Renaming a
  column never breaks references that point at it.
</Info>

## Records

A record belongs to one collection and stores a value per field. A field value is text,
an asset reference, or a list of items.

```ts theme={null}
type RecordFieldItem =
  | { readonly id: string; readonly kind: "text"; readonly value: string;
      readonly label?: string; readonly locale?: string }
  | { readonly id: string; readonly kind: "asset"; readonly assetId: string;
      readonly label?: string; readonly locale?: string };

type RecordFieldValue =
  | { readonly kind: "text"; readonly value: string }
  | { readonly kind: "asset"; readonly assetId: string }
  | { readonly kind: "list"; readonly items: readonly RecordFieldItem[] };

interface ContentRecord {
  readonly id: string;
  readonly collectionId: string;
  readonly fields: Readonly<Record<string, RecordFieldValue>>;
  readonly presentations?: readonly RecordPresentation[];
}
```

A `many` field holds a `list` value. Each item in a list gets a **stable item ID**,
because an author may reference one pronunciation, image, or translation independently.
Scalar (`one`) fields do not need value IDs.

## Example record

```json theme={null}
{
  "id": "record_cat",
  "collectionId": "vocabulary",
  "fields": {
    "japanese": { "kind": "text", "value": "猫" },
    "english": { "kind": "text", "value": "cat" },
    "pronunciations": {
      "kind": "list",
      "items": [
        { "id": "pronunciation_primary", "kind": "asset", "label": "Japanese (speaker A)", "assetId": "asset_cat_ja_audio" },
        { "id": "pronunciation_english", "kind": "asset", "label": "English (speaker B)", "assetId": "asset_cat_en_audio" }
      ]
    },
    "images": {
      "kind": "list",
      "items": [{ "id": "image_primary", "kind": "asset", "assetId": "asset_cat_image" }]
    }
  }
}
```

## Presentation

A record can carry one or more presentations that choose a primary field and which
columns are visible. Presentation is a view concern; it never changes what the record
means or how it is referenced.

```ts theme={null}
interface RecordColumn { readonly fieldId: string; readonly visible: boolean }
interface RecordPresentation {
  readonly id: string;
  readonly primaryFieldId: string;
  readonly columns: readonly RecordColumn[];
}
```

## Writing systems

Alphabets and characters are content, not a separate entity. A character is a record
with text and asset fields (glyph, romanization, pronunciation audio, stroke-order
media), so a writing system is a collection like any other.

Three writing-system concerns are all expressible today:

* **Order:** the collection's ordered record list captures canonical order (gojūon, alphabetical).
* **Grid and grouping:** fields like `row` and `vowel` let a view rebuild a syllabary grid.
* **Relations:** variants and derived forms (が from か) are record-to-record links via a
  `record` [binding](/data-structure/bindings).

Prefer one collection per writing system, since field shapes differ across scripts
(kanji needs readings and meanings that kana does not).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.