Schemas
Teach us how to read a class of document the same way every time. A schema names the fields, the validation rules, and the guidance, so every new invoice, purchase order, or quality report comes out shaped the same.
Audience: builders
Find the Schemas section
Open your Project. Click the Context tab. Pick Schemas. The header reads "Schemas" with a one-line note: "A schema teaches the system to read a class of document. Build it once, then it runs on every new one that comes in."
Empty state shows a single hero panel: "Pull structured data out of your team's documents." with a drop zone. Once you have schemas, the page shows a catalog with Name, Shape, Samples, Fields, Rules, Status, and Scope columns. A header above the catalog also accepts sample drops for drafting more schemas.
What a schema is
A schema is a JSON document with three required parts:
extraction_schema. A JSON-Schema-shaped object naming each field, its type, and whether it is required. This is what the agent fills in.prompt. Plain-language guidance for how to read this document type. Example: "Treat negative amounts as credits."rules. A list of validation sentences that must hold for an extraction to count as clean. Example: "The total equals the sum of line items."
Schemas can also carry field_suggestions (notes per field) and an extraction_config (provider-specific options). The shape badge on each row (Single table, Multi-table, Nested, or Schema) is computed from the fields.
Draft a schema from a sample
The fastest path is to hand the platform a real document and let it infer the fields.
Drop a sample
In the empty state or the Drop a sample to draft a schema strip above the catalog, drop a PDF, XLSX, DOCX, or image. The platform accepts one file at a time for inference.
Watch the analysis dock
A card appears with four steps: Reading your document, Looking for known patterns, Drafting a schema, Finalizing the schema. Each step shows elapsed seconds while it runs and "Done" when it lands. You can leave the page; analyses keep running server-side and reappear when you return.
Open the draft
When the card flips to Your schema is ready to review, click Open. The workbench opens with fields, rules, prompt, and guidance pre-filled from what was inferred.
Try it on the sample
Click Try on sample in the workbench bar. The right-hand result panel renders the structured extraction against the sample you dropped, so you can see what the schema produces before saving.
Save the draft
Click Save Draft. The schema is written to the Project's volume at .blockparty/schemas/<scope>/<slug>.json.
Author a schema by hand
Once at least one schema exists, New schema appears in the section header. It opens the same workbench with a blank draft. Edit fields in the Simple or Advanced view, write the prompt, add rules one sentence at a time, and Save Draft when ready.
Schema candidates from analyst corrections
When an analyst correction in chat surfaces a missing field or a needed rule, the platform proposes a schema candidate. Candidates appear in the catalog with Pending status and route through the same review flow as memory candidates.
Open a candidate row to inspect what would change. Approve the candidate (admin action) to promote it to a live schema. If you proposed the candidate, you can withdraw it from the drawer.
Direct write versus candidate. Whether Save Draft lands live or as a Pending candidate depends on your scope capabilities. The workbench picks the highest-write scope you have, then saves directly when you have direct authority and submits for review when you do not. The toast tells you which: "Saved as Draft" or "Submitted for review."
Use a schema in an App contract
A schema does real work when an App references it in its output contract. The contract names the slot, points at the schema, and the runbook fills the slot from each work item.
See App contracts for how to wire a schema into the contract, and how to keep slot keys stable across runbook republishes.
Versioning and supersession
Saves create a new version of the schema file in the volume. The path stays stable (.blockparty/schemas/<scope>/<slug>.json), so anything that references the schema by path picks up the latest version. Earlier work items keep their stored extractions intact; the schema change does not retroactively rewrite past results.
When a schema's shape changes in a way that would break consumers, supersede it: author a new schema with a new slug, point Apps and Data Collections at the new path, and retire the old one. The Audit ledger captures every save, approve, and delete.