# Definition format

Every field of a Definition and of each kind of question, with its type, its limits and an example.

A Definition describes a Decision: the input each call sends, the context it reads and the questions it answers, all in one call to one pinned model. You write it in YAML or JSON; the two say the same thing.

This page lists every field TypeFuse checks, with its type, its limits and the sentence you see when one is broken.

- [Decisions and Definitions](https://typefuse.dev/guides/decisions)
- [Per-item questions](https://typefuse.dev/guides/per-item-questions)

## The Definition

Its five fields, at the top level.

### definition

**A Decision's contract.**

One Definition is one call to one pinned model. Every answer comes back exactly as TypeSafe gives it, under the question's name.

**Fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | `3` | Required | The Definition format. Always 3. |
| `model` | `string`, Refused with “Use an exact model version such as jev-1.13.0”, one of `jev-1.13.0`, `jev-1.14.0` | Required | The model that answers, pinned to an exact version, such as jev-1.13.0. Moving to a newer model is a change you publish. |
| `state_schema` | `object` | Required | A JSON Schema for the input each call sends. To publish, every object declares its properties (or a typed additionalProperties map) and every array the shape of its items. |
| `context` | `any JSON value` | Optional | Fixed rules and reference material sent with every call, such as a policy. Anything that doesn't change from call to call belongs here rather than in the input. |
| `questions` | `object`, question names match ^[a-z][a-z0-9_]{0,63}$, Refused with “Add at least one question”, Refused with “snake_case question id” | Required | The questions the Decision answers, by name. Each answer comes back under its question's name. |

```yaml
format: 3
model: jev-1.13.0
state_schema:
  type: object
  properties:
    request:
      type: string
      description: What the customer wrote
    days_since_delivery:
      type: number
    items:
      type: array
      maxItems: 20
      items:
        type: object
        properties:
          name:
            type: string
          condition:
            type: string
        required:
          - name
          - condition
        additionalProperties: false
  required:
    - request
    - days_since_delivery
    - items
  additionalProperties: false
context:
  policy: Refund within 30 days for unused items or anything defective.
questions:
  eligible:
    type: noul
    instructions: Is this request eligible for a refund under the policy?
    criteria:
      "true": Within 30 days and unused, or defective.
      "false": Outside 30 days with no defect, or used.
  reason:
    type: choice
    instructions: Which policy rule decides this request?
    criteria:
      within_window: Inside 30 days and unused.
      defective: Faulty or damaged in transit.
      unclear: The supplied facts do not settle it.
  urgency:
    type: score
    instructions: How urgently does a person need to inspect this request?
    criteria:
      - level: routine
        description: The facts and policy give a clear answer.
      - level: immediate
        description: There is active harm or fraud.
  damaged:
    type: noul
    each: input.items
    instructions: Is `item` described as damaged?
```

## Questions

Each question is one of TypeSafe's native kinds, named by its type.

### noul

**Yes or no.**

A question answered yes or no. Its answer gives the probability of yes as `noul`, such as `{ "type": "noul", "noul": 0.94 }`.

**Fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"noul"` | Required | The kind of question. |
| `instructions` | `string or object or array or null` | Optional | What to ask, in plain words. Backticked paths refer to the input and the context, such as `input.request`. |
| `criteria` | `{ "true": string or object or array of any JSON value or null, "false": string or object or array of any JSON value or null } or null`, Refused with “Noul needs non-empty instructions or criteria” | Optional | What a true and a false answer mean. A yes-or-no question needs instructions, criteria or both. |
| `each` | `string`, a path matching ^(input\|context)(\.[A-Za-z_][A-Za-z0-9_]*)+$, its list declares maxItems, at most 100, Refused with “each is a dotted path to an array, such as input.tenders or context.sectors” | Optional | A path to a list in the input or the context, such as `input.items`: the question is asked once for each item. |

```yaml
eligible:
  type: noul
  instructions: Is this request eligible for a refund under the policy?
  criteria:
    "true": Within 30 days and unused, or defective.
    "false": Outside 30 days with no defect, or used.
```

### choice

**One of several options.**

A question answered with one of its options. Its answer gives the option chosen as `choice`, the probability of each option and a confidence.

**Fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"choice"` | Required | The kind of question. |
| `instructions` | `string or object or array or null` | Optional | What to ask, in plain words. Backticked paths refer to the input and the context, such as `input.request`. |
| `criteria` | `object`, Refused with “Choice needs at least two options” | Required | The options by name, each with what it means. At least two. |
| `each` | `string`, a path matching ^(input\|context)(\.[A-Za-z_][A-Za-z0-9_]*)+$, its list declares maxItems, at most 100, Refused with “each is a dotted path to an array, such as input.tenders or context.sectors” | Optional | A path to a list in the input or the context, such as `input.items`: the question is asked once for each item. |

```yaml
reason:
  type: choice
  instructions: Which policy rule decides this request?
  criteria:
    within_window: Inside 30 days and unused.
    defective: Faulty or damaged in transit.
    unclear: The supplied facts do not settle it.
```

### score

**A level on a scale.**

A question answered with one of its levels, which are listed lowest first.

**Fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"score"` | Required | The kind of question. |
| `instructions` | `string or object or array or null` | Optional | What to ask, in plain words. Backticked paths refer to the input and the context, such as `input.request`. |
| `criteria` | `array`, at least 2 items | Required | The levels, lowest first, each with what it means. At least two. |
| `each` | `string`, a path matching ^(input\|context)(\.[A-Za-z_][A-Za-z0-9_]*)+$, its list declares maxItems, at most 100, Refused with “each is a dotted path to an array, such as input.tenders or context.sectors” | Optional | A path to a list in the input or the context, such as `input.items`: the question is asked once for each item. |

```yaml
urgency:
  type: score
  instructions: How urgently does a person need to inspect this request?
  criteria:
    - level: routine
      description: The facts and policy give a clear answer.
    - level: immediate
      description: There is active harm or fraud.
```

## Per-item questions

Any kind of question can be asked once for each item in a list.

### each

**Asked once for each item.**

Add `each` to a question to ask it for every item of a list in the input or the context, in the same call, and refer to the item as `item` in its instructions. The answer is a list with one answer for each item, in the items' order. An empty list asks nothing.

**Fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `each` | `string`, a path matching ^(input\|context)(\.[A-Za-z_][A-Za-z0-9_]*)+$, its list declares maxItems, at most 100, Refused with “each is a dotted path to an array, such as input.tenders or context.sectors” | Optional | A path to a list in the input or the context, such as `input.items`: the question is asked once for each item. |

```yaml
damaged:
  type: noul
  each: input.items
  instructions: Is `item` described as damaged?
```
