Collection carries everything a person authored, reviewed or organized in the apps: originals, paper records (type, details with origin, evidence, confidence and review, removed suggestions, people, built-in folder, reminder), readings, notes, personal folders with rules, people, relationships with decisions, pins and category icons, plus the external agents that proposed values. Optional sections may be omitted; an omitted array is empty and an omitted object is not described. The runtime also checks canonical paths, global ID uniqueness, reference resolution, digests, byte and capacity limits and the rules stated in each $comment.
Top Level
| Member | Type | Rules |
|---|---|---|
format required | "showpapers" | |
formatVersion required | 4 | |
protection required | "readable" | |
generator required | generator | |
collection required | collection | |
agents | array of agent | max items 32 |
originals required | array of original | max items 100 |
papers | array of paperEntry | max items 100 |
readings | array of readingEntry | max items 100 |
notes | array of note | max items 100 |
folders | array of folder | max items 64 |
people | array of person | max items 64 |
relationships | array of relationship | max items 5000 |
library | library |
Definitions
id
string · pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
sha256
string · pattern ^[a-f0-9]{64}$
collectionTitle
string · min length 1; max length 200; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]+$
paperTitle
Unicode scalars. The apps' native title rule: trimmed, no control characters, no '/' or '\\'.
string · min length 1; max length 100; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff/\\]+$
noteTitle
Collection: edge whitespace kept, at least one non-whitespace scalar.
string · min length 1; max length 160; pattern ^[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]*[^\s\u0000-\u001f\u007f-\u009f\ud800-\udfff][^\u0000-\u001f\u007f-\u009f\ud800-\udfff]*$
generator
The program that wrote this file, not a signature. Apps write {"name":"ShowPapers","platform":"android"|"ios","version":<app version>}.
| Member | Type | Rules |
|---|---|---|
name required | string | min length 1; max length 80; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]+$ |
platform required | string | min length 1; max length 40; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]+$ |
version required | string | min length 1; max length 40; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]+$ |
collection
| Member | Type | Rules |
|---|---|---|
id required | id | |
revision required | integer | min 1; max 9007199254740991 |
title required | collectionTitle | |
parent | object | closed The exact archive this revision was edited from. Optional; parent.revision is lower than revision. |
agent
An external AI agent that proposed values in this file. Agent-origin values reference it by id and stay pending until the person reviews them.
| Member | Type | Rules |
|---|---|---|
id required | id | |
name required | string | min length 1; max length 80; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]+$ |
platform required | string | min length 0; max length 40; pattern ^[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]*$ |
version required | string | min length 0; max length 40; pattern ^[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]*$ |
original
| Member | Type | Rules |
|---|---|---|
id required | id | |
title required | paperTitle | |
path required | string | pattern ^originals/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(pdf|png|jpg|webp)$ |
size required | integer | min 1; max 20971520 |
sha256 required | sha256 | |
mediaType required | one of "application/pdf", "image/png", "image/jpeg", "image/webp" |
paperEntry
papers/<id>.json holds urn:showpapers:paper-record:1 for the original with the same id.
| Member | Type | Rules |
|---|---|---|
id required | id | |
path required | string | pattern ^papers/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$ |
size required | integer | min 1; max 1048576 |
sha256 required | sha256 |
readingEntry
readings/<id>.json holds urn:showpapers:reading:1 for the original with the same id.
| Member | Type | Rules |
|---|---|---|
id required | id | |
path required | string | pattern ^readings/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$ |
size required | integer | min 1; max 8388608 |
sha256 required | sha256 |
note
Payload is the Collection note record (urn:showpapers:scratch-record:1); paperIds is its first-occurrence reference union.
| Member | Type | Rules |
|---|---|---|
id required | id | |
title required | noteTitle | |
path required | string | pattern ^notes/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$ |
size required | integer | min 1; max 524288 |
sha256 required | sha256 | |
encoding required | "utf-8" | |
paperIds required | array of id | max items 100; unique |
rule
Automatic filing. autoAdd needs at least one document type. Clause fields are distinct; only the six date fields accept operators other than equals, and their values are ISO dates.
| Member | Type | Rules |
|---|---|---|
documentTypes required | array of one of "evidence.identity.foreign-passport", "state.issued.us-passport", "state.issued.visa-foil", "cbp.record.i-94", "ice.sevp.issued.i-20", "uscis.issued.i-551", "uscis.issued.i-766", "uscis.notice.i-797", "uscis.notice.i-797a", "uscis.notice.i-797b", "uscis.notice.i-797c" | max items 11; unique |
autoAdd required | boolean | |
excludedPaperIds required | array of id | max items 100; unique |
condition required | null or object or object |
folder
A personal folder. Array order is the folder order. Folders hold papers only. Names are unique ignoring case and are limited in UTF-16 units, like the apps.
| Member | Type | Rules |
|---|---|---|
id required | id | |
name required | string | min length 1; max length 80; max UTF-16 units 80; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]+$ |
color required | one of "blue", "teal", "green", "amber", "coral", "purple", "gray" | |
icon required | null or one of "folder", "paper", "passport", "identity", "travel", "study", "work", "receipt", "shield", "people", "home", "checklist", "appointment" | |
purpose required | string | min length 0; max length 240; max UTF-16 units 240; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]*$ |
rule required | null or rule | |
paperIds required | array of id | max items 100; unique |
person
Names are unique ignoring case; at most one person is the owner (isMe).
| Member | Type | Rules |
|---|---|---|
id required | id | |
name required | string | min length 1; max length 80; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]+$ |
isMe required | boolean |
relationship
Undirected pair (paperIds sorted ascending) with an optional referring paper for direction. id is derived: UUID.nameUUIDFromBytes(UTF-8 of 'showpapers:relationship:1:' + paperIds[0] + ':' + paperIds[1] + ':' + type). accept implies confirmed; reject implies rejected; agent origin needs agentId.
| Member | Type | Rules |
|---|---|---|
id required | id | |
type required | one of "same-case", "different-stage", "same-person", "same-record", "same-organization", "supporting-document", "renewal", "amendment", "subsequent-filing", "duplicate", "alternate-version" | |
paperIds required | array of id | min items 2; max items 2; unique |
referringPaperId required | null or id | |
status required | one of "suggested", "confirmed", "rejected" | |
origin required | one of "reading", "person", "agent" | |
agentId required | null or id | |
reasons required | array of string | max items 16 |
decision required | null or object |
categoryIcon
Icon chosen for a category group. label is the custom type for purpose custom, otherwise null.
| Member | Type | Rules |
|---|---|---|
purpose required | one of "identity", "admission", "approvals-and-receipts", "study", "work-permission", "personal-records", "tax", "insurance", "custom", "unknown" | |
label required | null or label | |
icon required | one of "folder", "paper", "passport", "identity", "travel", "study", "work", "receipt", "shield", "people", "home", "checklist", "appointment" |
library
| Member | Type | Rules |
|---|---|---|
pinnedPaperIds required | array of id | max items 100; unique |
categoryIcons required | array of categoryIcon | max items 64 |
label
string · min length 1; max length 80; pattern ^(?![ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000])(?![\s\S]*[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]$)[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]+$
icon
one of "folder", "paper", "passport", "identity", "travel", "study", "work", "receipt", "shield", "people", "home", "checklist", "appointment"