Build Specification

urn:showpapers:format:build-spec:4JSON Schema 2020-12Download JSON

Local tooling input for `create`; never stored inside an archive. The writer computes media types, paths, sizes, digests and the manifest, sets its own generator, and derives relationship ids. Paper, reading and note payloads are given inline as record or as a JSON source file (kept byte for byte).

Top Level

Member	Type	Rules
`formatVersion` required	`4`
`collection` required	collection
`agents`	array of agent	max items 32
`originals` required	array of originalSource	max items 100
`papers`	array of paperSource	max items 100
`readings`	array of readingSource	max items 100
`notes`	array of noteSource	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]*$

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]*$`

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

As in the manifest; id may be omitted and the writer derives it.

Member	Type	Rules
`id`	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"

source

string · min length 1; max length 4096; pattern ^(?!/)(?![\s\S]*(^|/)\.\.?(/|$))[^\\:]+$

originalSource

source: a regular file below the build-spec directory; its bytes become the original.

Member	Type	Rules
`id` required	id
`title` required	paperTitle
`source` required	source

paperSource

One of:

paperSource: variant 1

Member	Type	Rules
`id` required	id
`record` required	object	max members 16 A complete urn:showpapers:paper-record:1 object, validated by paper-record.schema.json.

paperSource: variant 2

Member	Type	Rules
`id` required	id
`source` required	source

readingSource

One of:

readingSource: variant 1

Member	Type	Rules
`id` required	id
`record` required	object	max members 8 A complete urn:showpapers:reading:1 object, validated by reading.schema.json.

readingSource: variant 2

Member	Type	Rules
`id` required	id
`source` required	source

noteSource

One of:

noteSource: variant 1

Member	Type	Rules
`id` required	id
`title` required	noteTitle
`record` required	object	max members 16 A complete urn:showpapers:scratch-record:1 object, validated by note-record.schema.json.

noteSource: variant 2

Member	Type	Rules
`id` required	id
`title` required	noteTitle
`source` required	source