# Decisions and Definitions What a Decision is, and how a Definition describes its input, its context and the questions it answers. ## What a Decision is A Decision is one judgment your software asks for, such as "is this refund eligible?" or "which team should handle this ticket?". It has a defined input, a set of questions and typed answers, and it is versioned like code. Every Decision belongs to an organisation, and its identifier is `organisation/decision`, for example `acme/refunds`. Decisions are answered by TypeSafe, the AI model provider TypeFuse runs on. Its model, Jev, reads the input and returns typed answers with probabilities rather than text. Each call to a Decision is a single call to one pinned version of that model. A Decision is not a workflow or a chain of prompts: it asks all of its questions together and returns their answers together. ## The Definition A Decision is described by its Definition. You write it in YAML, or in JSON if you prefer; the two are interchangeable, and TypeFuse keeps the source exactly as you wrote it. Open a Decision and choose **Definition** to edit it. ```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 } required: [request, days_since_delivery] 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. ``` A Definition has five parts: - `format` is always `3`. - `model` names an exact TypeSafe model version, such as `jev-1.13.0`. A range or a bare model name is refused, so a Decision never changes model without a new version. - `state_schema` is the JSON Schema for the input your software sends with each call. Every call is checked against it before anything is asked. - `context` is optional. It holds the static rules and reference material that go with every call, such as a policy or a price list. It is versioned with the Decision, so changing it is a release. - `questions` holds one or more questions, keyed by the answer's name. Names start with a lower-case letter and use lower-case letters, digits and underscores. The model sees `{ context, input }`: your static context beside the caller's input. ## Questions and answers There are three kinds of question, using TypeSafe's own names. TypeSafe calls a yes-or-no question a `noul`, and its answer is the probability of yes. | Type | Asks | `criteria` | Answer | | --- | --- | --- | --- | | `noul` | A yes-or-no judgment | Optional `"true"` and `"false"` descriptions | `noul`, the likelihood of yes, from 0 to 1 | | `choice` | One of a set of options | A map of at least two option keys to their meaning | `choice`, with `probabilities` for every option and `confidence` | | `score` | A position on an ordered scale | A list of at least two levels, lowest first | `score`, with the `legend` of levels, `probabilities` and `confidence` | `instructions` say what to judge. A `noul` question needs instructions, criteria or both; a `choice` or `score` question needs its criteria. A score's levels are written like this: ```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. ``` Answers come back exactly as TypeSafe returns them: ```json { "eligible": { "type": "noul", "noul": 0.94 }, "reason": { "type": "choice", "choice": "within_window", "probabilities": { "within_window": 0.9, "defective": 0.07, "unclear": 0.03 }, "confidence": 0.9 } } ``` To ask the same question once for every item in a list, see [Per-item questions](https://typefuse.dev/guides/per-item-questions). ## Drafts and publishing Every Decision has one draft. You can save a draft whenever its source parses, even while it has problems, so you can work on it in steps. Problems show in the editor with the exact path that needs attention, and the [Definition assistant](https://typefuse.dev/guides/definition-assistant) suggests fixes. Publishing is stricter. A draft publishes only when it compiles, and publishing refuses open-ended schemas: every object needs its `properties` or a typed `additionalProperties` map (use `additionalProperties: false` for an object with no fields), and every array needs the shape of its `items`. Context and questions together must also fit within the model's input size. You publish from **Versions**; see [Versions and releases](https://typefuse.dev/guides/versions). Callers keep getting the deployed version until you publish and deploy the draft. ## Settings, moving and archiving A Decision's **Settings** hold its name, description and category. The category is chosen by TypeFuse from the Definition whenever it changes; **Recategorise** asks again. From Settings an owner or admin can also move it to another organisation (see [Moving a Decision](https://typefuse.dev/guides/organisations#moving-a-decision)) or archive it. A Decision can't be deleted: its calls are sealed into the audit trail, and its versions, approvals and evidence packs are the record an auditor asks for. Archiving takes it out of every environment it serves (take it out of production first), off the Decisions list and off your plan's count, and makes it read-only. Its history stays, and you can restore it from the Decisions list. ## Where to go next - Try the draft on real input in the [Sandbox](https://typefuse.dev/guides/examples-and-test-sets#the-sandbox). - Write [Examples and Test sets](https://typefuse.dev/guides/examples-and-test-sets) so the Decision can be checked. - Let an agent write the Definition with you: [Connecting an agent](https://typefuse.dev/guides/agents).