Anatomy of a data product
A Dataset sells the truth of its records: one Noun, built from Sources and Resources, each value with its origin and its times, delivered and metered.
A Dataset is a Product of curated Things of one Noun, with a promise that they are true. SoftwareBuilder ships it through the same Interfaces as any Software.
The promise
A Customer buys a Dataset to decide something, or to run its own code on the answers. The promise has three parts: what each value means, where it came from, and when it was true. A plausible value that breaks any part breaks the promise.
Ratebook sells US sales-tax rates. A lookup by address returns each jurisdiction with its rate, its share, its effective date and its authority. Checkouts call it from code, and shopping agents call it through MCP.
One declaration
---
$type: [Dataset, API]
nouns: [Rate]
sources: [state-bulletins, county-ordinances]
refresh: daily
coverage: [Every US taxing jurisdiction]
---
A rate for any US address in under 100 milliseconds.nouns names exactly one Noun. $type: ships the same records as lookups on the API and as MCP tools, with no second definition.
Built from Sources and Resources
A Source is what a Dataset draws on but did not build. It is owned (the Startup collects it), wrapped (another party's feed, under its terms) or recruited (people paid to supply it). Each record from a Source is a Resource, a Thing whose home is at that Source, in one of three modes.
mode | Who leads | Ratebook's example |
|---|---|---|
upstream | The Source leads; reads go through to it and a mirror is kept | A state's published rate service |
mirrored | A copy imported from a read-only Source | A county's ordinance file, read each day |
owned | db.sb leads | The district boundaries Ratebook draws itself |
An Integration connects a wrapped Source with its credentials. Sources and refresh covers each mode, the selection rule, and the schedule.
Every value with its origin
Every value records its Source and three times: when it was true, when the Source published it, and when the Dataset last read it. Any record reads as it stood at an earlier moment. Provenance and as-of reads cover both.
Licensing is part of the promise, because the right to read a Source is not the right to resell it. A Dataset enters Live only when every Source is licensed, collected within its terms, or synthetic.
Coverage before charge
Coverage names a population and a date range, never "complete". Any lookup can run first as a free coverage check, so a key outside coverage costs nothing. Coverage shows the check and the published coverage map.
Delivered four ways
| Way | Question | Read |
|---|---|---|
| Lookup | What is true of this key? | Zero or more records for one key, such as an address |
| Search | Which records match these criteria? | A ranked page of records |
| Bulk and warehouse | Give me the whole slice | Every record in a scope, on a schedule |
| Feed of changes | What changed since the last read? | Each change as an Event |
A lookup with no match returns an empty result, not an error, and costs nothing. Delivery covers each way and how it is priced.
Product Templates
The Dataset API Product Template sells keyed lookups per call to developers and their agents, with free misses and a free allowance per key. The Directory Product Template sells listings in a Dataset that buyers browse free.
Next
Life of a lookup follows one call through every part above.