Grist integration

Grist combines typed columns generated from locally loaded manifests with a read-only JSON fallback containing every extension envelope.

Inspect the schema for the configured node with:

birdd --config birdd.toml grist-schema

Without configured manifests, the schema contains no extension-specific columns.

Projected columns

Each [[projected_fields]] declaration maps one top-level extension data key to a Grist column. For example, the optional bird manifests generate:

These are examples, not built-in columns. Column IDs are derived deterministically from the extension ID and JSON key as described in Authoring extensions.

Projection fails closed. A projected cell is null when:

• The envelope is absent
• Its version is not supported by the local manifest
• Its value does not match the declared Grist type

Text requires a JSON string. Int requires a non-negative integer that fits in a u32.

Extensions JSON

Extensions JSON contains the canonical JSON representation of the complete extension map, including supported envelopes, unsupported versions, unknown extension IDs, and keys without projected columns.

The column is read-only. Editing it does not update an observation. Add an editable projected field when a key needs a typed Grist edit path.

Creation and editing semantics

Editable projected cells in a new Our_Observations row create extension envelopes. Birdd uses the first version in the manifest’s ascending supported_versions list. Blank projected cells do not create keys, and an extension with no populated keys is omitted.

For an existing local observation, changing an editable projected cell creates a signed correction. Setting a cell to null removes only that JSON key. Birdd clones the complete extension map before editing, preserving unknown keys and unrelated envelopes.

If an existing envelope uses an unsupported version, Birdd ignores projected edits to it rather than rewriting data it cannot interpret. Remote observations in Following_Remote remain read-only.

These rules describe extension conversion. General row creation, deletion, stale revisions, and table usage are documented in Using Grist.

Webhook requirements

The managed webhook watches core editable columns and extension columns marked editable. A no-op edit creates no event, and stale revisions are rejected.

Handling corrections requires the webhook secret. Supporting new-row creation also requires grist.base_url, grist.document_id, and grist.api_key because Birdd writes the generated observation ID, revision, canonical extension JSON, and sync status back to the row after recording the observation.

Schema changes

Changing the loaded manifest set changes the deterministic Grist schema. After deploying manifests and restarting the relevant process, run birdd grist-provision to apply additive changes:

• Missing tables and columns are created.
• Changed column labels are updated.
• Existing columns with incompatible types stop provisioning.
• Extra tables and columns are retained.
• The managed webhook’s watched columns are updated.

Removing a manifest does not delete old Grist columns or stored envelope data. The columns are no longer managed by the generated schema.

Test generated IDs and forward/reverse conversion before editors use a changed field. Run reconciliation after successful provisioning.