An extraction template lists, in YAML, the fields you want taken from a document.

**Extraction through the connector is coming soon.** You can already write templates and keep them on the dashboard's Templates page, but no tool or endpoint uses your saved templates yet.

## Format

A template is a YAML mapping with a list of fields:

| Key | Required | What it holds |
| --- | --- | --- |
| `name` | No | A name for the template. |
| `description` | No | The kind of document it is for. |
| `fields` | Yes | The fields to extract, at least one. |

Each field has these keys:

| Key | Required | What it holds |
| --- | --- | --- |
| `name` | Yes | The field's name. |
| `type` | Yes | One of `string`, `integer`, `float`, `boolean`, `date`, `list[string]` and `list[object]`. |
| `description` | No | What the field holds, in a few words. |
| `required` | No | `true` (the default) or `false`. |
| `children` | No | For a `list[object]` field, the fields of each object, written the same way. |

A short template:

```yaml
name: receipt
description: Shop receipt
fields:
  - name: shop
    type: string
  - name: date
    type: date
  - name: items
    type: list[object]
    children:
      - name: item
        type: string
      - name: price
        type: float
  - name: total
    type: float
```

## Saving a template

On the dashboard's Templates page, give the template a name and an optional description, and paste its YAML. mdfi checks the YAML when you save it and shows what is wrong:

| Message | What is wrong |
| --- | --- |
| `Invalid YAML: <reason>` | The text is not valid YAML. |
| `A template must be a YAML mapping with a 'fields' list` | The YAML is empty, or is not a mapping of keys to values. |
| `A template needs at least one field` | `fields` is missing or empty. |
| `Invalid template: <reason>` | A field has no `name` or `type`, or its `type` is not one of the types above. |
| `Anchors and aliases are not supported in templates` | The YAML uses `&anchor` or `*alias`. Write each part out in full. |

The YAML can be up to 65,536 characters, the name up to 255 and the description up to 500. Templates can be edited and deleted from the same page.

The number of templates you can keep depends on your plan: 5 on Starter, 50 on Pro and no limit on Enterprise ([Pricing](pricing.md)). At the limit, saving another one answers `Template limit reached (5 for Starter plan). Upgrade to create more.`

## Built-in examples

mdfi comes with five example templates. **Start from example** on the Templates page copies one into your templates, under the example's name, and the copy counts toward your plan's limit.

| Example | For |
| --- | --- |
| `contract` | Contract or agreement with parties, terms, and obligations |
| `invoice` | Invoice with vendor info, line items, and totals |
| `meeting_notes` | Meeting notes with attendees, decisions, and action items |
| `research_paper` | Academic or research paper with structured sections |
| `resume` | Resume or CV with experience, education, and skills |

The `invoice` example in full:

```yaml
name: invoice
description: Invoice with vendor info, line items, and totals
fields:
  - name: vendor
    type: string
    description: Vendor or company name
  - name: invoice_number
    type: string
    description: Invoice number or reference ID
  - name: date
    type: date
    description: Invoice date
  - name: due_date
    type: date
    description: Payment due date
    required: false
  - name: bill_to
    type: string
    description: Billing recipient name or company
    required: false
  - name: line_items
    type: list[object]
    description: Individual line items
    children:
      - name: description
        type: string
        description: Item description
      - name: quantity
        type: float
        description: Quantity
        required: false
      - name: unit_price
        type: float
        description: Price per unit
        required: false
      - name: amount
        type: float
        description: Line item total
  - name: subtotal
    type: float
    description: Subtotal before tax
    required: false
  - name: tax
    type: float
    description: Tax amount
    required: false
  - name: total
    type: float
    description: Total amount due
```

## Coming soon

- Extraction with your saved templates through the connector.
- A `/v1/templates` API ([API](api.md#templates-coming-soon)).

The older `/convert`, `/jobs` and `/batches` endpoints can already apply one of the built-in examples by name, with `schema=invoice`; they do not use your saved templates. [API](api.md#older-endpoints) has the details.