Datasets
A Dataset sells the truth of its records: what each value means, where it came from, and when it was true.
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.
plugatlas.com is a Startup that sells records of public EV charging stations. A lookup by location returns each station with its connectors, power, operator, price, and live status. Route planners call it from code, and travel Agents call it through MCP.
Coverage and freshness
Coverage names a population and a date range, never "complete". plugatlas.com covers every public station in 31 countries, refreshed at least daily. A station in an unlisted country is out of coverage, and the reference says so before a Customer finds out by a miss.
Each record carries three times, because each answers a different question:
| Field | Question it answers |
|---|---|
observedAt | When the fact was true |
publishedAt | When the Source published it |
refreshedAt | When the Dataset last read that Source |
A station read an hour ago from a feed published last month is a fresh read of an old fact. Customers filter on the time that matters to them.
Sources and provenance
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). An Integration connects an outside Source with its credentials.
Every value records its Source. When two Sources disagree on a station's power, a declared selection rule picks the answer and keeps the losing observation. Enrich adds fields to an existing Thing the same way: identity stays, and each new value names its origin.
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.
Lookup, search, and bulk
Three access shapes answer three questions, and each carries its own guarantee.
| Shape | Question | Result |
|---|---|---|
| Lookup | What is true of this key? | Zero or more records for one key, such as a location |
| Search | Which records match these criteria? | A ranked page of records |
| Bulk | Give me the whole slice | Every record in a scope, at one refreshedAt |
A lookup with no match returns an empty result, not an error. The Offer states whether a miss counts as usage, and the Meter follows the Offer, never the HTTP status.
Covered before charged
Any lookup can run first in the try Mode, which charges nothing. The preview answers whether the key is in coverage, what the call costs, and how many Meter units it draws. An Agent buying on its own checks coverage and price across Datasets before it spends.
A Dataset earns on a done Action. A key outside coverage returns refused and costs the Customer nothing.
Product Templates
The Dataset API Product Template sells keyed lookups per call to developers and their Agents. The Directory Product Template sells listings in a Dataset that buyers browse free.
Next
Agents covers the Product that acts on Datasets and Software for its Customer.