Type Alias: OsfqlValue

OsfqlValue = { type: "null"; } | { type: "unbound"; } | { type: "integer"; value: number; } | { type: "float"; value: number; } | { type: "string"; value: string; } | { type: "boolean"; value: boolean; } | { type: "datetime"; value: string; } | { type: "list"; value: OsfqlValue[]; } | { type: "term_ref"; value: string; } | { type: "term"; value: OsfqlTermValue; }

Defined in: src/types/osfql.ts:209

A bound value from OSFQL execution.

Union Members

Type Literal

{ type: "null"; }

Type Literal

{ type: "unbound"; }

Type Literal

{ type: "integer"; value: number; }

Type Literal

{ type: "float"; value: number; }

Type Literal

{ type: "string"; value: string; }

Type Literal

{ type: "boolean"; value: boolean; }

Type Literal

{ type: "datetime"; value: string; }

A UTC instant in its RFC 3339 Z-suffixed form — the binding of a date/timestamp feature, or of a MIN/MAX aggregate over one.

Type Literal

{ type: "list"; value: OsfqlValue[]; }

Type Literal

{ type: "term_ref"; value: string; }

Type Literal

{ type: "term"; value: OsfqlTermValue; }

Remarks

Uses a tagged discriminated union with type as the discriminant. The discriminants are lowercase on the wire ("string", not "String") — this is not the tagged ValueDto format used by term CRUD, and not the untagged FeatureValueDto inference format. The Rust DTO is adjacently tagged (#[serde(tag = "type", content = "value")]), so every non-null variant carries its payload under a single value key.

The union is genuinely recursive: list holds Vec<OsfqlValueDto> and a term’s features hold BTreeMap<String, OsfqlValueDto>. The backend erases both with #[schema(value_type = ...Object)], so the SDK hand-writes the recursion against the Rust source rather than degrading the nested payloads to object.

The property-graph endpoints return this exact DTO — PropertyGraphValue is an alias of this type.

unbound and null are different answers and carry no payload for opposite reasons. null is a value the record HOLDS — the OSF null. unbound is the record NOT carrying the feature at all: the pattern named it, open-world OSF bound a fresh unconstrained variable, and there is no value and no record to point at. Render it as an absence (an em dash), never as data. Backend issue #205 shipped it as a term_ref whose UUID GET /terms/:id answers 404 for and which differed on every execution of the same query.

Example

const text: OsfqlValue = { type: 'string', value: 'Alice' };
const list: OsfqlValue = { type: 'list', value: [{ type: 'integer', value: 1 }] };
const term: OsfqlValue = {
  type: 'term',
  value: { sort: 'person', features: { name: text } },
};