Tracker
Tracker data format
The published contract for tracker exports: the version-1 JSON shape, the merge rules, and a JSON Schema your tools can validate against.
The tracker is local-first: your data lives in your browser and leaves only as a JSON export you control — or, if you create an account and sign in, as a synced copy stored on the server in exactly this export format (deleting the account deletes that copy; local-only use sends nothing). This page is the contract for that export, so your own tools — or your agent — can read, merge and validate it. The tables below are rendered from the same schema object that generates the machine-readable schema, so this page and the schema cannot disagree.
Top-level fields
An export is one JSON object with these fields: kind, version, exportedAt, profile, inventory.
kind: always"getpreparedstuff-tracker". Importers reject any other kind.version: format version, currently1. See versioning below.exportedAt: ISO timestamp of the export, or null. Informational only; importers ignore it.profile: the household profile, below.inventory: the inventory entries, below.
Profile fields
| Field | Type | Required | Meaning |
|---|---|---|---|
adults | integer | yes | Adults in the household. |
children | integer | yes | Children (a full person for water; 1,400 kcal/day). |
babies | integer | no | Babies — drives diaper and formula quantities. Older files without it import as 0. |
dogs | integer | no | Dogs. |
cats | integer | no | Cats. |
medUsers | integer | no | People who take daily medication — drives the medication buffer. Older files without it import as 0. |
targetTier | one of: tonight, h72, wk2, mo1, mo3 | yes | Readiness target: tonight = 1 day, h72 = 3 days, wk2 = 14 days, mo1 = 30 days, mo3 = 90 days. Unknown values import as wk2. |
housing | one of: own, rent | no | own = house; rent = apartment / renting / small space (barrels, generators and fixture-change items drop out of gaps and readiness). Older files without it import as own. |
Target tiers: tonight, h72, wk2, mo1, mo3. Housing values: own, rent. On import, profile counts are coerced to integers and clamped to 0 or more.
Inventory entry fields
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | yes | Entry id, unique within the file. Regenerated on import when missing or duplicated. |
itemId | string | null | no | Catalog item id, or null for a custom entry. |
name | string | yes | Display name. |
category | string | yes | Catalog category id, or a free category for custom entries. |
quantity | number | yes | Amount on hand, in unit. Negative or non-finite values reject the import. |
unit | string | no | Unit for quantity (may be empty). For catalog-linked entries this is the catalog rule's unit — see the note below. |
location | string | no | Where it is stored (may be empty). |
purchased | string | null | no | Purchase / fill date, YYYY-MM-DD, or null. Must be a real calendar date. |
expires | string | null | no | Explicit expiry date, YYYY-MM-DD, or null. Must be a real calendar date. |
custom | boolean | no | true when the entry is not tied to a catalog item. |
countsToward | string | null | no | Catalog item id this entry's quantity counts toward — e.g. bottled-water cases counting toward stored water. The quantity is credited in that item's unit, scaled by countsFactor. |
countsFactor | number | null | no | Optional multiplier applied to quantity when crediting countsToward (use it when your unit differs from the item’s unit — e.g. one case of 24 × 500 ml bottles ≈ 3.17 gallons, so countsFactor 3.17 toward stored water). |
notes | string | no | Free notes (may be empty). |
selfFilled | boolean | null | no | For stored water only: true = self-filled containers (the 6-month replacement rule applies); false = commercially bottled water, which follows its own printed expires date instead; null = legacy entry saved before the flag existed, treated as self-filled. |
For catalog-linked entries, unit is the catalog rule's unit; older exports may carry a legacy unit string on such entries — importers must ignore entry.unit for catalog-linked gap credit, and the tracker normalizes it on import.
Merge rules
- Merge mode never duplicates: an incoming entry is skipped when its
idalready exists or when an existing entry matches it on item, counts-toward, name, quantity, unit, location and both dates. Re-importing your own backup therefore adds 0 entries. - The import UI previews the exact add/skip counts and waits for confirmation before anything changes. The preview is bound to the chosen file and the chosen mode: changing either one disarms Confirm until you preview again.
- Unknown fields are dropped on import. An entry with a bad name, category, quantity, or date rejects the whole import — a bad file changes nothing.
- Gap credit is freshness-aware: stock past its replace-by/expiry date is listed in rotation but does not count toward closing a gap.
Versioning
versionbumps only on a breaking change to this schema (a field removed, renamed, or changing meaning).- Importers reject unknown future versions (
versionother than1is an error) rather than guessing at a format they do not understand. - Additive, optional fields do not bump the version; old importers drop fields they do not know.
Example export
{
"kind": "getpreparedstuff-tracker",
"version": 1,
"exportedAt": "2026-11-18T00:00:00.000Z",
"profile": {
"adults": 2,
"children": 0,
"babies": 0,
"dogs": 0,
"cats": 0,
"medUsers": 0,
"targetTier": "wk2",
"housing": "own"
},
"inventory": [
{
"id": "entry-abc123",
"itemId": "stored-water",
"name": "Stored drinking water",
"category": "water",
"quantity": 15,
"unit": "gallon",
"location": "Garage",
"purchased": "2026-03-18",
"expires": null,
"custom": false,
"countsToward": null,
"countsFactor": null,
"notes": "",
"selfFilled": true
},
{
"id": "entry-def456",
"itemId": null,
"name": "Bottled water cases",
"category": "water",
"quantity": 2,
"unit": "cases",
"location": "Garage",
"purchased": "2026-09-01",
"expires": "2027-09-01",
"custom": true,
"countsToward": "stored-water",
"countsFactor": 5.28,
"notes": "",
"selfFilled": null
}
]
} Machine-readable schema
A JSON Schema (draft 2020-12) for this format is served at /tracker-export-schema.json — validate exports against it with any standard validator.
Format version 1, published Nov 18, 2026. The tracker's full documentation of storage keys and import behavior ships in the project repository (docs/tracker-data.md).