Content records

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.

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[];
}

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

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.

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

{
  "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.

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.

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

Get started

Course data structure

Build on Asakiri

Collections and fields

Records

Example record

Presentation

Writing systems

​Collections and fields

​Records

​Example record

​Presentation

​Writing systems

Collections and fields

Records

Example record

Presentation

Writing systems