Blog · · EN
bankproducts.json — 4 months later
What we learned, why zero banks published the format, and what a v2 spec would need.
/.well-known/bankproducts.json: one JSON file per bank at a well-known URL, like security.txt but for pricing. Four months later, zero banks have published such a file — but our own schema has grown from 6 banks / 128 products / 349 fees to 421 banks, 2,929 products, 6,719 fees and 2,376 interest rates. What the schema taught us about itself, forced through by 420-odd real banks: prices are one thing, interest rates are another. Source citations belong at the row level, not the file level. Claims need a verifiable flag. And the single most important rule for any LLM-populated data spec — learned the hard way through three real near-misses — is NULL > a plausible invention.
Recap: what the March post said
On 31 March 2026 we spent a weekend parsing six Swiss bank price schedules (108 PDF pages, 128 products, 349 fees) and derived a proposal from it: /.well-known/bankproducts.json. Every bank places a machine-readable product catalogue at a known URL. One file. One URL. No API, no contract, no scraping. Precedents: security.txt, openid-configuration, robots.txt. The JSON schema was at v1.0.
The post closed with a clear ask: "One bank publishing this file would prove the concept. Two would make it a pattern. Ten would make it a standard."
Four months later: the reality
| March 2026 | August 2026 | |
|---|---|---|
| Banks in the DB | 6 | 421 |
| Products | 128 | 2,929 |
| Fees | 349 | 6,719 |
| Interest rates | 0 | 2,376 |
| Narrative claims | 0 | 1,160 |
| Source documents | ≈10 | 931 |
| Schema version | v1.0 | v3 |
| Banks with LEI | ? | 410 (97%) |
Banks that published a /.well-known/bankproducts.json | 0 | 0 |
The last row is the honest one. The format was picked up by no bank. The DB was built by us — through a crawler maintained by an external contractor, and through loader sessions where every bank gets its own SQL file. The exact opposite of the "every bank publishes for itself" promise.
The exercise wasn't wasted, though — the schema evolved massively under the pressure of 420 real banks. And that evolution is the real yield: a v2 proposal that knows where v1 was wrong.
What the schema itself taught us
1. Interest rates are not fees
The March version had a fees array per product. Rates showed up nowhere. Four months in, we have 2,376 interest rates in a dedicated interest_rate table — with tenor_months, tier_floor/tier_ceiling, currency and a rate_type enum (savings, mortgage_rate, term_deposit, …). A savings account isn't a fee carrier, it's a rate carrier.
v2 consequence: either a second rates array per product, or a second file /.well-known/bankrates.json. Either is cleaner than "everything is a fee with different semantics".
2. The source citation belongs on the row, not on the file
The March post had a single source object at the file head. In reality every single fee wants a source_page reference (for PDFs) or a source_url (for HTML pricing). Why: a mid-sized bank typically has three valid pricing documents live in parallel — base fees, card conditions, interest rates — and an LLM or compliance auditor needs page-level, not file-level, provenance.
That's the real "trust killer feature". Without per-item citation the file is just a nicely-formatted list of claims. With per-item citation, it becomes verifiable.
3. Claims need a verifiable flag
Four LLMs independently confirmed (see llm-validation/2026-05-31.md): the biggest difference between a price list and a price-list-with-a-story is the distinction fact vs. marketing. Example:
- verifiable=1: "ZKB has a AAA credit rating from S&P" (checkable at S&P Global)
- verifiable=0: "We are the most customer-friendly bank in Switzerland" (marketing self-report)
The flag changes the language an AI agent uses to cite the claim. Both belong in the file, but labelled differently. Our claim table today has 1,160 rows, 82% of them verifiable=1. The v1 spec did not carry this concept.
4. Packages need content, not just a name
The March version listed package as a product category — without saying what's in the package. Reality check: "ZKB inklusiv Silber CHF 6/month" is worthless if it isn't clear that private account + savings account + Visa Debit + standard credit card + e-banking are bundled. We have 109 packages in the DB, each with package_item rows pointing at the included product IDs.
v2: package products carry an included: [product_id, product_id, …] field.
5. "On request" is a legitimate answer
A big gap between wish-world and reality: many banks intentionally don't publish their rates. In our Q3 inventory we found 240 blank cells across 64 banks — 165 of them with an explicit "on request" marker (see What Swiss banks don't publish). At 31 banks, the Pillar-3a rate is never public.
v2 has to represent this canonically: amount: null with a note field is allowed and means "the bank does not publish this" — not "we haven't parsed it yet". That's an important semantic difference for an AI agent that needs to distinguish "don't know" from "know that it isn't public".
6. ACTUS contract type as a bridge to the finance industry
Between March and today we mapped 30 product categories to 11 ACTUS contract types (UMP, PAM, ANN, CSH, STK, …). ACTUS is the international ISO-adjacent standard for financial contracts. A savings account is a UMP, a fixed-rate mortgage is an ANN. That bridge makes our data directly compatible with any ACTUS-based analysis (cashflow modelling, ALM, balance-sheet simulation).
v2: optional actus_type field per product. Not required, but a door to the institutional world.
7. Identity is layered
March had bank.id: "zkb". Today reality: a bank carries five identifiers, each with a distinct purpose:
- LEI (GLEIF, international) — for cross-system joins
- UID (Zefix, CH-national) — for commercial-register references
- BIC (SWIFT) — for payments
- SIC IID (SIX, CH clearing) — for interbank clearing
- BPG (our internal opaque code, FIGI-inspired, with check digit) — survives renames, mergers, rebrands
v2 must put LEI first (97% coverage in our DB, globally unique). The rest is supplementary.
The core principle — learned the hard way
NULL is better than a plausible-sounding invention.
This one rule alone deserves its own blog post. It's the single most important lesson of the last four months. Three real near-misses, all from LLM-generated loader sessions:
- "Frankly Technologie AG" — a plausible-sounding legal entity for the ZKB brand Frankly. Doesn't exist. Zefix doesn't know it. An LLM had hallucinated it during a loader session because the question "who is Frankly's legal entity?" didn't allow an empty answer. It almost landed in the DB. Journal atom #354.
- 11 fabricated cantonal-bank UIDs — hand-loaded cantonal-bank files contained UIDs in the format
CHE-105.939.310that, when checked against Zefix, did not exist. All 11 were LLM-signature numbers ("looks like a UID"). Journal atom #357. - LEI fallback to parent cooperative — for Raiffeisen member banks without their own LEI, an earlier enrichment run had stamped in the Raiffeisen Schweiz parent LEI. The downstream GLEIF lookup then returned the wrong UID. Journal atom #367.
The common thread: an LLM is trained to answer the question, not to leave it open. If a data spec doesn't carry an explicit rule that null is the correct answer when the truth is unknown, an LLM will 100% of the time fill it with something plausible. And plausible is worse than wrong, because it doesn't trip downstream validators.
The v1 spec did not have this rule. The v2 spec must carry it normatively, in capital letters, at the file head. It applies to every field: name, uid, lei, amount, rate, all of them.
What a v2 could look like
Skeleton — not complete, but the new elements are visible:
{
"$schema": "https://bankproducts.info/schema/v2.json",
"version": "2.0",
"generated_at": "2026-08-05",
"bank": {
"id": "zkb",
"lei": "165GRDQ39W63PHVONY02", // NEW: LEI as primary ID
"uid": "CHE-105.887.640",
"name": "Zürcher Kantonalbank",
"country": "CH",
"bank_type": "cantonal_bank"
},
"products": [
{
"id": "visa_debit",
"category": "debit_card",
"actus_type": "SVC", // NEW: ACTUS bridge (optional)
"name": "ZKB Visa Debit Card",
"fees": [
{
"type": "fx_markup",
"amount": 1.25, "currency": "percent", "frequency": "per_txn",
"note": "Max CHF 1.50 per transaction",
"source": { // NEW: source PER row
"url": "https://www.zkb.ch/...prices.pdf",
"page": 13
}
},
{
"type": "atm_abroad",
"amount": null, // NEW: null is allowed
"note": "on request — depends on package",
"source": { "url": "https://www.zkb.ch/...package-info" }
}
]
},
{
"id": "sparkonto",
"category": "savings_account",
"actus_type": "UMP",
"rates": [ // NEW: rates alongside fees
{ "rate_type": "savings", "rate": 0.10, "currency": "CHF",
"tier_floor": 0, "tier_ceiling": 50000,
"valid_from": "2026-07-01",
"source": { "url": "...", "page": 8 } }
]
},
{
"id": "inklusiv_silber",
"category": "package",
"fees": [ { "type": "base_fee", "amount": 6.0, "currency": "CHF",
"frequency": "monthly" } ],
"included": [ // NEW: package contents
"privatkonto", "sparkonto", "visa_debit",
"credit_standard", "ebanking"
]
}
],
"claims": [ // NEW: verifiable assertions
{
"category": "safety",
"key": "credit_rating",
"value": "AAA",
"verifiable": true,
"source_url": "https://www.spglobal.com/ratings/en/..."
},
{
"category": "digital",
"key": "app_rating_apple",
"value": "4.7",
"verifiable": true,
"source_url": "https://apps.apple.com/ch/app/..."
}
]
}
Why zero banks adopted — and what that means
Four honest reasons:
- No business case. A bank publishes prices in a PDF today because FINMA implicitly expects it. No additional customer results from a JSON file. Until someone builds book-value aggregate volume on top of it, there's no economic traction.
- No push. PSD3 is in the making in the EU, but the detailed publication-format requirements aren't ratified. If PSD3 explicitly mandates JSON in a normalised structure (rather than "published on the website"), that changes abruptly.
- We became the interim solution. Our
api.bankproducts.infoaggregates 421 banks. An AI agent or a compliance query today has no operational reason to wait for per-bank publication — the aggregation already exists. Paradoxically, that weakens the push for self-publication. - Internal friction. For a bank, publishing a
bankproducts.jsonmeans internal sign-off, a legal review, a deployment path. Costs are real (even if small), benefit is diffuse.
The realistic path forward is three-part:
- A frontrunner. A cantonal bank or a neobank that publishes out of ESG transparency or marketing motives. One is enough — it becomes referenceable in RFPs.
- A regulatory trigger. PSD3 explicit, or a FINMA recommendation for machine-readable fee publication. That's the most likely accelerant.
- An LLM traffic threshold. When 5-10% of retail-bank-product discovery traffic runs via LLM, self-publication becomes an SEO equivalent. We're probably 12-18 months away from that.
What remains
The March proposal was naive in the details and right in principle. The details we've corrected in hindsight — through 421 real banks, three near-misses and a schema that evolved under real-world pressure in ways we couldn't have foreseen at a desk.
The principle stands: The data exists. It's public. The access path to it is the scandal. What our post missed — and what these four months made crisp — is the anti-fabrication rule as a normative core. Any data spec that gets populated by LLMs must explicitly allow null as a correct answer and normatively recommend it. Otherwise the LLM fills the gap with a plausible invention, and plausible is worse than wrong.
If a bank publishes its /.well-known/bankproducts.json along the v2 skeleton, tell us immediately: roman@bankproducts.info. Until then, the crawler keeps running.