> ## Documentation Index > Fetch the complete documentation index at: https://docs.matil.ai/llms.txt > Use this file to discover all available pages before exploring further. # Structures > Define the fields you want to extract from your documents. A **structure** is a schema that defines what data to extract from a document. You define the fields — name, type, description — and Matil reads the document and fills them in. Structures are the foundation of everything in Matil. Every deployment points to a structure. ## How it works 1. **Define a structure** in the [Matil Dashboard](https://admin.matil.ai). For example, an invoice structure might have fields like `invoice_number`, `invoice_date`, `total`, and `lines`. 2. **Publish a version.** Structures use a draft/publish workflow. Edit the draft, then publish when ready. 3. **Create a deployment** that points to that structure version. 4. **Send documents** via the API. Matil extracts the data and returns structured JSON. ## Example If your structure defines fields for an invoice, the extracted `data` in the response looks like: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "invoice_number": "INV-2024-001", "invoice_date": "2024-01-15", "currency": "EUR", "lines": [ { "description": "Consulting services", "quantity": 10, "unit_price": 125.00, "line_total": 1250.00 } ], "subtotal": 1250.00, "tax_amount": 262.50, "total": 1512.50 } ``` ## Pricing and pages Custom structures are billed at **0.10 € per page**. A "page" depends on the document type: | Document type | What counts as 1 page | | --------------- | -------------------------------------- | | **PDF** | 1 PDF page = 1 page | | **Image** | 1 image = 1 page | | **Text** | Every 200 words = 1 page (minimum 1) | | **Spreadsheet** | Every 1,500 cells = 1 page (minimum 1) | For example, a 3-page PDF costs 0.30 €. A spreadsheet with 4,500 cells counts as 3 pages (0.30 €). Marketplace structures have their own fixed price per page, shown on each structure's page in the [Marketplace](https://matil.ai/marketplace). ## Field types ### Data fields These are the fields that produce values in the output: | Type | Description | Output example | | ------------- | --------------------------------------------------------------------------- | ------------------------------------------ | | `text` | A single string value. Supports regex validation and allowed values (enum). | `"INV-2024-001"` | | `number` | A single numeric value. Supports decimal precision and rounding. | `1250.00` | | `boolean` | A true/false value. | `true` | | `list_text` | A list of strings. | `["EUR", "USD"]` | | `list_number` | A list of numbers. | `[10.0, 20.5]` | | `object` | A nested object with its own subfields. | `{"street": "...", "city": "..."}` | | `list_object` | A table — a list of rows, each with the same columns. | `[{"description": "...", "quantity": 10}]` | ### Structural fields These organize extraction but don't produce keys in the output: | Type | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `group` | Groups fields into an execution unit. Enables parallel extraction, conditional execution, and contextual instructions. Child fields are flattened to the parent namespace in the output. | | `structure` | References another structure's versioned definition. Its fields are flattened into the parent output. | | `validation` | An inline rule that verifies extracted data and can trigger automatic corrections or LLM retries. | ## Groups Groups let you organize fields into separate extraction units that can run **in parallel**, improving performance for complex structures. A structure with groups: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "fields": [ { "type": "group", "name": "header", "fields": [ { "type": "text", "name": "invoice_number", "description": "..." }, { "type": "text", "name": "currency", "description": "..." } ] }, { "type": "group", "name": "line_items", "instruction": "Extract line items. Currency is {/currency}.", "fields": [ { "type": "list_object", "name": "lines", "description": "...", "columns": [...] } ] } ] } ``` Produces a flat output — group names don't appear: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "invoice_number": "INV-001", "currency": "EUR", "lines": [...] } ``` Groups can also be **conditional** (skipped if an expression evaluates to false) and can include **instructions** with `{/path}` placeholders that reference data from other groups. ## Computed fields Any field can be marked as `is_computed: true`. Instead of being extracted by the LLM, its value is calculated from an expression after extraction. Useful for derived values like line totals. ## Validations Structures can include validation rules that verify extracted data. When a validation fails, it can trigger programmatic corrections (e.g., recalculate a field) or ask the LLM to re-extract specific fields. When a field fails validation, the response status is `completed_with_errors` and includes an `errors` array: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "errors": [ { "path": "/total", "message": "Required field missing", "code": "REQUIRED_FIELD" } ], "status": "completed_with_errors" } ``` | Status | Meaning | | ----------------------- | ----------------------------------------------------------------------------------- | | `completed` | All fields extracted and validated successfully. | | `completed_with_errors` | Extraction succeeded, but some fields failed validation. Partial data is available. | | `failed` | Processing could not complete. | ## Versioning Structures use a **draft/publish** workflow: * **Draft** — Your working copy. Edit freely without affecting live processing. * **Published version** — A snapshot that deployments can point to. Once published, a version is immutable. You can publish as many versions as you want. Each deployment chooses which version to use, so you can test a new version on a staging deployment before rolling it to production. ## Next steps Connect your structure to a deployment for API access. Understand how results are stored and how to correct them.