The contracts
Each record a module gives back holds the contract of its kind, Bid or Prospect, version 1, field by field.
Tommos checks each record against the contract of its kind. A record that fails is refused with its reason, and the
others go on (check d). The builders aBid and aProspect of the tools
make a record of the contract and say why one fails.
The contracts are JSON Schemas, published at https://app.tommos.ai/modules/contracts/bid.v1.json and
https://app.tommos.ai/modules/contracts/prospect.v1.json, and in the tools under contracts/.
Bid, version 1
A bid is one record per source and key.
| Field | Required | What it holds |
|---|---|---|
source | yes | Where the bid comes from: one of the manifest's record_sources, such as fictional-register. Never highergov, nor a source another module of the workspace names |
key | yes | The bid's own id at its source, such as the notice's id, at most 200 characters |
matched | yes | The rule of your module that took this bid, as a fact: «an open notice of the fictional register», «CPV 72254, software testing» |
title | yes | The notice's own title, at most 500 characters |
buyer | yes | { "name": "...", "key": "...", "type": "..." }; name is required |
source_url | yes | The notice on the source's own site, http or https |
contact_email | no | The buyer's contact, an email address |
due_date | no | The day bids are due, YYYY-MM-DD |
posted_date | no | The day the notice was posted, YYYY-MM-DD |
summary | no | A short text of the notice |
description | no | The notice's whole text, at most 100000 characters |
documents | no | Each file of the notice: { "name": "...", "url": "..." }, at most 100 |
value_estimate | no | { "low": 1000, "high": 5000, "currency": "GBP" }; currency is required, ISO 4217 |
country | no | The buyer's country, ISO 3166 alpha-2: GB, US. The log of Tommo Bids shows its flag |
naics, cpv, opp_type | no | The notice's codes and its kind of procedure |
place | no | { "city": "...", "region": "..." } |
A bid of the example's fictional register (no buyer, notice or amount in it is real):
{
"source": "fictional-register",
"key": "FN-0001",
"matched": "an open notice of the fictional register",
"title": "Testing of the citizen portal (fictional)",
"buyer": { "name": "The Borough of Nowhere (fictional)" },
"due_date": "2026-12-01",
"posted_date": "2026-11-09",
"source_url": "https://github.com/TommosCRM/tommos-module-template/blob/main/data/fictional-notices.json#FN-0001",
"description": "A fictional notice: the borough asks for the testing of its citizen portal before it opens.",
"value_estimate": { "low": 40000, "high": 40000, "currency": "GBP" }
}A record never carries a secret: neither the value of a secret of the source, nor a link with a credential in its
query (such as ?token=). Tommos refuses such a record with its reason.
Prospect, version 1
A prospect is one company, one record per module and domain. Two modules that find the same domain make one card on the board Prospecting, with the evidence of both.
| Field | Required | What it holds |
|---|---|---|
domain | yes | The company's own website: lower case, no www, no path, such as acme.io |
name | yes | The company's name, at most 300 characters |
matched | yes | The rule of your module that took this company, as a fact |
evidence | yes | 1 to 50 facts: { "what": "...", "url": "...", "date": "YYYY-MM-DD", "quote": "..." }; what and url are required |
segment | no | A segment your module gives as a fact, at most 100 characters |
score | no | A number your module gives as a fact |
facts | no | The value of each fact the manifest names that the record knows, by its key: { "round": "Seed" }. See Facts |
country | no | ISO 3166 alpha-2 |
people | no | Each person you know: { "name": "...", "title": "...", "email": "...", "url": "..." } |
Evidence is a fact, never an opinion: what happened, the link where it stands, its day, and a quote of the source's own words.
{
"domain": "jobworth.io",
"name": "JobWorth",
"matched": "a Show HN launch with its own website",
"evidence": [
{
"what": "Launched on Hacker News (Show HN)",
"url": "https://news.ycombinator.com/item?id=50453700",
"date": "2026-11-11",
"quote": "Show HN: JobWorth, paste a job description, see how hard it is to get"
}
],
"score": 1
}Facts
A prospect module names its facts in the manifest: at most six, each with a key, a label and a
kind. A record carries a value for each fact it knows, under facts, by the fact's key. A record that knows no fact
leaves facts out. Give a fact only when the source states it; a fact is never a guess.
| Kind | The value | An example |
|---|---|---|
text | A text, at most 300 characters | "Seed" |
money | An amount and its currency, ISO 4217 | { "amount": 2500000, "currency": "USD" } |
count | A whole number, 0 or more | 12 |
date | A day, YYYY-MM-DD | "2026-11-17" |
The prospect example names round (text) and amount (money). It takes them only from the words of the launch's own
title. A record of its fictional example:
{
"domain": "quayside.example",
"name": "Quayside (fictional)",
"matched": "a Show HN launch with its own website",
"evidence": [
{
"what": "Launched on Hacker News (Show HN)",
"url": "https://news.ycombinator.com/item?id=fictional-2",
"date": "2026-11-17",
"quote": "Show HN: Quayside (fictional) – we raised $2.5M in a Seed round to test ports"
}
],
"score": 3,
"facts": { "round": "Seed", "amount": { "amount": 2500000, "currency": "USD" } }
}Tommos keeps the facts with the evidence of the company, with their labels. A card on the board Prospecting shows the first two facts the manifest names; the company's page shows all of them.
Tommos refuses a record that carries a fact the manifest does not name, or a value of another kind, with its reason
(check d): facts.round is not a value of the kind count: facts.round must be a whole number.
A bid carries no facts.