# SCHEMA — callhome/1

Every row in `register.json`, `register.jsonl` and `register.csv` has these fields, in this order. A row is one call out by one product at one version on one build; a product where no call was found has one row whose id ends in `/none` and states how deep the look went. In the CSV a nested value is written as JSON text.

The grade is the ceiling of a row's words: `measured` · `witnessed` · `read` · `inferred` (defined in `register.json` under `grades`).

## identity

| field | type | required | what it holds |
|---|---|---|---|
| `id` | text | yes | `<slug>-<version>-<build>/<call>`; unique; names, never numbers |
| `product` | text | yes | the product as the vendor names it |
| `slug` | text (lower case, hyphenated) | yes | the product page's address |
| `package` | text | may be null | the package or project name |
| `version` | text | yes | the exact version read or run; several are listed, never spanned |
| `version_read_utc` | date (UTC, YYYY-MM-DD) | may be null | the day the version was read |
| `build` | text | yes | which build: platform, archive or image |
| `os` | text | yes | where the evidence came from |
| `arch` | text | yes | the processor architecture of that evidence |
| `install_method` | text | yes | how the copy was installed, or that only source was read |
| `group` | one of `servers and apps you run` · `libraries other tools install for you` · `research engines and model repositories we read` · `Ubuntu and the network software around them` | yes | which of the table's four kinds |

## the answer

| field | type | required | what it holds |
|---|---|---|---|
| `sends_by_default` | one of `yes` · `likely` · `opt_in` · `when_chosen` · `unclear` · `none_found` · `not_read` | yes |  |
| `answer_cell` | text | yes | the printed 'sends by default' cell, the depth of the look inside it |
| `look_depth` | one of `run` · `code_read_call_sites` · `code_read_keyword` · `dependency_only` · `vendor_doc` | yes | how deep the look went |
| `condition` | text | may be null | a conditional call's condition |
| `call_kind` | list of one of `reports` · `checks` · `fetches` · `cloud_you_chose` | yes | `reports` · `checks` · `fetches` · `cloud_you_chose`; empty where no call |
| `trigger` | one of `background` · `on_request` · `you_asked` | may be null |  |

## what and when

| field | type | required | what it holds |
|---|---|---|---|
| `sends` | list of sent field {field, class} | no | field names and classes, never values |
| `when` | text | may be null | the trigger and timing in words, with its network condition |
| `when_observed_s` | list of number | may be null | [low, high] seconds, observed |
| `when_anchor` | one of `from_launch` · `from_ready` · `from_sdk_init` | may be null |  |
| `when_condition` | one of `every attempt refused` · `every handshake hung up` · `every request answered` · `on a working network` | may be null | the network condition a timing was seen under |
| `when_state` | text | may be null | a state the timing depends on |

## where

| field | type | required | what it holds |
|---|---|---|---|
| `host_class` | one of `vendor telemetry collector` · `vendor API` · `update service` · `model hub` · `code host` · `error tracker` · `third-party analytics` · `OS telemetry` · `own resolver (DNS over HTTPS or TLS)` · `hard-coded address` · `local network (discovery)` · `third-party service` · `package index` · `download server` | may be null |  |
| `hosts` | list of host {name, provenance} | no |  |

## the switch

| field | type | required | what it holds |
|---|---|---|---|
| `switch` | switch | may be null | the setting that stops the call |
| `switch_verdict` | one of `proven` · `undecided` · `does_not_stop_it` · `not_tested` · `n/a` · `not_decidable_at_depth_N` | yes |  |
| `switch_verdict_how` | text | may be null | how the verdict was reached |
| `switch_verdict_version` | text | may be null |  |
| `switch_verdict_window` | text | may be null |  |
| `switch_verdict_n` | whole number, at least 1 | may be null |  |
| `steps_not_met` | list of text | no | any of the seven steps not met |

## exposure and cloud

| field | type | required | what it holds |
|---|---|---|---|
| `listens_default` | one of `loopback` · `all_interfaces` · `all_interfaces_in_official_image` · `n/a` | may be null | the documented default bind; null where not covered |
| `listens_source` | text | yes | what the default bind was read from, or why it is not covered |
| `cloud_features` | list of cloud feature {name, switch, source} | no |  |
| `licence` | licence {name, source, read_utc} | yes | the licence the vendor states, with its source and read date |

## evidence

| field | type | required | what it holds |
|---|---|---|---|
| `grade` | one of `measured` · `witnessed` · `read` · `inferred` | yes | the ceiling of the row's words |
| `read_source` | one of `code` · `vendor_doc` | may be null |  |
| `method` | text | yes | how the row was established |
| `measured_utc` | window {from, to} | may be null | both ends, UTC |
| `read_utc` | date (UTC, YYYY-MM-DD) | may be null |  |
| `exercised` | list of text | no |  |
| `not_exercised` | list of text | no |  |
| `leaves_on_disk` | list of disk trace {path, what, receipt} | no |  |
| `receipts` | list of receipt {label, url, kind} | yes | the receipts; a row with no primary one does not ship |
| `version_at_witness` | text | may be null |  |
| `measured_on` | list of text (a research hub slug, with #section where it names one) | no | research hub pages that measured this |

## fairness

| field | type | required | what it holds |
|---|---|---|---|
| `vendor_purpose` | {quote, source, where, read_utc} or {none_found, read_utc} or {left_out, read_utc} | may be null | what the vendor says the call is for, in the vendor's words |
| `vendor_documents_it` | vendor documents it | may be null | whether the vendor's own documents describe this call and its switch |
| `public_discussion` | list of discussion {url, by, opened_utc} | no |  |
| `credit` | list of dated text {text, source, read_utc} | no |  |
| `does_not_send` | list of dated text {text, source, read_utc} | no |  |
| `also_know` | list of dated text {text, source, read_utc} | no | what a run or a released house page already shows |
| `brings_in` | list of text | no | row ids this product carries |
| `installed_by` | list of text | no | row ids of the packages that carry it |
| `installed_by_packages` | list of package {name, version, note} | no | packages that carry it and have no row |

## bookkeeping

| field | type | required | what it holds |
|---|---|---|---|
| `first_published_utc` | date (UTC, YYYY-MM-DD) | may be null |  |
| `last_read_utc` | date (UTC, YYYY-MM-DD) | may be null |  |
| `superseded_by` | text | may be null | the row id that replaced this one |
| `history` | list of history entry | no |  |

## products

`register.json` also carries `products[]`, one entry per product: `slug`, `name` and `answer` (the one-sentence answer its page opens with, naming only what the product's rows carry), then `not_yet_checked[]`, `old_slugs[]` and `newest` (the newest release on the day the version watch last read it).

## groups (the `group` field's four values)

- servers and apps you run
- libraries other tools install for you
- research engines and model repositories we read
- Ubuntu and the network software around them

## counts

`register.json` carries `counts`, every figure the front page prints, computed from the rows and never typed; a `_by_kind` key holds one whole number per kind of call (`reports`, `checks`, `fetches`, `cloud_you_chose`) and is never summed across kinds. Each key's rule, so a reader can repeat it:

| key | the rule |
|---|---|
| `rows` | every row on the register |
| `products` | every product (one slug) |
| `table_lines` | the table's lines: one per product and version |
| `calls_found_by_kind` | rows that send (yes, only if you opt in, when chosen), per kind of call |
| `calls_likely_by_kind` | rows whose answer is likely, per kind of call |
| `calls_unclear_by_kind` | rows whose answer is unclear, per kind of call |
| `products_with_none_found` | products every one of whose rows reads none found |
| `products_own_code_not_read` | products every one of whose rows reads not read |
| `n_send` | products with a row that reads yes |
| `n_full` | of those, products whose every yes row the vendor documents (yes) |
| `n_part` | of those, products not in n_full with a yes row the vendor documents yes or partly |
| `grade_measured` | rows graded measured |
| `grade_witnessed` | rows graded witnessed |
| `grade_read` | rows graded read |
| `grade_inferred` | rows graded inferred |