documentation

Schemas, models and assistance

Writing the brief, picking a tier per project, and drafting a schema from a sentence.

# Schemas, models and assistance

The schema is not documentation of the output. It is the instruction.

## The schema is the brief

Every property you declare is a field the model is asked for. The `description` is what it
is told to look for, and `required` is what makes a missing value a failure instead of an
empty string.

```json
{
  "type": "object",
  "properties": {
    "vendor": { "type": "string", "description": "Merchant name" },
    "total": { "type": "number", "description": "Grand total" },
    "date": { "type": "string", "description": "Issue date, ISO 8601" }
  },
  "required": ["vendor", "total"]
}
```

Two rules that save the most time:

- **Write the description for a stranger.** "Grand total" is enough for a receipt. "Amount
  charged before tax" is not the same field, and saying so is the difference.
- **Declare only what the page has.** A field the document never carries becomes a
  violation on every read.

Up to 10 additional prompts of 500 characters each can be attached to a schema for the
instructions that do not fit in a description.

## Choosing a model

Each project picks one tier. The tiers differ in how hard a page they will read, not in the
contract they answer with: every tier validates against your schema.

| Tier       | Built for                                              | Watch for                        |
| ---------- | ------------------------------------------------------ | -------------------------------- |
| `fast`     | Clean scans, printed receipts, dense but regular forms | Handwriting, faded thermal paper |
| `balanced` | The default: mixed scans, phone photos, multi-column   | Very long documents              |
| `best`     | Dense or damaged pages, small print, stamps, tables    | Cost per read, slower turnaround |

Switching a tier does not change your schema, your credential or your existing results. It
changes what the next read costs and how much it can see.

## Assistance

Naming the fields is the slow part, not writing the JSON. Describe what you want in one
sentence such as _"vendor, total and issue date from a receipt"_, and the console drafts a
schema: named properties, types, descriptions, and the required list marked. You edit the
draft in the editor, not the other way round.

The draft is a starting point, never a decision: nothing is saved until you save it, and the
schema you commit is still the only thing the core is asked to honour.

## Where the schema lives

One schema per project, editable from the project page. Saving a new version takes effect on
the next read: no redeploy, no credential rotation, no re-indexing. Results already kept
stay as they were read, with the violations they were read with.