Schemas — Docs

Schemas

The contract between you and the engine: what data to extract.

A schema names the fields you want back and gives each a type. The type decides how the value is normalized and validated — which is why any schema gets the same guarantees without code of its own.

restaurant_order.json

{
  "name": "restaurant_order",
  "version": "1.0",
  "description": "Restaurant delivery order",
  "locale": "ar-JO",
  "fields": {
    "customerName": { "type": "person", "label": "Customer name", "required": true },
    "phone": {
      "type": "phone",
      "required": true,
      "validation": { "country": "JO" },
      "normalization": { "format": "international" }
    },
    "items": {
      "type": "array",
      "required": true,
      "items": {
        "type": "object",
        "fields": {
          "name":     { "type": "string", "required": true },
          "quantity": { "type": "integer", "required": true, "min": 1, "default": 1 }
        }
      }
    },
    "address": { "type": "address", "required": true },
    "notes":   { "type": "text" }
  }
}

Field properties

Property	Meaning
`type`	One of the field types. Required.
`label`, `description`	For people and for the model: the description tells the model what the field means.
`required`	Missing required fields are listed in `missingFields`, so your app knows what to ask.
`default`	Used when nothing was said; the field's status is `defaulted`.
`values` (or `enum`)	Enum options: strings, or `{value, label, synonyms}` for the words people use.
`min`, `max`, `pattern`	Value range (numbers), length (text) or number of entries (lists); a regular expression for strings and emails.
`validation`	Type-specific rules: `country` for phones, `currency` for money, `notBefore` for dates…
`normalization`	Output format: `format` for phones, `unit` for durations.
`requiresConfirmation`	Always ask a person to confirm this field (money does by default).
`examples`	Example values shown to the model as format hints.
`items` / `fields`	What one entry of a list is; the sub-fields of an object. Up to 3 levels.

A schema may also carry instructions (short wording rules for the model, per language) and worked examples (a transcript and the expected answer). Every worked example must pass validation against its own transcript, so the model is never taught to invent.

Creating schemas

In the dashboard: Create schema — a visual builder with a JSON view, live checks from the engine, and a Test button.
By API: POST /api/v1/schemas saves a version; POST /api/v1/schemas/validate checks one without saving. Errors come with paths such as fields.items.items.fields.quantity.min.
Inline: send the whole definition as schema in a parse request — useful for trying a draft; nothing is stored.

Built-in examples

delivery_order, restaurant_order, appointment_booking, field_service_request and hr_leave_request ship with the service to show the range. They are read-only and contain no special code — see Examples.