Open System One Specification

Status: early draft. Later releases may include breaking changes, marked in the changelog.

This document holds the normative rules of Open System One. The contract itself is the OpenAPI file of a release, the latest being openapi/2026-11-07.json; schema names in this document, such as SystemOneRequest, refer to its components.schemas. Where this document and the OpenAPI file disagree, that is a bug.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

Scope and terminology

• State: the input that all questions in a request refer to: a string, or structured data as an object or array (SystemOneContent).
• Question: a named, typed question about the state (SystemOneQuestion). Its type selects the question shape and the answer shape.
• Answer: the result for one question, under the question’s name, with the question’s type (SystemOneAnswer).
• Asset: an image referenced from the state, instructions, or criteria by a placeholder (SystemOneAsset).
• Implementer: a server that serves the System One operation at an endpoint URL, such as a model provider or a gateway in front of one.
• Client: anything that calls an implementer.
• Decision types (noul, choice, score, box) judge the state: a probability, a choice, a score, or a box in an image. They come from TypeSafe’s format.
• Extraction types (text, number, date, time, datetime, duration, list, estimate, forecast) answer with values read, computed, or estimated from the state.
• Core types are the decision and extraction types above (SystemOneCoreQuestion, SystemOneCoreAnswer). Extension types are any other type, named owner:type.

An implementer need not support every core type. It MUST reject the ones it does not support (see Errors).

Endpoint and envelope

The contract fixes no endpoint path. Its operation, components.pathItems.SystemOne, is served as an HTTP POST at a URL the implementer chooses, such as https://api.example.com/v1/systemone. A client MUST take the full endpoint URL as configuration, not build it from a base URL, so that switching implementers changes only the URL and model.

An implementer MUST accept an application/json body. It MAY also accept multipart/form-data, with the JSON request in the first part, named request, and each image in its own part.

• A request either succeeds with every answer or fails. An implementer MUST NOT return a partial answers object.
• Setting a field to its documented default is equivalent to omitting it.
• Implementers MAY add response fields. Clients MUST ignore response fields they do not know.
• Request fields this specification does not define are implementer-defined: an implementer MAY ignore or reject them.

Question types

Settings are the question fields other than type.

An implementer MUST NOT silently ignore a setting it cannot honor. It MUST reject the request with unsupported_parameter.

Answer guarantees

An implementer MUST return answers that satisfy these rules. Clients MAY rely on them across implementers.

Decision types

• noul, choice, score, and box answers keep TypeSafe’s shapes exactly.
• choice: choice MUST be one of the question’s criteria names and SHOULD be the one with the highest probability. probabilities is keyed by criteria names.
• score: legend and probabilities are keyed by score level, "0" for the first criterion. score is within [0, number of criteria - 1].

Value types

text, number, date, time, datetime, and duration are value types. Their answers have value, p_null, confidence, and optionally guess and span.

• Null rule: value MUST be null when p_null is above the question’s null_threshold, and MUST NOT be null otherwise. null_threshold defaults to 0.5.
• Guess: guess is the most likely value. An implementer that returns guess MUST return it also when value is null. An answer with a non-null span MUST have guess.
• Span: span is where guess was read in the state text, as a half-open range [start, end) of SystemOneSpan offsets, with start <= end <= length. It indexes into state_text when the response has it, and into state otherwise. For text, the spanned text MUST equal guess; for other value types it is the text guess was read from, such as $52.10 for 52.1. When guess was not read from the state text, for example when it was read from an image or computed, span is absent or null.
• Offsets count Unicode code points.
• number and duration values honor integer and decimals. A duration answer’s unit equals its question’s unit, which defaults to seconds.
• date is YYYY-MM-DD. time is 24-hour HH:MM or HH:MM:SS without a time zone. datetime is SystemOneDateTime, with an offset only when the state gives one.

list

• value MUST be an array, never null: no match is an empty list.
• Items MUST be in the order they appear in the input, each in the format of its items type.
• spans, when present, has one entry per item in the same order: the item’s span, following the span rules above, or null when the item was not read from the state text. It is REQUIRED for text items, and each non-null entry for a text item MUST cover exactly that item.

estimate

• An estimate answer is never null.
• value, median, p10, p90, and every entry of quantiles MUST be within [min, max] and of the same kind as min and max (numbers or dates).
• mean, p_below, and p_above are optional. mean, when present, is of the same kind as min and max: a date for date estimates.
• value, median, p10, and p90 MUST be on the step grid starting at min, when step is set. mean MAY fall between grid points.
• p10 <= median <= p90.
• quantiles MUST be present when the question sets quantiles: true, as the 1st to 99th percentiles in non-decreasing order, and MUST be absent otherwise.

forecast

• steps MUST have exactly horizon entries, nearest step first. Parallel arrays per field, such as an array of values and an array of medians, are not part of the contract; an implementer MAY return them only as extra fields.
• Each step MUST satisfy the estimate rules, using the question’s min, max, step, and scale. Steps MUST NOT have quantiles: forecast questions have no quantiles setting.

Truncation and state text

• state_text is REQUIRED whenever span offsets index text that differs from the state sent, for example when structured state is serialized to text. It MUST be the text the offsets index into.
• An answer MUST NOT have spans into a non-string state without state_text.
• truncated is REQUIRED whenever the implementer knows whether it shortened the state to fit the model’s context. An implementer that never truncates MAY omit it or set it to false.
• Clients MUST NOT read an absent truncated as false.
• When truncated is true, state_text, if returned, MAY be only the portion of the state the model read. Spans index into it.
• Instead of truncating, an implementer MAY reject input too long for the model with an implementer-defined error.

Errors

Two error codes are standard. Both use HTTP 400 and the SystemOneErrorResponse envelope.

An implementer MUST use:

• unsupported_question_type for a question whose type it does not support, whether core, extension, or unknown. param is questions.<name>.type.
• unsupported_parameter for a request field or question setting defined by this specification that it cannot honor, such as a reference_date it cannot apply, assets for a model without image input, or quantiles: true for a model without quantiles. param names the field.

An implementer MAY report only the first unsupported item. All other errors, such as unknown models, oversized input, authentication, and rate limits, are implementer-defined.

Extension types

• A non-core type MUST be named owner:type (SystemOneExtensionType): a lowercase owner identifier, a colon, and a lowercase type name, such as acme:sentiment.
• The owner identifier names the organization that defines the type, such as its domain name without the top-level domain. Owners SHOULD publish the question and answer shapes of their types.
• Unprefixed type names are reserved for core types. Implementers MUST NOT define unprefixed types.
• Only type is constrained by ExtensionQuestion and ExtensionAnswer. Owners SHOULD reuse core conventions such as p_null, confidence, and span, and MUST follow the envelope, error, and state text rules.
• An implementer MUST reject an extension type it does not support with unsupported_question_type.
• Clients and intermediaries SHOULD tolerate answer types they do not know: a gateway SHOULD pass them through unchanged, and a client MAY skip them.

Promotion to core

An extension type becomes core when at least two independent implementers support it with the same shape and a dated release adds it. That release defines it under the unprefixed name. Implementers that supported the prefixed name SHOULD keep accepting it, as an alias, until the next dated release.

Versioning

• A release is a single OpenAPI file named openapi/YYYY-MM-DD.json by its release date. A released file MUST NOT change.
• The first release is 2026-11-07.
• openapi/draft.json is the working draft. It MAY change at any time and is not a release. At a release it is identical to the new release file, whose date is its info.version; between releases its info.version is draft.
• Additive changes are new optional request fields or question settings, new response fields, and new core types. Any other change, such as removing, renaming, or retyping a field, or making an optional field required, is breaking. Breaking changes SHOULD be avoided and MUST be marked as breaking in the changelog.
• Releases after 2026-11-07 fix no endpoint path. The 2026-11-07 release defines its operation at /v1/systemone.
• Clients pin a release by vendoring its dated file, optionally with a checksum. Implementers SHOULD state which release they implement.

Compatibility with TypeSafe

• Open System One is a strict superset of TypeSafe’s format: a valid TypeSafe request is a valid SystemOneRequest, and TypeSafe answers are valid SystemOneAnswers.
• Releases MUST NOT change TypeSafe’s request or answer shapes.
• If TypeSafe adds a type whose name collides with a core type, the next dated release adopts TypeSafe’s shape. If that shape is not compatible with the core one, the change is breaking and is marked as such; earlier releases keep the old shape.