[DBIP] Seven columns are reserved for the team's automation and hold 0–13% real data; run the scripts, open the fields, or drop the columns

[EazyHood]

Proposal type: Modify column; Other (decision on columns reserved for automation)

Affected scope (files/folders/chains): references/offers/sdks.csv (latestKnownVersion, latestKnownReleaseDate, maintainer, license); references/offers/apis.csv (verifiedUptime, verifiedLatency, verifiedBlocksBehindAvg); wiki pages SDKs and APIs

Motivation / problem statement

Seven columns are documented as reserved for the Chain.Love team's automation — the SDKs page says of the four SDK fields "Fields reserved for automation scripts from Chain.Love team - fetching this information from the action buttons link", and the APIs page describes the three verified* columns as kept by the team for provider performance history. Measured on current main, the automation has populated almost none of them:

column                         real   sentinel   blank   rows
apis   verifiedUptime             0    384 NULL      6    390
apis   verifiedLatency            0    384 NULL      6    390
apis   verifiedBlocksBehindAvg    0    384 NULL      6    390
sdks   latestKnownVersion         9    120 TBD      44    173
sdks   latestKnownReleaseDate     9    120 TBD      44    173
sdks   maintainer                16    113 TBD      44    173
sdks   license                   23    106 TBD      44    173

The table is the offers master, which is where the reservation is written. The same four columns exist in every network's sdks.csv and carry a further 77 TBD cells at listing level (20 / 20 / 20 / 17), included in the 685 counted in #3557.

So the reservation is doing two things at once: it keeps contributors out of seven columns, and it keeps the columns empty. For 74 of the 173 SDK rows the action-button link is a GitHub repository, where license, the latest release tag and date, and the owning organisation are one API call each — the fields could be filled today, by a script or by hand, and are not.

This is the decision that #2683 (NULL/null) and #3557 (TBD) both stop short of: those normalize the sentinel spelling; this one asks what the columns are for.

What the site publishes

@CodeRabbit-byte measured this in the thread below and I reproduced it at e83cde0 with the json-tools scripts at 5f89146. The four SDK columns are not internal: meta/columns.json defines them as user-facing table columns with labels and filters (Latest Version, Release Date and Maintainer as searchableMultiSelect, License as select). After csv_to_json.py fans the offer rows out across the networks, this is what those facets contain:

published sdks listing rows: 4381, on all 155 networks

column                      TBD    real   null   TBD share
license                    4106     275      0     93.7%
latestKnownVersion         4166     215      0     95.1%
latestKnownReleaseDate     4166     215      0     95.1%
maintainer                 3981     400      0     90.9%

In the License filter, TBD outnumbers Apache-2.0 4106 to 244 and MIT 4106 to 26.

The zero in the null column is not the data; it is the converter. tools/csv_to_json.py on json-tools carries SDK_TBD_FIELDS = (latestKnownVersion, latestKnownReleaseDate, maintainer, license) and ensure_sdks_tbd_fields(), called for every network, which writes the string TBD into any of the four that is missing, None or blank (introduced in 74d50e1, #563, February). Traced per published row: 98 TBD per column come from cells that are blank in the CSVs, 17-20 from listing rows, 2 from listing-only rows with no master entry, and the rest from the TBD in the offers master. So the site shows TBD for these four fields whenever a value is absent, however the CSV spells the absence. Two consequences:

• Blanking the 536 TBD cells that [DBIP] TBD acts as a missing-value sentinel in 685 cells across five categories; the Style Guide reserves it for internal use and three wiki examples teach it anyway #3557 holds for this decision would not change one published value: the converter puts TBD back.
• Whichever option is chosen, the default has to go with it. Options 1 and 2: emit null (or omit the key) for an absent value, as every other column does, so the facets list real values only. Option 3: delete the four keys from SDK_TBD_FIELDS together with the columns.

The reservation is therefore not holding a field in reserve: it publishes a placeholder as a filter option on 155 networks, the tooling regenerates that placeholder from empty cells, and the wiki forbids contributors from touching the columns. That is the cost of leaving this undecided.

To reproduce: copy tools/ and meta/ from the json-tools branch onto a main checkout, run python tools/csv_to_json.py, and count the values of the four keys under sdks in json/*.json.

Detailed proposal

• Change type: modify column (policy on who fills them); no column added or removed unless option 3 is chosen

One of three, in order of preference:

1. Run the automation the reservation promises, on a schedule, and keep the reservation. If the script exists, the 7 columns become the most reliable data in the file; if it does not, the reservation is a note about a plan.
2. Drop the reservation on the four SDK fields and let contributors fill them from the action-button link, with the format the existing rows already use (Apache-2.0, 2.1.0, 2026-02-24, Ava Labs). The three apis verified* columns should stay reserved: they are measurements, not lookups.
3. Drop the columns that will not be populated, so the schema stops advertising data it does not hold.

Whichever is chosen, the 120 TBD and 384 NULL cells are then covered by #3557 and #2683 respectively, and the wiki sentence on the SDKs page is updated to match.

Reproduction

import csv, io
for f, cols in (('sdks', ['latestKnownVersion', 'latestKnownReleaseDate', 'maintainer', 'license']),
                ('apis', ['verifiedUptime', 'verifiedLatency', 'verifiedBlocksBehindAvg'])):
    rows = list(csv.reader(io.open(f'references/offers/{f}.csv', encoding='utf-8-sig')))
    h = [c.strip() for c in rows[0]]
    for c in cols:
        v = [r[h.index(c)].strip() for r in rows[1:]]
        print(f, c, 'real', sum(1 for x in v if x and x not in ('TBD', 'NULL', 'null')),
              'sentinel', sum(1 for x in v if x in ('TBD', 'NULL', 'null')), 'blank', v.count(''))

Rewards address: 0x06f44f4839fd5df4f4670036d028b29dec939363

[EazyHood]

One data point for option 2, surfaced on #3557 by @CodeRabbit-byte: #3231 and #3232 (open since 26 August, mergeable, review pending) fill exactly the four sdks columns this proposal lists — latestKnownVersion, latestKnownReleaseDate, maintainer, license — on 36 offer rows, sourced from each package's registry entry. So contributors are already treating the reservation as advisory. If those PRs are accepted, the SDKs wiki line is the thing left to change; if they are not, that answer is just as useful, and it would be worth saying so on them.

[CodeRabbit-byte]

Confirming the wiki text, and disclosing that two of my own open PRs are on the wrong side of it.

The prohibition is stronger than the line you quoted. SDKs.md lines 74-77 read in full:

latestKnownVersion, latestKnownReleaseDate, maintainer and license

Exists only in resulting JSONs.
Fields reserved for automation scripts from Chain.Love team - fetching this information from the action buttons link.
Can't be modified manually.

So it is not only a reservation — it is an explicit instruction not to edit those four columns by hand.

#3231 and #3232 modify them by hand. #3231 fills 96 cells across 25 rows and #3232 replaces 47 TBD cells across 12 rows, in exactly those four columns. Both are currently approved and mergeable. I did not know about this wiki paragraph when I opened them in August, and I would rather say so here than have it discovered after they merge.

I am not asking for an exception. If the reservation stands, both PRs should be closed and the cells left to the script — the fact that they pass review does not make them compliant, and a rule that is enforced only when someone notices is worse than no rule.

On the substance, your option 2 is the one I would argue for, on evidence rather than convenience:

• The reservation has held since the columns were created and the automation has produced, by your own count, 9 real values in latestKnownVersion out of 173 rows. A reservation that has not been exercised is not protecting data quality; it is preventing it.
• For the 74 GitHub-backed rows the three lookups are GET /repos/{owner}/{repo} for license and owner, and GET /repos/{owner}/{repo}/releases/latest for tag and published date. That is not a judgement call, which is what usually justifies reserving a column.
• The existing real values already establish the format — Apache-2.0, 2.1.0, 2026-02-24, Ava Labs — so a contributor pass has an unambiguous target.

I agree the three apis verified* columns are a different case and should stay reserved. They are measurements of provider performance over time; a contributor cannot produce them honestly, and a contributor who tried would be inventing numbers. The distinction your proposal draws between a lookup and a measurement is the right line.

One correction to the reproduction, if you want the counts to include listings. The snippet reads references/offers/sdks.csv only. Repo-wide, sdks also carries 83 listing-level TBD cells, which is why my earlier total came to 685 rather than 600 — worth stating explicitly in the issue so the two numbers do not look like a discrepancy later.

Until this is decided I have stopped adding cells to those four columns. I will not open the follow-up PR for the remaining GitHub-backed rows that we were sequencing on #3557, because it would mean writing more data into a column whose policy is under active question. If option 2 is adopted I will pick it up; if option 1 or 3 is adopted, the work should not exist.

[EazyHood]

Thank you for putting the disclosure here rather than leaving it for someone to find. The lookup-versus-measurement line is the one I would keep whatever is decided.

The paragraph you quote reaches further than #3231 and #3232. On main at e83cde0, 536 of the 685 TBD cells in #3557 sit in those same four columns — 459 in the offers master (120 latestKnownVersion, 120 latestKnownReleaseDate, 113 maintainer, 106 license) and 77 at listing level (20 / 20 / 20 / 17). Blanking a cell is a manual edit too, so I am holding those 536 as well and letting #3557 proceed only on the 149 cells outside the reservation. As written, the rule now freezes two mergeable PRs and most of a cleanup, while the columns it protects hold between 9 and 23 real values out of 173.

On the counts: the table above is the offers master only, by design — that is where the reservation is written. The listing-level cells are in the first table of #3557 (600 offer-level, 85 listing-level, sdks 490 / 83); I have added a line above so the two issues read together.

@ArseniiPetrovich this decision now gates #3557 (536 cells), #3231 and #3232. Any of the three options unblocks all of them; option 2 is the one with data behind it.

[CodeRabbit-byte]

Your 536 / 149 split reproduces exactly on my side, same commit e83cde0: 459 offer-level (120 / 120 / 113 / 106) and 77 listing-level (20 / 20 / 20 / 17) inside the reservation, 149 outside it — sdks/programmingLanguage 37, platforms/toolType 34, security/deliveryType 23, ramps/deliveryType 22, security/executionEnvironment 18, security/toolType 11, storages/planType 2, security/planType 2. Total 685.

Agreed on holding the 536, and I think you are right that blanking is a manual edit too.

There is a consequence of the reservation that I do not think either of us has stated, and it is the strongest argument in this issue. The wiki paragraph opens with "Exists only in resulting JSONs", which reads like an internal field. It is not. All four are defined in meta/columns.json as user-facing table columns with labels, icons, sorting and filters:

latestKnownVersion       label "Latest Version"  filter searchableMultiSelect
latestKnownReleaseDate   label "Release Date"    filter searchableMultiSelect
maintainer               label "Maintainer"      filter searchableMultiSelect
license                  label "License"         filter select

So they are shipped to the site as filterable, sortable facets. I ran csv_to_json.py over e83cde0 and counted what those facets actually contain once all-networks inheritance has fanned the offer rows out across every network:

published sdks listing rows across all networks: 4381

column                      TBD     real    null   TBD share
license                    4106      275       0      93.7%
latestKnownVersion         4166      215       0      95.1%
latestKnownReleaseDate     4166      215       0      95.1%
maintainer                 3981      400       0      90.9%

TBD appears in the published sdks data of 155 networks. In the license facet it outnumbers Apache-2.0 4106 to 244 and MIT 4106 to 26. There are no nulls at all — the sentinel is not an empty cell awaiting a value, it is a string being served.

That reframes the cost. This is not a tidy-up of an internal staging column: a visitor filtering SDKs by License is offered a dropdown whose dominant option is TBD, and sorting by Release Date sorts a column that is 95% placeholder. The reservation is not holding a field in reserve — it is publishing a placeholder to end users across 155 networks and forbidding anyone from fixing it.

That argues for option 2, and it also makes option 3 coherent for the first time. If the automation is not going to run, dropping four columns that are 91–95% placeholder is better than continuing to ship them as filter facets. What is not defensible is the current state, which is the only one of the three that keeps the placeholder visible to users indefinitely.

For whoever picks this up: the 275 real license values already establish the vocabulary (Apache-2.0, MIT, BSD-3-Clause, MIT / Apache-2.0), so option 2 has an unambiguous target format and does not need a new spec.

I have nothing further to add beyond this — my two PRs stay held either way, and I would rather this be decided on the published-output numbers than on whose PR is waiting.

Reproduction, from a clean checkout with the json-tools scripts in place:

python csv_to_json.py
python - <<'PY'
import json, glob, collections
cols = ['license', 'latestKnownVersion', 'latestKnownReleaseDate', 'maintainer']
stat = {c: collections.Counter() for c in cols}
rows = 0
for p in glob.glob('json/*.json'):
    d = json.load(open(p, encoding='utf-8'))
    for row in d.get('sdks', []):
        rows += 1
        for c in cols:
            v = row.get(c)
            stat[c]['TBD' if v == 'TBD' else ('(null)' if v in (None, '') else 'real')] += 1
print('rows', rows)
for c in cols:
    s = stat[c]
    print(c, dict(s))
PY

[EazyHood]

Reproduced at e83cde0 with the json-tools scripts at 5f89146: 4381 published rows, 4106 / 4166 / 4166 / 3981 TBD, 275 / 215 / 215 / 400 real, no nulls, all 155 networks; License filter 4106 TBD against 244 Apache-2.0 and 26 MIT. It is now in the body above as "What the site publishes", with credit.

One thing came out of tracing where each published TBD originates. The zero nulls are not the data: csv_to_json.py has SDK_TBD_FIELDS and an ensure_sdks_tbd_fields() pass (since 74d50e1, #563) that writes the string TBD into any of the four fields that is missing or blank. Per column, 98 of the published TBD come from cells that are blank in the CSVs, 17-20 from listing rows, 2 from listing-only rows, and the rest from the master. So blanking the 536 cells would not change one published value, and whichever option is chosen, the default has to go with it: emit null or omit the key for an absent value (options 1 and 2), or drop the four keys from the tuple along with the columns (option 3). Added to the body as well.

The current state is still the only one of the three that keeps the placeholder in front of users; it just has one more moving part than either of us had counted.