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

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

Schema index

SystemOneRequest

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

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

{
  "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"].

Raw JSON schema

{
  "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."

NoulQuestion

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

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.

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"].

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"].

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

Answer (union)

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

NoulAnswer

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

No confidence property exists on NoulAnswer.

ChoiceAnswer

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

ScoreAnswer

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

Usage

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

ModelMetadata

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

ModelMetadataList

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

HTTPValidationError

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

ValidationError

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

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 HTTP status codes, rate limits, retry semantics.

Related

• HTTP API: POST /v1/systemone and GET /v1/models — the endpoints these schemas describe
• HTTP status codes, rate limits, retry semantics — statuses the spec does not enumerate
• Python SDK question types (Noul, Choice, Score) — the Python types over these schemas
• JavaScript SDK interfaces and type aliases — the TypeScript interfaces over these schemas
• Primitives: Choice, Score, Noul — semantics of Noul, Choice, Score
• Confidence vs probability — what confidence measures

Sources

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