Replica document (GristReplicaDocument)

This page describes the canonical JSON document used across the SDK and emulator. Implementation types live in packages/core/src/sdk/replica-document.ts; consumer overview is in packages/core/README.md (Replica document).

Where it is used

• useGristSchema() — builds and filters a replica for the widget
• getDocumentJson / buildDocumentJson — serialize for LLMs or fixtures
• Playground and tests — *.grist.json (same content could use .replica.json)
• createGristEmulator({ document }) — validated with parseDocument (Zod)

Top-level fields

Field	Required	Notes
generatedAt	yes	ISO 8601 string
tables	yes	Record<tableId, GristReplicaTable>; keys match docApi.listTables() / fetchTable(tableId)
source	no	Provenance string (useGristSchema({ source }), buildReplicaDocumentFromDocApi(docApi, { source })); safe to log in the host
docName, mode, selection, …	no	See GristReplicaDocument in the core package

Optional mode: "schema-only" | "schema+samples" | "schema+data" (hint only). Use normalizeReplicaTableInput / normalizeReplicaDocumentInput from grist-widget-sdk so omitted rows matches [] at boundaries.

Tables and rows

• GristReplicaTable: optional label, columns, rows, rowCount, dataOmitted, error, …
• GristReplicaRow: { id: number, … } — not columnar fetchTable shape. Use buildReplicaDocumentFromDocApi or decodeColumnarToReplicaRows when converting from docApi.fetchTable.

Building and JSON export

• buildReplicaDocumentFromDocApi(docApi, { includeRows: false \| "samples" \| "full", sampleRowLimit, source, includeSystemTableData }) — primary standalone builder. With useGrist() (e.g. const w = useGrist()), call w.buildReplicaDocumentFromDocApi({ … }) — same options, no docApi argument. buildDocument is deprecated (maps legacy rowMode).
• getDocumentJson / buildDocumentJson: options include includeRows: "none" | "samples" | "full" and optional sampleRowLimit, space.

Emulator contract

The emulator accepts only a GristReplicaDocument: pass it to createGristEmulator({ document }). Use parseDocument on unknown JSON. There is no legacy fixture coercion; conversion helpers were removed—build a complete replica object first.