Get started
DocumentationConcepts

Observation

Source

One figure, parsed out of one document, at one moment. The atom of the record.

witness.observation is append-only. An observation is never edited and never deleted, so anything derived from it can be recomputed and checked later.

Fields

FieldMeaning
idSerial id, the thing /api/v1/observations/{id}/proof takes
fetchIdThe read this came out of
skuIdWhat was priced
dimensionIdWhat it was priced by
amountUsdThe figure, numeric(14,6)
observedAtWhen it was read
derivedWhether Vitna computed this rather than read it
derivationHow, when derived is true
locatorWhere in the document it was found
parserVersionWhich version of the adapter read it

One figure per cell per read

A unique index on the fetch, the sku, the dimension and the context band means one read of one document yields at most one figure for any one cell. A page that lists the same model twice cannot produce two conflicting observations from a single fetch.

Derived figures announce themselves

Some numbers are not printed on the page. A provider that prices a 20-minute sandbox session has an hourly rate implied but not published, and Vitna computes it.

A database constraint requires derivation to be non-null whenever derived is true, so a computed figure cannot enter the record without saying how it was computed. derived travels all the way out to the API, on every tape row and every spread entry.

locator and parserVersion exist for the argument you will have later

When a figure looks wrong, the question is always the same: did the provider change the price, or did Vitna misread the page? locator says where in the document the parser looked and parserVersion says which parser looked there, so that question is answerable a year later against an archived document rather than debated.

From observation to price

An observation is a reading, not yet a price. Readings accumulate into price periods, and change detection publishes a move only on the second consistent read.