πŸͺ¦ Part of the Sunset Pledge

Open File Formats

Spec version 1 β€” 19JUL2026. Every file that leaves AcornSmarts is a format you can read without us β€” so your family's learning record stays usable even if AcornSmarts ever disappears. This spec is drift-locked to the app's export code by an automated test: if the code and this page's source document ever disagree, the build fails.

Three families of artifacts leave the app. All three are plain, standard formats: the backup file (readable JSON), the Backpack code (a short typeable string), and every printable (self-contained HTML / paper).

1. The backup file β€” backupVersion: 1

Produced by Settings β†’ Backup as acornsmarts-backup-YYYY-MM-DD.json. One JSON object, human-readable, no compression, no encryption, no binary blobs. Open it in any text editor.

KeyMeaning
app"acornsmarts" β€” file self-identification
backupVersion1 β€” this spec's format version; parsers key migrations on it
appVersionwhich build wrote the file (e.g. "1.81.0")
exportedAtISO-8601 timestamp
datathe family record: profiles (nickname, grade βˆ’1 = Pre-K … 5, avatar), per-kid states (stars, streak, per-skill mastery, day-by-day history, awards, books, reading log, goals, comfort settings), local classes, and app-level settings (audioOn, lang, season, display comforts, plan, vacation window, learning-lamp hours, Table-Story setup, Family Jar)

Deliberate omissions (privacy, part of the format): a child's real name is stripped from every profile (nickname only), the parent PIN is never written, and the per-device camera opt-in is never written β€” a restored file can't silently enable scanning on a new device.

Restore anywhere via Settings β†’ Restore β€” no account, no network. In the raw file, data.states.<kidId>.days is the day-by-day practice history and data.states.<kidId>.mastery is per-skill standing.

2. The Backpack code β€” format AS1

A compact, versioned, human-typeable string that re-creates a child's working levels and comfort settings on any install. It carries no name and no history β€” levels only.

"AS1"  gradeChar  acc[6]  ( skillToken[3] )*  checksum[2]
  • Alphabet: base-36 (0-9 A-Z); case-insensitive; dashes/spaces stripped (display groups by 4: AS1-XXXX-XXXX-…).
  • gradeChar: P = Pre-K, 0…5 = K…grade 5.
  • acc (6 chars): readingFont(0/1) Β· easyRead(0/1) Β· reducedMotion(0/1) Β· highContrast(0/1) Β· textScale(0 normal / 1 large / 2 xl) Β· dailyTarget(0 = off, 1–4 = option index+1).
  • skillToken (3 chars): 2-char base-36 index into the frozen, append-only skill registry + 1-char level 1–9 β€” old codes decode forever.
  • checksum (2 chars): positional weighted char-code sum of the body (Ξ£ charCode(i)Β·(i+1) mod 1296) as 2 base-36 chars β€” catches typos and transpositions. A parser must reject (never partially import) any code failing the tag, length bounds, or checksum.

3. Printables β€” the Forever File and friends

Every printed artifact (Forever File, Family Almanac report, homeschool compliance export, Backpack Record page, worksheets, certificates, teacher packets) is generated on your device as a self-contained HTML document and handed to the browser's print dialog. No server renders it; the paper (or the saved PDF) is the archival format β€” readable in fifty years by definition.

Versioning promise. This spec is append-only within a version: backupVersion: 1 files and AS1 codes written today stay readable by every future build. A breaking change bumps the version tag (backupVersion: 2, AS2) and this document gains the new section before the code ships β€” the drift-lock test enforces the order.