Collections & schema

In one line. What a Collection is in practice, how to create one, and how to give it a schema — the fields the platform will extract from every document. You’ll be able to. Create a Processing collection from scratch and define its fields, ready for documents to flow in. Where this lives. Studio ▸ Data Model ▸ Collections

Why it matters

A Collection is the operational home for one type of record — “Vendor Invoices”, “HR Policies”, “Support Tickets”. Everything downstream hangs off it: documents land in a collection, an agent works it, your end-users read it. And before any of that, you give it a schema — the list of fields the platform pulls out of each document. The schema is the single most important thing you author here, because the schema drives extraction: the platform’s extraction agents read your field list to know what to pull out. No field, no extracted value.

Vocabulary. The UI says Collection; the API/URL still say Entity / RelationalEntity / EntityId. A Learner (a.k.a. Taxonomy / Data Capture group) is the trainable extractor that owns a group of fields. A Label is one field (the UI shows it as a Field). A Schema = “a Learner plus its Labels” — not a separate object. Keep the Glossary open.

Every collection sits on two independent axes:

Category — why it exists: Processing (decide on each document — review stages, field extraction, an agent acts on each one) or Knowledge (a passive corpus, auto-indexed so agents can read and cite it). The categories have a dedicated page: Collection types.
Kind — who works it: Agent (an AI agent processes it) or Human (a person’s work queue, like the Inbox).

Status. The explicit Knowledge category, its auto-vectorise-on-ingest behaviour, and the Index Health tab are shipped release features behind the knowledgeCollections flag (default on; environments can switch it off as a kill-switch, which hides every Knowledge surface). Processing collections need no flag — that is what the walkthrough below builds.

The Collections workspace

Menu path: Studio ▸ Data Model ▸ Collections.

This is a master-detail surface: a list of every collection on the left, and a detail pane on the right that shows the selected collection’s seven (or eight) tabs.

Left rail lists collections by name. Parent/child collections are shown as indented nesting (a child sits under its parent, with a coloured left border by depth). A star marks the Primary/Default collection — the project’s default ingestion target. Click a row to load it on the right.
Right pane shows the selected collection’s name, a row-action menu, and the tab strip.

What every control does

Control	What it does	Notes
+ Collection (rail footer)	Opens the Create Collection modal	Always present, even when the list is empty. Backend still enforces create permission.
Row ⋮ ▸ Edit	Re-opens the collection in the editor	Hidden when the `collectionsUnified` flag is on — there the General tab is the editor.
Row ⋮ ▸ Delete	Deletes the collection (confirm)	Flag `collectionWorkbench`. Warns by name if the collection has child collections.
+ Taxonomy (pane header)	Opens Create Taxonomy scoped to the selected collection	A shortcut to add a Learner without opening the Schema tab first.
Empty state	“No Collection found in the project” + + Collection	Shown before you create your first.

Tip — deep-links. A consumer “Edit in Studio” link arrives as …?selectedEntityId=<id> and pre-selects that collection for you. You don’t need to hunt for it in the list.

Flag-gated layout. With collectionWorkbench on, the right pane is the tabbed workbench described below. With it off, you get a flat, read-only details panel instead (EntityName, Description, copyable EntityId, created/updated by + date, an IsPrimary toggle, and Independent-Queue status). This page teaches the tabbed workbench.

The right-pane tabs — what each one is and where it’s covered

The detail pane embeds seven tabs (eight for Knowledge collections). Each non-General tab is the exact same page you can also reach as a standalone model_data/* route — here they’re just mounted inline.

Tab	What it’s for	Covered in
General	The collection’s settings — this is also the create/edit form	This page, below
Schema	Define the fields to extract (Learners + Labels)	This page
Lifecycle	The review stages documents move through	Taxonomy, lifecycle, tags & events
Tags	The project’s free-form tag set applied to records	Taxonomy, lifecycle, tags & events
Events	Webhooks / emails / Slack fired on document or stage events	Taxonomy, lifecycle, tags & events
Ingestion	Where this collection’s documents come from	Ingestion & connectors
Agents	Assign the Worker (Intake Agent) and watch it run	Your first agent
Index Health	Vectorisation health, per-cause failure groups, retries and reindex — Knowledge collections only	Search, indexes & vectorization

Two agent-collection relationships. A Worker (the Intake Agent) runs on each document — you set it on the Agents tab. A Reader searches the collection’s index — you set that on the Knowledge tab in Agent Builder, not here. Don’t confuse the two.

Creating a collection — the General tab

Click + Collection (or open the General tab of an existing one). The same form serves as both Create and Edit, and as the inline General tab. Save is disabled while the form is invalid; in modal mode a Close button appears.

You only need four decisions to get a working Processing collection — the rest are optional accordions with sensible defaults.

The key settings groups (summary)

Group	What you set	Required?
Purpose	The collection category — Processing, Knowledge, or Structured (see Collection types; picker behind flag `knowledgeCollections`). Immutable after create (shown as a read-only chip on edit).	Pick one
Knowledge settings	Search model (the embedding model — required; the first available model is preselected on create and Save is blocked without one), chunk size (default 2000), chunk overlap (default 10). An Advanced ingestion settings foldout adds Index location (Shared vs Project index), page/document summaries, and OCR for scans. Expanded by default on create. Only when Purpose = Knowledge.	Pick the Search model
Collection Name	The display name	Yes
Description	What it holds	Yes
Allowed Ingestion Types	Whitelist which source types may feed this collection (Upload, Cloud, connectors, Form Templates)	Optional
Default View	A starting column view (only if any exist)	Optional
Parent Collection	Make this a child of another collection — reveals label-mapping accordions. Disabled once set (no re-parenting).	Optional
Enrich / Dashboards / Independent Queue	Advanced accordions (enrich-xflow triggers, per-collection dashboards, dedicated queue)	Optional
Set as Primary	Make this the project’s default ingestion target (exactly one per project)	Optional

The full field-by-field table — every accordion, every child-mapping row, every default — is in the Schema field reference.

Watch out — Category is permanent. You choose Processing or Knowledge once, at create time. After that it shows as a read-only chip and cannot be changed. Pick deliberately.

Under the hood — where intake assignment lives. There used to be an “Assign to” / Intake-Agent picker on this form. It was removed — you now pick the working agent on the Agents tab (Your first agent). So the create form defines the shape and the rules; the Agents tab assigns the worker.

The Schema tab — defining what to extract

This is the heart of the page. Menu path: select a collection, then Schema (or standalone model_data/taxonomy).

How schema drives extraction

When a document arrives, the platform’s extraction agents look at the collection’s schema and extract a value for each Label. A Label called invoice_total (with a currency validation) tells the agent “find the total and pull it out as money.” Remove the Label and that value is simply never captured. So authoring the schema is authoring the extraction. (For a child collection, a parent’s extracted Labels can auto-derive the child’s records via label mapping — see Taxonomy, lifecycle, tags & events.)

A schema is a small tree:

Learner (a.k.a. Taxonomy / Data Capture) — the trainable extractor on the collection
- Label (UI: “Field”) — one extractable value: a name plus behaviour
  - child Label — a column, when the parent Label is a table/record

Layout — master-detail

┌──────────────────────────────┐ ┌──────────────────────────────────────────────┐
│ Taxonomy   [type ▾] [search]  │ │  Invoice Header        [+ Label]   [⋮ Edit]   │
│ ──────────────────────────── │ │  Labels | Details                              │
│  * Invoice Header (primary)   │ │  ─────────                                     │
│    Invoice Line Items         │ │   invoice_number      text                     │
│                               │ │   invoice_date        date                     │
│                               │ │   total_amount        currency                 │
│  ──────────────────────────  │ │   line_items          ▸ table (3 child fields)  │
│  [ Taxonomy ]  [ Import ]     │ │                                                │
└──────────────────────────────┘ └──────────────────────────────────────────────┘

Left list — every Learner (Name + Description); a star marks the Primary Learner. A type filter (All · Custom · Default · Imported) and a search icon narrow the list.
Footer — Taxonomy (create a new Learner) and Import (import a Learner). Empty state: “No Taxonomies found. Create new Taxonomy.”
Right pane (a Learner selected) — + Label (top-right, on the Labels sub-tab) and an action menu with Edit (edit the Learner). Two sub-tabs: Labels (a hierarchical field tree) and Details (the Learner’s metadata).

Control	What it does
Taxonomy (footer)	Opens Create Taxonomy — defines a new Learner (the field group)
Import (footer)	Imports a Learner from a bottom-sheet
type ▾ filter	Filters the Learner list: All / Custom / Default / Imported
+ Label	Opens the field editor (add a field to the selected Learner)
⋮ ▸ Edit	Edits the selected Learner

Adding a Learner (Create Taxonomy)

A Learner groups the fields and is the thing that can be trained later. To create one, click Taxonomy and fill:

Field	Notes
Taxonomy Name (required)	Non-empty; duplicate names rejected
Description (required)
Type (required)	What it classifies/extracts — for whole-document field extraction pick DocumentClassification
Entity (required)	Which collection it belongs to (pre-filled to the one you’re on)

The full list of Learner Types (DocumentClassification, TableClassification, ImageAnnotation, and more) is in the Schema field reference.

Adding a Field (Label) — the field editor

Select a Learner, then + Label. The editor has two tabs — Add label and Import labels.

Label Name and Description are the only required inputs — and for most fields they’re all you need.
Show Advanced Settings reveals six accordions (summarised below).
Add saves the field and keeps the dialog open (handy for entering several in a row); Add and exit saves and closes.

Field types — how a Label becomes text, number, currency, date, boolean or a table

There is no single “type” dropdown. A field’s shape comes from a combination of a validation rule (in View Config) and Record Config. In practice you produce these shapes:

Shape	How you get it
Text	A Label with no special validation (the default)
Number	Label + a numeric validation rule (View Config ▸ Validation)
Currency / amount	Numeric validation, optionally Enable Total Field
Date	A date validation rule
Boolean / yes-no	A validation rule limiting to two values
Single-select / enum	A validation rule listing allowed values
Table / line-items	Is Record (Record Config) + child Labels as columns
Masked / sensitive	Mask Values toggle (Toggles)

Tip. 90% of fields are “a Label + a validation rule.” The one shape that’s different is a table/line-items field: turn on Is Record, then add child Labels — each child becomes a column.

The exhaustive enumeration of every shape and every validation option is in the Schema field reference.

The six advanced accordions (summary)

You’ll rarely need these for a first build — here’s what each is for. The full control-by-control list is in the Schema field reference.

Accordion	In one line
Table Styling	Header/body background and text colours for a table field
Contextual Insights	Real-time derivation (RTD) and aggregation widgets
Record Config	Make the field a table (Is Record), define columns, grouping, widths
Toggles / Features	Mask Values, Expand Label Values, Enrich Label
Lookup Config	Derive/refresh a value from another label or source
View Config	Validation rules (this is where number/date/boolean/enum live), sort, totals

Bulk import of fields

The Import labels tab takes .txt, .xlsx, .tsv or .csv. Parent/child nesting is expressed by indentation (text) or columns (spreadsheet), so you can stand up a whole table-with-columns in one go, then Upload & Create.

Tip. For a large schema, build the field list in a spreadsheet first (one column per nesting level) and import it — far faster than clicking + Label dozens of times.

Behaviours to know

Required fields: Learner Name + Description; Label Name + Description. Save/Submit/Add stay disabled until they’re filled.
Duplicate names are rejected (Learner level).
The Schema tab and the standalone model_data/taxonomy route are the same surface — edits in one are edits in the collection.

Try it yourself

Build a Vendor Invoices Processing collection with four fields. (~5 minutes.)

Go to Studio ▸ Data Model ▸ Collections. Click + Collection.
Purpose: leave/select Processing. Collection Name: Vendor Invoices. Description: Incoming supplier invoices for approval. Leave everything else default. Click Save.
Your collection appears in the left rail. Select it, open the Schema tab.
Click Taxonomy. Name: Invoice Header, Description: Top-level invoice fields, Type: DocumentClassification, Entity: Vendor Invoices. Submit.
Select Invoice Header, click + Label. Add these four, using Add between each and Add and exit on the last:
- invoice_number — Description: The supplier's invoice number. (Plain text — no advanced settings.)
- invoice_date — open View Config, add a date validation rule.
- vendor_name — plain text.
- total_amount — open View Config, add a numeric validation rule (currency).
Confirm all four show in the Labels tree under Invoice Header.

You now have a Processing collection whose extraction agent knows to pull four fields from every invoice. In Ingestion & connectors you’ll feed it documents; in Your first agent you’ll assign the agent that extracts them. The full end-to-end build is Invoice processing.

Bonus. Add a fifth field line_items as a table: in the editor open Record Config, turn on Is Record, then add child Labels description, quantity, unit_price as its columns.

Recap

A Collection is the typed home for one kind of record, at Studio ▸ Data Model ▸ Collections — a master-detail workspace (collection rail + tabbed detail pane).
Create one from + Collection / the General tab: pick Processing vs Knowledge (flag knowledgeCollections, immutable after create), name it, describe it. Everything else is optional accordions with defaults.
The detail pane has up to eight tabs: General + Schema (this page), Lifecycle / Tags / Events, Ingestion, Agents, and Index Health (Knowledge collections only).
The Schema tab defines Learners (field groups) and Labels (fields). Schema drives extraction — the agent extracts exactly the Labels you define.
A field’s type comes from its validation rule + Record Config, not a single dropdown. Tables use Is Record + child Labels. Import labels stands up a big schema fast.

Where to go next

Taxonomy, lifecycle, tags & events — the other Data-Model tabs: review stages, tags, and webhooks.
Ingestion & connectors — get documents into your new collection.
Your first agent — assign the Worker that extracts your fields (the Agents tab).
Invoice processing — this collection, built end to end.