Changes Document

urn:showpapers:changes:1JSON Schema 2020-12Download JSON

What an AI app hands back when it cannot write a .showpapers file: proposed changes to one collection, made against the exact archive in base (from the archive or a companion). Every change is a proposal: the app shows each one for review, marks values as coming from the generator, and applies only what the person accepts. Nothing is deleted or confirmed without the person. Recognize it by schema == urn:showpapers:changes:1. The reference tool applies a changes document to its base archive and writes a new Collection file.

Top Level

Member	Type	Rules
`schema` required	`"urn:showpapers:changes:1"`
`base` required	object	closed
`generator` required	generator
`summary` required	string	min length 0; max length 500; pattern `^[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]*$`
`changes` required	array of change	min items 1; max items 500

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

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]+$

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

icon

one of "folder", "paper", "passport", "identity", "travel", "study", "work", "receipt", "shield", "people", "home", "checklist", "appointment"

unit

number · min 0; max 1

kind

one of "generic", "i20", "i94", "passport", "visa", "i797", "employment-authorization", "drivers-license", "social-security", "birth-certificate", "marriage-certificate", "tax", "insurance"

fieldKey

one of "program-start-date", "program-end-date", "sevis-id", "admission-date", "admit-until", "class-of-admission", "admission-record-number", "given-name", "family-name", "date-of-birth", "country-of-birth", "country-of-citizenship", "nationality", "document-number", "passport-number", "issuing-country", "issue-date", "expiration-date", "place-of-birth", "sex", "full-name", "receipt-number", "case-type", "notice-type" … (78 values)

valueType

one of "text", "date", "duration-of-status"

isoDate

string · min length 10; max length 10; pattern ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$

region

Normalized to the rendered page (0..1). box is [left, top, right, bottom] with left <= right and top <= bottom.

Member	Type	Rules
`box` required	null or array of unit
`polygon` required	array of array of unit	max items 8

evidence

One of:

evidence: variant 1

A line of this paper's reading (readings/<id>.json must exist and contain it).

Member	Type	Rules
`page` required	integer	min 0; max 199
`block` required	integer	min 0; max 1999
`line` required	integer	min 0; max 9999

evidence: variant 2

Text quoted from the original page by an external agent, with an optional location. Not an OCR line.

Member	Type	Rules
`page` required	integer	min 0; max 199
`quote` required	string	min length 1; max length 8192; pattern `^[^\u0000-\u0008\u000b-\u001f\u007f-\u009f\ud800-\udfff]*$`
`region` required	null or region

changeDetail

A proposed detail. It arrives with origin agent and stays pending until the person reviews it. label is required for key other.

Member	Type	Rules
`id` required	id
`key` required	fieldKey
`label` required	null or label
`value` required	string	min length 1; max length 4096
`normalizedValue` required	null or string
`valueType` required	valueType
`confidence` required	null or unit
`evidence` required	array of evidence	max items 16

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

reminder

source detail names a date detail of this paper with one of the keys expiration-date, valid-until, program-end-date, admit-until, coverage-end-date; source date has detailId null.

Member	Type	Rules
`source` required	one of `"detail"`, `"date"`
`detailId` required	null or string
`date` required	isoDate
`leadDays` required	one of `7`, `14`, `30`
`enabled` required	boolean

change

One of:

change: collection.rename

Rename the collection.

Member	Type	Rules
`op` required	`"collection.rename"`
`title` required	collectionTitle

change: paper.rename

Propose a new paper title.

Member	Type	Rules
`op` required	`"paper.rename"`
`paperId` required	id
`title` required	paperTitle

change: paper.setType

Propose a paper type. custom only with kind generic. Stored as the paper's type.agentSuggestion.

Member	Type	Rules
`op` required	`"paper.setType"`
`paperId` required	id
`kind` required	kind
`custom` required	null or label
`confidence` required	null or unit

change: paper.setPeople

Replace the people assigned to a paper.

Member	Type	Rules
`op` required	`"paper.setPeople"`
`paperId` required	id
`personIds` required	array of id	max items 64; unique

change: paper.setBuiltInFolder

Place a paper in a built-in folder (null: automatic).

Member	Type	Rules
`op` required	`"paper.setBuiltInFolder"`
`paperId` required	id
`builtInFolder` required	null or one of `"identity"`, `"visas"`, `"notices"`, `"applications"`, `"residency"`, `"work-authorization"`, `"travel-entry"`, `"study"`, `"home"`, `"finance"`, `"health"`, `"education"`, `"work"`, `"family"`, `"legal"`, `"other"`

change: paper.setReminder

Set or clear a paper's reminder.

Member	Type	Rules
`op` required	`"paper.setReminder"`
`paperId` required	id
`reminder` required	null or reminder

change: paper.pin

Pin a paper (appended to the pinned order).

Member	Type	Rules
`op` required	`"paper.pin"`
`paperId` required	id

change: paper.unpin

Unpin a paper.

Member	Type	Rules
`op` required	`"paper.unpin"`
`paperId` required	id

change: detail.add

Propose a new detail.

Member	Type	Rules
`op` required	`"detail.add"`
`paperId` required	id
`detail` required	changeDetail

change: detail.remove

Propose removing a detail.

Member	Type	Rules
`op` required	`"detail.remove"`
`paperId` required	id
`detailId` required	string	min length 1; max length 96

change: person.add

Add a person.

Member	Type	Rules
`op` required	`"person.add"`
`person` required	person

change: person.rename

Rename a person.

Member	Type	Rules
`op` required	`"person.rename"`
`personId` 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]+$`

change: person.remove

Remove a person and their paper assignments.

Member	Type	Rules
`op` required	`"person.remove"`
`personId` required	id

change: folder.add

Add a personal folder at the end.

Member	Type	Rules
`op` required	`"folder.add"`
`folder` required	folder

change: folder.update

Change the listed folder fields; omitted fields stay unchanged.

Member	Type	Rules
`op` required	`"folder.update"`
`folderId` required	id
`name`	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`	one of `"blue"`, `"teal"`, `"green"`, `"amber"`, `"coral"`, `"purple"`, `"gray"`
`icon`	null or one of `"folder"`, `"paper"`, `"passport"`, `"identity"`, `"travel"`, `"study"`, `"work"`, `"receipt"`, `"shield"`, `"people"`, `"home"`, `"checklist"`, `"appointment"`
`purpose`	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`	null or rule

change: folder.remove

Remove a folder; its papers stay.

Member	Type	Rules
`op` required	`"folder.remove"`
`folderId` required	id

change: folder.addPapers

Add papers to a folder.

Member	Type	Rules
`op` required	`"folder.addPapers"`
`folderId` required	id
`paperIds` required	array of id	min items 1; max items 100; unique

change: folder.removePapers

Remove papers from a folder.

Member	Type	Rules
`op` required	`"folder.removePapers"`
`folderId` required	id
`paperIds` required	array of id	min items 1; max items 100; unique

change: note.add

Add a note.

Member	Type	Rules
`op` required	`"note.add"`
`noteId` required	id
`title` required	noteTitle
`record` required	object	max members 16 A complete urn:showpapers:scratch-record:1 object.

change: note.replace

Replace a note's title and complete record.

Member	Type	Rules
`op` required	`"note.replace"`
`noteId` required	id
`title` required	noteTitle
`record` required	object	max members 16 A complete urn:showpapers:scratch-record:1 object; carry forward every unchanged row and field.

change: note.remove

Remove a note.

Member	Type	Rules
`op` required	`"note.remove"`
`noteId` required	id

change: relationship.add

Suggest that two papers are related. It arrives as a suggested relationship with origin agent.

Member	Type	Rules
`op` required	`"relationship.add"`
`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
`reason` required	string	min length 0; max length 500; pattern `^[^\u0000-\u001f\u007f-\u009f\ud800-\udfff]*$`

change: relationship.remove

Propose removing a relationship.

Member	Type	Rules
`op` required	`"relationship.remove"`
`relationshipId` required	id