Schemas

TsFamilyForecastQuery

A forecast query over one timeseries family: the timeseries family and its schema (`input`), the columns to forecast (`targets`), an optional aggregation `selector`, `static_variables`, the requested `quantiles`, `compute_metrics`, and the time-axis settings (`cutoff`, `lead_time`, `context`, `prediction_length`, `span`).

TimeseriesFamilySchema · required

A timeseries family written out in full: where its rows come from, plus what its columns mean.

targets

array | null · minItems: 1

The columns to forecast. Omit to forecast every column the schema declares with the "target" kind.

Default: null

Selector

Selector for materializing a subset of a timeseries family. If omitted, every timeseries will be forecasted.

An object with one entry per dimension, keyed by the level to forecast that dimension at: "city" takes the geography dimension at its city level, aggregating the finer levels below it. Each value is a pattern, narrowing which of that level's values to take:

"any" selects every value at that level.
[value, ...] selects concrete values.
{ "from": value?, "to": value? } selects a bounded or half-bounded range.

A dimension with no entry is aggregated over entirely.

Default: null

object

Default: {}

quantiles

array | null · unique

Quantile levels to forecast for every target, as numbers in [0, 1]; include "mean" to also request the mean. Omit for a default spread.

Default: null

compute_metrics

boolean

Score the forecast against the actuals the request carries, and report the scores under metrics in the response. A cutoff is scored only when its whole forecast window is present and non-null for every target. Some of the scores are computed on the mean, so when this is set the mean is forecasted whether or not quantiles asks for it.

Default: false

InformationCutoffDatetime[] · minItems: 1

A non-empty array of information cutoffs. For example ["latest"], an explicit date ["2025-01-31"], or a recurring schedule [{ "every": "3d" }].

Default: ["latest"]

Leadtime

Gap held before the forecast starts, on top of the step separating the information cutoff from the first prediction's target time.

Default: 0

Context

How much history to feed the model before the information cutoff.

Default: null

Horizon

Total time window forecasted, measured from the end of the lead time.

Default: 1

Span

Target-time interval covered by each forecasted value (e.g. a span of 1d produces daily predictions, 3d produces 3-day buckets).

Default: 1

TimeseriesFamilySchema

A timeseries family written out in full: where its rows come from, plus what its columns mean.

Source · required

Where the timeseries family's rows come from.

object · required

The timeseries family's columns, keyed by name. Exactly one declares kind: "time".

has_gaps

boolean | null

Whether rows may be missing from the grid. false, the default, asserts the rows are complete and reports the first gap as an error. true completes the grid and lets series start late, then fills the rows it added the way each column says to: a column with an impute rule gets that rule's value, and a column without one is left null.

object | null

Roll-up paths, keyed by the name you give each one.

Covariate[]

Other timeseries families to attach, each contributing extra variables.

name

string | null

A name for the timeseries family, for your own reference.

description

string | null

What the timeseries family holds, for your own reference.

metadata

Anything you want to keep alongside the timeseries family. It is stored as written and plays no part in the forecast.

Column

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	No specific criteria

Properties for Role shorthand:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Identifier:

Const value: identifier

Names which series a row belongs to, such as a store or a product.

BareKind

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Identifier:

Const value: identifier

Names which series a row belongs to, such as a store or a product.

FullColumn

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind

Properties for Identifier column:

Names which series a row belongs to.

kind

string · const · required

Const value: identifier

type

Type

Type of the column's values. Omit it and the type is read from the data; a type given here wins.

Example 1: int64

Example 2: float64

Example 3: string

Example 4: date32

Example 5: timestamp_us

Example 6: nullable<float64>

column

string | null

Column to read in the source data, when it differs from the name this declaration sits under. Cannot be combined with virtual.

virtual

Expr

Expression computing the column instead of reading it from the source. Cannot be combined with column. Not supported yet: a request declaring it is rejected.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

description

string | null

What the column means, for your own reference.

Type

string

A value type: bool, int32, int64, float32, float64, string, date32, or timestamp_us. Wrap one in nullable<...> to allow missing values, or in list<...> for a column of lists.

Example 1: int64

Example 2: float64

Example 3: string

Example 4: date32

Example 5: timestamp_us

Example 6: nullable<float64>

Expr

string

An expression: an aggregation (sum, mean, avg, min, max), a literal (0, 1.5, true), or a comma-separated tuple of those in parentheses.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

Known

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	type = object · requires: at

Properties for Named horizon:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Historical:

Const value: historical

Observed up to the cutoff only.

KnownTime

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Historical:

Const value: historical

Observed up to the cutoff only.

KnownAt

An observation time given as an expression. Not supported yet: a request declaring it is rejected.

at

Expr · required

When the value becomes observable, as an expression over the time column.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

Aggregate

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object · requires: expr

Properties for Aggregation:

Expr

The aggregation on its own.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

AggregateTable

An aggregation plus what it is allowed to read.

expr

Expr · required

How the values combine.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

complete

array | null

Roll-up paths whose levels have to be complete first: every level a row could exist at is filled in before the values combine.

imputed

boolean | null

Whether filled-in values feed the aggregation as well as recorded ones. Defaults to false.

Impute

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: const
	type = object · requires: locf
	type = object · requires: locb
	type = object · requires: rolling

Properties for Constant:

Fill every gap with the same value.

const

number | boolean | string · required

The value to fill with. A string keeps its own quotation marks inside the JSON string, as the examples show, and there is no null: to leave gaps empty, omit the rule instead.

Example 1: 0

Example 2: 1.5

Example 3: true

Example 4: "n/a"

GapFill

How far a carried value reaches.

max_gap

integer | null · uint64 · min: 0 · max: 4294967295

Longest run of consecutive missing values to fill, counted in grid steps. Omit it to fill runs of any length.

Rolling

A statistic over the values around each gap.

RollingStat · required

Which statistic to compute.

size

integer · uint64 · min: 1 · max: 4294967295 · required

How many grid steps the window spans. A centred window needs an odd number, so it has as many steps on each side.

RollingAlignment

Where the window sits relative to the value being filled. Defaults to trailing. centered needs an odd size.

RollingStat

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Mean:

Const value: mean

Arithmetic mean of the window.

RollingAlignment

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string

Properties for Trailing:

Const value: trailing

The window covers the steps before it.

Interpolate

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	type = object · requires: proportional_by

Properties for Named method:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Broadcast:

Const value: broadcast

Copy the coarser value onto every finer row.

InterpolateName

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Broadcast:

Const value: broadcast

Copy the coarser value onto every finer row.

ProportionalBy

A split weighted by another column.

proportional_by

string · required

Column whose values weight the split.

Rule

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: at, impute
	type = object · requires: from, to

Properties for Filling rule:

How to fill missing values at the levels it names.

ImputeRule

at

RankPattern · required

Levels this rule applies at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

Impute · required

How the missing values are filled there.

ImputeRule

How to fill missing values at named levels.

at

RankPattern · required

Levels this rule applies at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

Impute · required

How the missing values are filled there.

RankPattern

string

Which levels a rule applies to: * for every level of every roll-up path, or a comma-separated list of clauses, one per path. A clause compares a path's level with =, >=, <=, >, or <, where the coarser level is the greater one, and its right-hand side is a level name, * for any level, or absent for rows not broken down by that path at all.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

TransitionRule

How values move from one level to another: `aggregate` when the target is coarser, `interpolate` when it is finer. Giving neither leaves that change with no rule of its own.

from

RankPattern · required

Levels the values are read at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

to

RankPattern · required

Levels the values are produced at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

Aggregate

How the values combine, when to is the coarser side.

Interpolate

How the values are spread out, when to is the finer side.

Interval

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Interval string:

IntervalString

The spacing written as one string.

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

IntervalString

string

An interval written as one string: a name (daily, weekly, 5min), space-separated terms (1d 3h), or an ISO 8601 duration (P1Y2M10D). Names are case-insensitive and accept the singular, the plural, and the adjective (day, days, daily).

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

IntervalParts

An interval written field by field. Fields left out count as zero, and the total has to be strictly forward.

years

integer | null · int64

Whole years.

months

integer | null · int64

Whole months.

days

integer | null · int64

Whole days.

hours

integer | null · int64

Whole hours.

minutes

integer | null · int64

Whole minutes.

seconds

integer | null · int64

Whole seconds.

ms

integer | null · int64

Whole milliseconds.

us

integer | null · int64

Whole microseconds.

Anchor

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Weekday, month, or instant:

string

A weekday, which anchors weekly grids; a month, which anchors yearly ones; or the date or timestamp the grid starts at.

Example 1: monday

Example 2: april

Example 3: 2024-01-06

Example 4: 2024-01-06T00:00:00Z

Partition

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Spacing:

IntervalString

The grid's spacing on its own.

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

PartitionBody

A coarser grid with its own spacing and start.

Interval

Spacing of this grid. Omit it and the name this entry sits under names the spacing, so {} is enough under a key like weekly.

Anchor

Where this grid's buckets start. Omit it for the usual start for the spacing.

Chain

string[] · minItems: 1

One roll-up path: identifier columns from finest to coarsest. At least one column.

Example: {"0": "store", "1": "city", "2": "country"}

Source

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: inline
	type = object · requires: uri
	type = object · requires: parquet

Properties for Inline rows:

The rows themselves, one array of values per column name. Every array has the same length, and each position across them is one row.

object · required

The rows themselves, one array of values per column name. Every array has the same length, and each position across them is one row.

Example 1:

{
  "time": ["2020-01-01", "2020-01-02", "2020-01-03"],
  "sales": [12, 9, 15]
}

Example 2:

{
  "time": ["2020-01-01", "2020-01-01", "2020-01-02", "2020-01-02"],
  "store": ["north", "south", "north", "south"],
  "sales": [12, 7, 9, 11],
  "on_promotion": [false, false, true, false]
}

Scalar

number | boolean | string | null

A single value: a number, a boolean, a string, or null for a missing observation. A JSON document may write null; a TOML one has no form for it.

Example 1: 12

Example 2: 1.5

Example 3: north

Example 4: true

Example 5: null

ParquetPaths

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = array

Properties for One path:

string

One file, or a glob matching several.

Example 1: sales.parquet

Example 2: sales/*.parquet

Covariate

Another timeseries family attached to this one, contributing extra variables. This timeseries family keeps its own series, grid, and density; the attached one only adds variables, matched onto the base's rows by `on`. A kept variable arrives under the name of the column it reads, unless `rename` says otherwise. Two variables arriving under the same name is an error when `only` or `rename` is given, and takes an `_rhs` suffix otherwise.

VersionedSchema · required

The attached timeseries family, written out here or pointed at elsewhere.

array | null

Which columns to match rows on. An empty list matches every attached row to every row of this timeseries family. Omit it and the request is rejected: spell the pairs out.

only

array | null

Which of the attached timeseries family's variables to keep, by the name they carry there. Omit it to keep all of them.

object | null

Names to give the kept variables, keyed by the name they carry on the attached timeseries family.

VersionedSchema

A schema document: one timeseries family, plus the `version` saying which schema format it is written in.

version

string · enum · required

Which schema format this document is written in.

Enum values:

0.1

0.2

0.3

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: columns, source, version
	type = object · requires: ref, version
	type = object · requires: version
	type = object · requires: version

Properties for Inline timeseries family:

A timeseries family written out in full: where its rows come from, plus what its columns mean.

Source · required

Where the timeseries family's rows come from.

object · required

The timeseries family's columns, keyed by name. Exactly one declares kind: "time".

version

string · const · required

Which schema format this document is written in.

Const value: 0.3

has_gaps

boolean | null

object | null

Roll-up paths, keyed by the name you give each one.

Covariate[]

Other timeseries families to attach, each contributing extra variables.

name

string | null

A name for the timeseries family, for your own reference.

description

string | null

What the timeseries family holds, for your own reference.

metadata

Anything you want to keep alongside the timeseries family. It is stored as written and plays no part in the forecast.

SchemaUri

string

Where another schema document lives: a timetrove://org/name reference, or a path to a schema file relative to the document naming it.

Example 1: timetrove://acme/sales

Example 2: ./sales.json

OnPair

One pair of columns to match rows on.

base

string · required

Column on the timeseries family the covariate is attached to.

attached

string · required

Column on the attached timeseries family.

ColumnName

string

Name of a column in a timeseries.

Selector

Selector for materializing a subset of a timeseries family. If omitted, every timeseries will be forecasted. An object with one entry per dimension, keyed by the level to forecast that dimension at: `"city"` takes the geography dimension at its city level, aggregating the finer levels below it. Each value is a pattern, narrowing which of that level's values to take: - `"any"` selects every value at that level. - `[value, ...]` selects concrete values. - `{ "from": value?, "to": value? }` selects a bounded or half-bounded range. A dimension with no entry is aggregated over entirely.

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = array
	type = object

Properties for Any:

SelectorAny · enum

Enum values:

any

Select every value at this column — the string "any".

SelectorPattern

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = array
	type = object

Properties for Any:

SelectorAny · enum

Enum values:

any

Select every value at this column — the string "any".

SelectorAny

string · enum

Enum values:

any

The string "any": select every value at a column.

SelectorRange

A range of values: `{ "from": …, "to": … }`. Both bounds are optional; give only one for a half-bounded range. The values match the column's type (number, string, or date).

from

Lower bound of the range; omit for an open lower end.

to

Upper bound of the range; omit for an open upper end.

Quantile

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = number
	type = string

Properties for Variant 1:

number · min: 0 · max: 1

InformationCutoffDatetimes

InformationCutoffDatetime[] · minItems: 1

A non-empty array of information cutoffs. For example ["latest"], an explicit date ["2025-01-31"], or a recurring schedule [{ "every": "3d" }].

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = object · requires: every

Properties for Latest observation:

LatestStr · enum

Enum values:

latest

The most recent point where every target is observed.

InformationCutoffDatetime

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = object · requires: every

Properties for Latest observation:

LatestStr · enum

Enum values:

latest

The most recent point where every target is observed.

LatestStr

string · enum

Enum values:

latest

The literal string "latest": use the most recent point at which the target is observed as the information cutoff.

Datetime

string · pattern: ^\d{4}-\d{2}-\d{2}([…

Example 1: 2025-01-04T00:00:00Z

Example 2: 2025-01-04T00:00:00+02:00

Example 3: 2025-01-04T00:00:00

Example 4: 2025-01-04 00:00:00

Example 5: 2025-01-04

RecurringCutoff

A recurring information cutoff: one cutoff every `every`, repeated across the series. Use this for backtesting or rolling-origin evaluation instead of listing every cutoff date by hand. `every` must be a whole multiple of the timeseries' calendar frequency. Each series produces cutoffs on the schedule phased from `start` or, when omitted, from the calendar grid's anchor — so every series lands on the same global schedule. Cutoffs are admitted within the series' own observed window; `end` caps it explicitly.

RelativeInterval · required

A forecast-geometry interval: either a whole number of the series' native frequency steps, or a [CalendarInterval] — never both.

start

Datetime · pattern: ^\d{4}-\d{2}-\d{2}([…

end

Datetime · pattern: ^\d{4}-\d{2}-\d{2}([…

RelativeInterval

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

CalendarInterval

string

A calendar interval: an ISO 8601 duration (P1Y2M10D, PT1H30M), a named interval (daily, 5min), or space-separated terms (1d 3h).

Example 1: P1Y2M10D

Example 2: PT1H30M

Example 3: daily

Example 4: 1d 3h

Leadtime

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

Context

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

Horizon

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

Span

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

ForecastTaskResponse

ResponseDataFrame · required

Long-format forecast dataframe: one row per (cutoff, horizon step).

array | null

Accuracy metrics, one entry per series whose actuals cover a whole forecast window. Present only when the request set compute_metrics.

ResponseDataFrame

Long-format forecast dataframe: one row per (cutoff, horizon step).

time

Datetime[] · required

Target time of the prediction: one step past cutoff, plus lead_time.

InformationCutoffDatetime[] · required

Information cutoff the prediction was made from, the last instant it saw.

lead_time

CalendarInterval[] · required

span

CalendarInterval[] · required

object · required

The dimensional columns — every identifier column declared by the schema (including hierarchy ancestors), keyed by source column name.

object · required

The targets

ColumnarData

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = array
	type = array
	type = array
	type = array
	type = array
	type = array

Properties for I64:

integer[]

ForecastDistributionResult

object · required

SeriesMetrics

Accuracy for one timeseries of the timeseries family, keyed by target column.

object · required

The series' identifier values, as the response dataframe's identifiers columns carry them.

object · required

IdentifierValue

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = null
	type = string
	type = integer

Properties for Null:

null

Metrics

Accuracy for one target: the distribution scored over the requested quantile levels, and the mean scored as a point forecast. A field is null where the metric does not apply — the CRPS under three levels, `mape` against a zero actual, a scaled metric whose actuals are all zero.

crps

number | null · double

scaled_crps

number | null · double

crps divided by the mean absolute actual over the scored windows.

mae

number | null · double

mape

number | null · double

Mean absolute percentage error as a fraction, not a percentage.

wape

number | null · double

mae divided by the mean absolute actual over the scored windows.

scaled_bias

number | null · double

Mean signed error, prediction - actual, divided by the mean absolute actual over the scored windows: negative when the forecast runs low.

Forecasting API

Schemas

TsFamilyForecastQuery

TimeseriesFamilySchema · required

A timeseries family written out in full: where its rows come from, plus what its columns mean.

targets

array | null · minItems: 1

The columns to forecast. Omit to forecast every column the schema declares with the "target" kind.

Default: null

Selector

Selector for materializing a subset of a timeseries family. If omitted, every timeseries will be forecasted.

"any" selects every value at that level.
[value, ...] selects concrete values.
{ "from": value?, "to": value? } selects a bounded or half-bounded range.

A dimension with no entry is aggregated over entirely.

Default: null

object

Default: {}

quantiles

array | null · unique

Quantile levels to forecast for every target, as numbers in [0, 1]; include "mean" to also request the mean. Omit for a default spread.

Default: null

compute_metrics

boolean

Default: false

InformationCutoffDatetime[] · minItems: 1

A non-empty array of information cutoffs. For example ["latest"], an explicit date ["2025-01-31"], or a recurring schedule [{ "every": "3d" }].

Default: ["latest"]

Leadtime

Gap held before the forecast starts, on top of the step separating the information cutoff from the first prediction's target time.

Default: 0

Context

How much history to feed the model before the information cutoff.

Default: null

Horizon

Total time window forecasted, measured from the end of the lead time.

Default: 1

Span

Target-time interval covered by each forecasted value (e.g. a span of 1d produces daily predictions, 3d produces 3-day buckets).

Default: 1

TimeseriesFamilySchema

A timeseries family written out in full: where its rows come from, plus what its columns mean.

Source · required

Where the timeseries family's rows come from.

object · required

The timeseries family's columns, keyed by name. Exactly one declares kind: "time".

has_gaps

boolean | null

object | null

Roll-up paths, keyed by the name you give each one.

Covariate[]

Other timeseries families to attach, each contributing extra variables.

name

string | null

A name for the timeseries family, for your own reference.

description

string | null

What the timeseries family holds, for your own reference.

metadata

Anything you want to keep alongside the timeseries family. It is stored as written and plays no part in the forecast.

Column

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	No specific criteria

Properties for Role shorthand:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Identifier:

Const value: identifier

Names which series a row belongs to, such as a store or a product.

BareKind

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Identifier:

Const value: identifier

Names which series a row belongs to, such as a store or a product.

FullColumn

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind

Properties for Identifier column:

Names which series a row belongs to.

kind

string · const · required

Const value: identifier

type

Type

Type of the column's values. Omit it and the type is read from the data; a type given here wins.

Example 1: int64

Example 2: float64

Example 3: string

Example 4: date32

Example 5: timestamp_us

Example 6: nullable<float64>

column

string | null

Column to read in the source data, when it differs from the name this declaration sits under. Cannot be combined with virtual.

virtual

Expr

Expression computing the column instead of reading it from the source. Cannot be combined with column. Not supported yet: a request declaring it is rejected.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

description

string | null

What the column means, for your own reference.

Type

string

A value type: bool, int32, int64, float32, float64, string, date32, or timestamp_us. Wrap one in nullable<...> to allow missing values, or in list<...> for a column of lists.

Example 1: int64

Example 2: float64

Example 3: string

Example 4: date32

Example 5: timestamp_us

Example 6: nullable<float64>

Expr

string

An expression: an aggregation (sum, mean, avg, min, max), a literal (0, 1.5, true), or a comma-separated tuple of those in parentheses.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

Known

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	type = object · requires: at

Properties for Named horizon:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Historical:

Const value: historical

Observed up to the cutoff only.

KnownTime

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Historical:

Const value: historical

Observed up to the cutoff only.

KnownAt

An observation time given as an expression. Not supported yet: a request declaring it is rejected.

at

Expr · required

When the value becomes observable, as an expression over the time column.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

Aggregate

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object · requires: expr

Properties for Aggregation:

Expr

The aggregation on its own.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

AggregateTable

An aggregation plus what it is allowed to read.

expr

Expr · required

How the values combine.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

complete

array | null

Roll-up paths whose levels have to be complete first: every level a row could exist at is filled in before the values combine.

imputed

boolean | null

Whether filled-in values feed the aggregation as well as recorded ones. Defaults to false.

Impute

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: const
	type = object · requires: locf
	type = object · requires: locb
	type = object · requires: rolling

Properties for Constant:

Fill every gap with the same value.

const

number | boolean | string · required

The value to fill with. A string keeps its own quotation marks inside the JSON string, as the examples show, and there is no null: to leave gaps empty, omit the rule instead.

Example 1: 0

Example 2: 1.5

Example 3: true

Example 4: "n/a"

GapFill

How far a carried value reaches.

max_gap

integer | null · uint64 · min: 0 · max: 4294967295

Longest run of consecutive missing values to fill, counted in grid steps. Omit it to fill runs of any length.

Rolling

A statistic over the values around each gap.

RollingStat · required

Which statistic to compute.

size

integer · uint64 · min: 1 · max: 4294967295 · required

How many grid steps the window spans. A centred window needs an odd number, so it has as many steps on each side.

RollingAlignment

Where the window sits relative to the value being filled. Defaults to trailing. centered needs an odd size.

RollingStat

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Mean:

Const value: mean

Arithmetic mean of the window.

RollingAlignment

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string

Properties for Trailing:

Const value: trailing

The window covers the steps before it.

Interpolate

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	type = object · requires: proportional_by

Properties for Named method:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Broadcast:

Const value: broadcast

Copy the coarser value onto every finer row.

InterpolateName

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Broadcast:

Const value: broadcast

Copy the coarser value onto every finer row.

ProportionalBy

A split weighted by another column.

proportional_by

string · required

Column whose values weight the split.

Rule

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: at, impute
	type = object · requires: from, to

Properties for Filling rule:

How to fill missing values at the levels it names.

ImputeRule

at

RankPattern · required

Levels this rule applies at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

Impute · required

How the missing values are filled there.

ImputeRule

How to fill missing values at named levels.

at

RankPattern · required

Levels this rule applies at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

Impute · required

How the missing values are filled there.

RankPattern

string

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

TransitionRule

How values move from one level to another: `aggregate` when the target is coarser, `interpolate` when it is finer. Giving neither leaves that change with no rule of its own.

from

RankPattern · required

Levels the values are read at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

to

RankPattern · required

Levels the values are produced at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

Aggregate

How the values combine, when to is the coarser side.

Interpolate

How the values are spread out, when to is the finer side.

Interval

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Interval string:

IntervalString

The spacing written as one string.

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

IntervalString

string

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

IntervalParts

An interval written field by field. Fields left out count as zero, and the total has to be strictly forward.

years

integer | null · int64

Whole years.

months

integer | null · int64

Whole months.

days

integer | null · int64

Whole days.

hours

integer | null · int64

Whole hours.

minutes

integer | null · int64

Whole minutes.

seconds

integer | null · int64

Whole seconds.

ms

integer | null · int64

Whole milliseconds.

us

integer | null · int64

Whole microseconds.

Anchor

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Weekday, month, or instant:

string

A weekday, which anchors weekly grids; a month, which anchors yearly ones; or the date or timestamp the grid starts at.

Example 1: monday

Example 2: april

Example 3: 2024-01-06

Example 4: 2024-01-06T00:00:00Z

Partition

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Spacing:

IntervalString

The grid's spacing on its own.

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

PartitionBody

A coarser grid with its own spacing and start.

Interval

Spacing of this grid. Omit it and the name this entry sits under names the spacing, so {} is enough under a key like weekly.

Anchor

Where this grid's buckets start. Omit it for the usual start for the spacing.

Chain

string[] · minItems: 1

One roll-up path: identifier columns from finest to coarsest. At least one column.

Example: {"0": "store", "1": "city", "2": "country"}{"0": "store", "1": "city", "2": "country"}

Source

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: inline
	type = object · requires: uri
	type = object · requires: parquet

Properties for Inline rows:

The rows themselves, one array of values per column name. Every array has the same length, and each position across them is one row.

object · required

The rows themselves, one array of values per column name. Every array has the same length, and each position across them is one row.

Example 1:

{
  "time": ["2020-01-01", "2020-01-02", "2020-01-03"],
  "sales": [12, 9, 15]
}{
  "time": ["2020-01-01", "2020-01-02", "2020-01-03"],
  "sales": [12, 9, 15]
}

Example 2:

{
  "time": ["2020-01-01", "2020-01-01", "2020-01-02", "2020-01-02"],
  "store": ["north", "south", "north", "south"],
  "sales": [12, 7, 9, 11],
  "on_promotion": [false, false, true, false]
}{
  "time": ["2020-01-01", "2020-01-01", "2020-01-02", "2020-01-02"],
  "store": ["north", "south", "north", "south"],
  "sales": [12, 7, 9, 11],
  "on_promotion": [false, false, true, false]
}

Scalar

number | boolean | string | null

A single value: a number, a boolean, a string, or null for a missing observation. A JSON document may write null; a TOML one has no form for it.

Example 1: 12

Example 2: 1.5

Example 3: north

Example 4: true

Example 5: null

ParquetPaths

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = array

Properties for One path:

string

One file, or a glob matching several.

Example 1: sales.parquet

Example 2: sales/*.parquet

Covariate

VersionedSchema · required

The attached timeseries family, written out here or pointed at elsewhere.

array | null

Which columns to match rows on. An empty list matches every attached row to every row of this timeseries family. Omit it and the request is rejected: spell the pairs out.

only

array | null

Which of the attached timeseries family's variables to keep, by the name they carry there. Omit it to keep all of them.

object | null

Names to give the kept variables, keyed by the name they carry on the attached timeseries family.

VersionedSchema

A schema document: one timeseries family, plus the `version` saying which schema format it is written in.

version

string · enum · required

Which schema format this document is written in.

Enum values:

0.1

0.2

0.3

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: columns, source, version
	type = object · requires: ref, version
	type = object · requires: version
	type = object · requires: version

Properties for Inline timeseries family:

A timeseries family written out in full: where its rows come from, plus what its columns mean.

Source · required

Where the timeseries family's rows come from.

object · required

The timeseries family's columns, keyed by name. Exactly one declares kind: "time".

version

string · const · required

Which schema format this document is written in.

Const value: 0.3

has_gaps

boolean | null

object | null

Roll-up paths, keyed by the name you give each one.

Covariate[]

Other timeseries families to attach, each contributing extra variables.

name

string | null

A name for the timeseries family, for your own reference.

description

string | null

What the timeseries family holds, for your own reference.

metadata

Anything you want to keep alongside the timeseries family. It is stored as written and plays no part in the forecast.

SchemaUri

string

Where another schema document lives: a timetrove://org/name reference, or a path to a schema file relative to the document naming it.

Example 1: timetrove://acme/sales

Example 2: ./sales.json

OnPair

One pair of columns to match rows on.

base

string · required

Column on the timeseries family the covariate is attached to.

attached

string · required

Column on the attached timeseries family.

ColumnName

string

Name of a column in a timeseries.

Selector

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = array
	type = object

Properties for Any:

SelectorAny · enum

Enum values:

any

Select every value at this column — the string "any".

SelectorPattern

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = array
	type = object

Properties for Any:

SelectorAny · enum

Enum values:

any

Select every value at this column — the string "any".

SelectorAny

string · enum

Enum values:

any

The string "any": select every value at a column.

SelectorRange

A range of values: `{ "from": …, "to": … }`. Both bounds are optional; give only one for a half-bounded range. The values match the column's type (number, string, or date).

from

Lower bound of the range; omit for an open lower end.

to

Upper bound of the range; omit for an open upper end.

Quantile

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = number
	type = string

Properties for Variant 1:

number · min: 0 · max: 1

InformationCutoffDatetimes

InformationCutoffDatetime[] · minItems: 1

A non-empty array of information cutoffs. For example ["latest"], an explicit date ["2025-01-31"], or a recurring schedule [{ "every": "3d" }].

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = object · requires: every

Properties for Latest observation:

LatestStr · enum

Enum values:

latest

The most recent point where every target is observed.

InformationCutoffDatetime

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = object · requires: every

Properties for Latest observation:

LatestStr · enum

Enum values:

latest

The most recent point where every target is observed.

LatestStr

string · enum

Enum values:

latest

The literal string "latest": use the most recent point at which the target is observed as the information cutoff.

Datetime

string · pattern: ^\d{4}-\d{2}-\d{2}([…

Example 1: 2025-01-04T00:00:00Z

Example 2: 2025-01-04T00:00:00+02:00

Example 3: 2025-01-04T00:00:00

Example 4: 2025-01-04 00:00:00

Example 5: 2025-01-04

RecurringCutoff

RelativeInterval · required

A forecast-geometry interval: either a whole number of the series' native frequency steps, or a [CalendarInterval] — never both.

start

Datetime · pattern: ^\d{4}-\d{2}-\d{2}([…

end

Datetime · pattern: ^\d{4}-\d{2}-\d{2}([…

RelativeInterval

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

CalendarInterval

string

A calendar interval: an ISO 8601 duration (P1Y2M10D, PT1H30M), a named interval (daily, 5min), or space-separated terms (1d 3h).

Example 1: P1Y2M10D

Example 2: PT1H30M

Example 3: daily

Example 4: 1d 3h

Leadtime

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

Context

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

Horizon

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

Span

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of native frequency steps (e.g. 3).

ForecastTaskResponse

ResponseDataFrame · required

Long-format forecast dataframe: one row per (cutoff, horizon step).

array | null

Accuracy metrics, one entry per series whose actuals cover a whole forecast window. Present only when the request set compute_metrics.

ResponseDataFrame

Long-format forecast dataframe: one row per (cutoff, horizon step).

time

Datetime[] · required

Target time of the prediction: one step past cutoff, plus lead_time.

InformationCutoffDatetime[] · required

Information cutoff the prediction was made from, the last instant it saw.

lead_time

CalendarInterval[] · required

span

CalendarInterval[] · required

object · required

The dimensional columns — every identifier column declared by the schema (including hierarchy ancestors), keyed by source column name.

object · required

The targets

ColumnarData

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = array
	type = array
	type = array
	type = array
	type = array
	type = array

Properties for I64:

integer[]

ForecastDistributionResult

object · required

SeriesMetrics

Accuracy for one timeseries of the timeseries family, keyed by target column.

object · required

The series' identifier values, as the response dataframe's identifiers columns carry them.

object · required

IdentifierValue

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = null
	type = string
	type = integer

Properties for Null:

null

Metrics

crps

number | null · double

scaled_crps

number | null · double

crps divided by the mean absolute actual over the scored windows.

mae

number | null · double

mape

number | null · double

Mean absolute percentage error as a fraction, not a percentage.

wape

number | null · double

mae divided by the mean absolute actual over the scored windows.

scaled_bias

number | null · double

Mean signed error, prediction - actual, divided by the mean absolute actual over the scored windows: negative when the forecast runs low.