---
title: "OpenAPI component schemas"
type: reference
tags: [openapi, schemas, reference, validation, http-api]
created: 2026-09-17
updated: 2026-09-17
confidence: high
sources:
  - raw/site/openapi.json
  - raw/docs/api.md
jev_version: "jev-1.13.0"
summary: "Every component schema in TypeSafe's OpenAPI 3.1.0 document (info version 0.2.0): properties, types, requiredness, constraints, and examples."
---

# OpenAPI component schemas

> **TL;DR** The TypeSafe OpenAPI document (`openapi: 3.1.0`, `info.version: 0.2.0`, `info.title: "TypeSafe"`) defines 16 component schemas. `SystemOneRequest` and `SystemOneResponse` are the two you serialize; `Question` and `Answer` are `oneOf` unions discriminated on `type`; `HTTPValidationError`/`ValidationError` describe the 422 body.

## Document metadata

| Field | Value |
|---|---|
| `openapi` | `3.1.0` |
| `info.title` | `TypeSafe` |
| `info.version` | `0.2.0` |
| `info.description` | "Ask yes/no questions, evaluate statements, select choices, or assign ratings to your content. Send your API key in the Authorization header as `Bearer <API_KEY>`. Use GET /v1/models to discover available model names." |
| `paths` | `/v1/systemone` (POST), `/v1/models` (GET) |
| `components.securitySchemes.HTTPBearer` | `{"type": "http", "scheme": "bearer"}` |

Note the version skew: the **API path** is `v1` while the **OpenAPI document** is `0.2.0`. They are independent version numbers.

## Schema index

| Schema | Kind | Used as |
|---|---|---|
| `SystemOneRequest` | object | POST `/v1/systemone` request body |
| `SystemOneResponse` | object | POST `/v1/systemone` 200 response |
| `Question` | `oneOf` union, discriminator `type` | value type of `SystemOneRequest.questions` |
| `NoulQuestion` | object | `Question` variant `noul` |
| `NoulCriteria` | object | `NoulQuestion.criteria` |
| `ChoiceQuestion` | object | `Question` variant `choice` |
| `ScoreQuestion` | object | `Question` variant `score` |
| `Answer` | `oneOf` union, discriminator `type` | value type of `SystemOneResponse.answers` |
| `NoulAnswer` | object | `Answer` variant `noul` |
| `ChoiceAnswer` | object | `Answer` variant `choice` |
| `ScoreAnswer` | object | `Answer` variant `score` |
| `Usage` | object | `SystemOneResponse.usage` |
| `ModelMetadata` | object | element of `ModelMetadataList.models` |
| `ModelMetadataList` | object | GET `/v1/models` 200 response |
| `HTTPValidationError` | object | 422 response on both paths |
| `ValidationError` | object | element of `HTTPValidationError.detail` |

## SystemOneRequest

Description: "Content and named questions to evaluate together using a TypeSafe model." `required: ["model", "questions", "state"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `state` | `anyOf`: `string`, `object` (`additionalProperties: true`), `array` | Yes | — | — | "The content all questions in this request refer to." |
| `model` | `string` | Yes | — | — | "Name or alias of the model to use. Available names are returned by GET /v1/models." |
| `questions` | `object` with `additionalProperties: {$ref: Question}` | Yes | — | `minProperties: 1` | "Questions to ask about the content, each with a name you choose. The response uses those names to identify the answers." |

Examples in the spec: `state` → `"I was charged twice. Please help."` and `{"subject": "Duplicate charge", "message": "Please help."}`; `model` → `"jev-latest"`; `questions` → `{"billing": {"type": "noul", "instructions": "Is this message about billing?"}}`.

Note `state` is **not** nullable here (no `null` member in the `anyOf`), unlike `instructions` on questions.

### Raw JSON schema

```json
{
  "SystemOneRequest": {
    "properties": {
      "state": {
        "anyOf": [
          { "type": "string" },
          { "additionalProperties": true, "type": "object" },
          { "items": {}, "type": "array" }
        ],
        "title": "State",
        "description": "The content all questions in this request refer to.",
        "examples": [
          "I was charged twice. Please help.",
          { "message": "Please help.", "subject": "Duplicate charge" }
        ]
      },
      "model": {
        "type": "string",
        "title": "Model",
        "description": "Name or alias of the model to use. Available names are returned by GET /v1/models.",
        "examples": ["jev-latest"]
      },
      "questions": {
        "additionalProperties": { "$ref": "#/components/schemas/Question" },
        "type": "object",
        "minProperties": 1,
        "title": "Questions",
        "description": "Questions to ask about the content, each with a name you choose. The response uses those names to identify the answers.",
        "examples": [
          { "billing": { "instructions": "Is this message about billing?", "type": "noul" } }
        ]
      }
    },
    "type": "object",
    "required": ["model", "questions", "state"],
    "title": "SystemOneRequest",
    "description": "Content and named questions to evaluate together using a TypeSafe model."
  }
}
```

## SystemOneResponse

Description: "Answers grouped by question name, with the model used and token usage." `required: ["model", "answers", "usage"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `model` | `string` | Yes | — | — | "Name of the model that answered the questions. May differ from the alias supplied in the request." |
| `answers` | `object` with `additionalProperties: {$ref: Answer}` | Yes | — | `minProperties: 1` | "Answers keyed by the question names supplied in the request. Each answer's type matches its question's type." |
| `usage` | `$ref: Usage` | Yes | — | — | "Input and output token counts for this evaluation." |

### Raw JSON schema

```json
{
  "SystemOneResponse": {
    "properties": {
      "model": {
        "type": "string",
        "title": "Model",
        "description": "Name of the model that answered the questions. May differ from the alias supplied in the request.",
        "examples": ["jev-latest"]
      },
      "answers": {
        "additionalProperties": { "$ref": "#/components/schemas/Answer" },
        "type": "object",
        "minProperties": 1,
        "title": "Answers",
        "description": "Answers keyed by the question names supplied in the request. Each answer's type matches its question's type.",
        "examples": [{ "billing": { "noul": 0.98, "type": "noul" } }]
      },
      "usage": {
        "$ref": "#/components/schemas/Usage",
        "description": "Input and output token counts for this evaluation.",
        "examples": [{ "input_tokens": 120, "output_tokens": 12 }]
      }
    },
    "type": "object",
    "required": ["model", "answers", "usage"],
    "title": "SystemOneResponse",
    "description": "Answers grouped by question name, with the model used and token usage."
  }
}
```

## Question (union)

Description: "A question about the supplied content."

| Aspect | Value |
|---|---|
| Composition | `oneOf: [NoulQuestion, ChoiceQuestion, ScoreQuestion]` |
| `discriminator.propertyName` | `type` |
| `discriminator.mapping` | `choice → ChoiceQuestion`, `noul → NoulQuestion`, `score → ScoreQuestion` |

## NoulQuestion

Description: "A yes/no question or statement, answered with the probability of yes or true." `required: ["type"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `type` | `string`, `const: "noul"` | Yes | — | `const` pins the value | "Identifies a yes/no question or statement." |
| `instructions` | `anyOf`: `string`, `object`, `array`, `null` | No (per spec; raw/docs/api.md marks it required) | — | — | "The yes/no question or statement to evaluate." |
| `criteria` | `anyOf`: `$ref NoulCriteria`, `null` | No | — | — | "Criteria clarifying what counts as a yes or no answer." |

Spec examples for `instructions`: `"Is this message spam?"`, `"This message contains unsolicited advertising."`, `{"task": "Identify unsolicited advertising."}` — i.e. a question, a statement, or a structured object. `criteria` example: `{"true": "Unsolicited advertising", "false": "A legitimate conversation"}`.

## NoulCriteria

Description: "Criteria defining what counts as a yes or no answer." No `required` list — both properties are optional.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `true` | `anyOf`: `string`, `object`, `array`, `null` | No | — | — | "What counts as a yes answer." Example: "The message is unsolicited advertising." |
| `false` | `anyOf`: `string`, `object`, `array`, `null` | No | — | — | "What counts as a no answer." Example: "The message is a legitimate conversation." |

`true` and `false` are JSON **string keys**, not booleans.

## ChoiceQuestion

Description: "A question that selects one option from the choices you define." `required: ["criteria", "type"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `type` | `string`, `const: "choice"` | Yes | — | — | "Identifies a question that selects one of the choices in criteria." |
| `instructions` | `anyOf`: `string`, `object`, `array`, `null` | No (per spec; required per raw/docs/api.md) | — | — | "What the model should decide when choosing an option." Example: "What is the tone of this message?" |
| `criteria` | `object` with `additionalProperties: anyOf [string, object, array, null]` | Yes | — | no `minProperties` in spec | "Choice names and descriptions of when each applies. A choice without a description is interpreted by its name alone." |

`criteria` example: `{"angry": "An upset or hostile message", "calm": "A neutral or polite message", "excited": "An enthusiastic or eager message"}`.

## ScoreQuestion

Description: "A question that assigns a score using an ordered rubric." `required: ["criteria", "type"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `type` | `string`, `const: "score"` | Yes | — | — | "Identifies a question that rates the content using the levels in criteria." |
| `instructions` | `anyOf`: `string`, `object`, `array`, `null` | No (per spec; required per raw/docs/api.md) | — | — | "What the model should rate." Example: "How urgent is this message?" |
| `criteria` | `array`, items `anyOf [string, object, array]` (items are **not** nullable) | Yes | — | `minItems: 1` in the spec; raw/docs/api.md says "at least two levels" | "Ordered descriptions of the score levels. Each description's position determines its score, starting at zero." |

`criteria` example: `["Can wait", "Needs attention this week", "Needs attention today"]`.

## Answer (union)

Description: "An answer whose type matches the corresponding question."

| Aspect | Value |
|---|---|
| Composition | `oneOf: [NoulAnswer, ScoreAnswer, ChoiceAnswer]` |
| `discriminator.propertyName` | `type` |
| `discriminator.mapping` | `choice → ChoiceAnswer`, `noul → NoulAnswer`, `score → ScoreAnswer` |

## NoulAnswer

Description: "The probability of a yes answer or a true statement." `required: ["noul", "type"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `type` | `string`, `const: "noul"` | Yes | — | — | "Identifies a yes/no answer." |
| `noul` | `number` | Yes | — | 0 to 1 (stated in the description, not as `minimum`/`maximum`) | "Probability of a yes answer or a true statement, from 0 to 1. Values near 1 favor yes or true, values near 0 favor no or false, and values near 0.5 indicate uncertainty." Example: `0.98` |

No `confidence` property exists on `NoulAnswer`.

## ChoiceAnswer

Description: "The selected choice, confidence, and probabilities for a choice question." `required: ["choice", "confidence", "probabilities", "type"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `type` | `string`, `const: "choice"` | Yes | — | — | "Identifies a selection from the requested choices." |
| `choice` | `string` | Yes | — | — | "The name of the choice with the highest probability among the question's criteria." Example: `"angry"` |
| `confidence` | `number` | Yes | — | 0 to 1 (description only) | "Confidence in the selected choice, from 0 to 1. Higher values indicate greater certainty; use lower values to flag uncertain selections for review." Example: `0.9` |
| `probabilities` | `object` with `additionalProperties: {type: number}` | Yes | — | values 0 to 1, sum ≈ 1 (description only) | "Probability of each choice in criteria, keyed by choice name, from 0 to 1. Shows how likely the alternatives are; values sum to approximately 1." Example: `{"angry": 0.8, "calm": 0.1, "excited": 0.1}` |

## ScoreAnswer

Description: "An expected score with its rubric, confidence, and score-level probabilities." `required: ["score", "confidence", "legend", "probabilities", "type"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `type` | `string`, `const: "score"` | Yes | — | — | "Identifies a rating against the requested score levels." |
| `score` | `number` | Yes | — | may be non-integer | "Expected score: the probability-weighted average of the rubric levels. May fall between integer levels." Example: `1.7` |
| `confidence` | `number` | Yes | — | 0 to 1 (description only) | "Confidence in the score, from 0 to 1. Higher values indicate greater certainty; use lower values to flag uncertain ratings for review." Example: `0.9` |
| `legend` | `object` with `additionalProperties: anyOf [string, object, array]` | Yes | — | keys are level indices as strings | "The requested criteria mapped to their score levels, so you can interpret the score." Example: `{"0": "Can wait", "1": "Needs attention this week", "2": "Needs attention today"}` |
| `probabilities` | `object` with `additionalProperties: {type: number}` | Yes | — | same keys as `legend`; sum ≈ 1 | "Probability of each score level, from 0 to 1, using the same keys as legend. Shows how likely the alternatives are; values sum to approximately 1." Example: `{"0": 0.1, "1": 0.1, "2": 0.8}` |

## Usage

Description: "Token usage for the request." `required: ["input_tokens", "output_tokens"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `input_tokens` | `integer` | Yes | — | — | "Number of billable input tokens used to evaluate the request." Example: `120` |
| `output_tokens` | `integer` | Yes | — | — | "Number of output tokens used to answer the questions. Output tokens are currently free of charge." Example: `12` |

## ModelMetadata

Description: "A model or model alias available to the authenticated account." `required: ["name", "description", "release_date"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `name` | `string` | Yes | — | — | "Model name or alias accepted by the request's model field." Example: `"jev-latest"` |
| `description` | `string` | Yes | — | — | "Human-readable description of the model and its capabilities." Example: "General-purpose system one model." |
| `release_date` | `string` | Yes | — | format stated in prose as `YYYY-MM-DD`, no JSON Schema `format` keyword | "Model release date, formatted as YYYY-MM-DD." Example: `"2026-09-15"` |

## ModelMetadataList

Description: "Models and aliases available to the authenticated account." `required: ["models"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `models` | `array<ModelMetadata>` | Yes | — | no `minItems` | "Available models and aliases. Use a model's name in POST /v1/systemone requests." |

## HTTPValidationError

Description: "Request validation failures returned with HTTP status 422." **No `required` list** — `detail` is technically optional.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `detail` | `array<ValidationError>` | No | — | — | "Validation errors describing which request values are missing or invalid." Example: `[{"loc": ["body", "state"], "msg": "Field required", "type": "missing"}]` |

## ValidationError

Description: "A request validation error at a specific field or array element." `required: ["loc", "msg", "type"]`.

| Property | Type | Required | Default | Constraints | Description (verbatim) |
|---|---|---|---|---|---|
| `loc` | `array` of `anyOf [string, integer]` | Yes | — | — | "Path to the invalid value: the request location followed by field names and array indices." Example: `["body", "questions", "urgency", "score", "criteria"]` |
| `msg` | `string` (title "Message") | Yes | — | — | "Human-readable explanation of the validation failure." Example: `"Field required"` |
| `type` | `string` (title "Error Type") | Yes | — | — | "Machine-readable validation error code." Example: `"missing"` |
| `input` | any (no `type` keyword) | No | — | — | "The input value that failed validation." Example: `{"type": "score"}` |
| `ctx` | `object` (title "Context") | No | — | — | "Additional context used to explain the validation failure." Example: `{"min_length": 1}` |

## Gotchas for code generators

- `Question` and `Answer` are `oneOf` with a `type` discriminator, so a generated tagged union keys on `type`, not on the presence of `criteria`.
- `instructions` is nullable in the spec but documented as required in raw/docs/api.md — generators that follow the spec will emit an optional field; always populate it anyway.
- `ScoreQuestion.criteria` items are **not** nullable, while `ChoiceQuestion.criteria` values **are** (`null` is a valid option description).
- `ScoreAnswer.legend` and `ScoreAnswer.probabilities` are keyed by the level index rendered as a **string** (`"0"`, `"1"`, ...), not by integer.
- `NoulCriteria` uses the literal keys `true` and `false`; in a typed language these need quoting or renaming with an alias.
- `minProperties: 1` applies to both `SystemOneRequest.questions` and `SystemOneResponse.answers` — an empty map is invalid in either direction.
- `529 Overloaded` (raw/docs/api.md) has **no** response entry in the OpenAPI document; only `200` and `422` are declared per path. Neither is `401` or `429`. Do not assume the spec enumerates every status. See [[reference/rate-limits-and-errors]].

## Related

- [[reference/http-api]] — the endpoints these schemas describe
- [[reference/rate-limits-and-errors]] — statuses the spec does not enumerate
- [[reference/python-sdk-questions]] — the Python types over these schemas
- [[reference/javascript-sdk-types]] — the TypeScript interfaces over these schemas
- [[concepts/primitives]] — semantics of Noul, Choice, Score
- [[concepts/confidence]] — what `confidence` measures

## Sources

- raw/site/openapi.json (https://docs.typesafe.ai/openapi.json)
- raw/docs/api.md (https://docs.typesafe.ai/api)