Skip to content

Reference

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.

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

  • formatRequired3
    The Definition format. Always 3.
  • modelRequiredstringRefused with “Use an exact model version such as jev-1.13.0”
    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.One of jev-1.13.0, jev-1.14.0
  • state_schemaRequiredobject
    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.
  • contextOptionalany JSON value
    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.
  • questionsRequiredobjectquestion names match ^[a-z][a-z0-9_]{0,63}$Refused with “Add at least one question”Refused with “snake_case question id”
    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

  • typeRequired"noul"
    The kind of question.
  • instructionsOptionalstring or object or array or null
    What to ask, in plain words. Backticked paths refer to the input and the context, such as input.request.
  • criteriaOptional{ "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 nullRefused with “Noul needs non-empty instructions or criteria”
    What a true and a false answer mean. A yes-or-no question needs instructions, criteria or both.
  • eachOptionalstringa path matching ^(input|context)(\.[A-Za-z_][A-Za-z0-9_]*)+$its list declares maxItems, at most 100Refused with “each is a dotted path to an array, such as input.tenders or context.sectors”
    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

  • typeRequired"choice"
    The kind of question.
  • instructionsOptionalstring or object or array or null
    What to ask, in plain words. Backticked paths refer to the input and the context, such as input.request.
  • criteriaRequiredobjectRefused with “Choice needs at least two options”
    The options by name, each with what it means. At least two.
  • eachOptionalstringa path matching ^(input|context)(\.[A-Za-z_][A-Za-z0-9_]*)+$its list declares maxItems, at most 100Refused with “each is a dotted path to an array, such as input.tenders or context.sectors”
    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

  • typeRequired"score"
    The kind of question.
  • instructionsOptionalstring or object or array or null
    What to ask, in plain words. Backticked paths refer to the input and the context, such as input.request.
  • criteriaRequiredarrayat least 2 items
    The levels, lowest first, each with what it means. At least two.
  • eachOptionalstringa path matching ^(input|context)(\.[A-Za-z_][A-Za-z0-9_]*)+$its list declares maxItems, at most 100Refused with “each is a dotted path to an array, such as input.tenders or context.sectors”
    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

  • eachOptionalstringa path matching ^(input|context)(\.[A-Za-z_][A-Za-z0-9_]*)+$its list declares maxItems, at most 100Refused with “each is a dotted path to an array, such as input.tenders or context.sectors”
    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?