The JSON interface¶
Every command listed under Commands, below, takes --json, before or after
the verb:
hammunition --json status and hammunition status --json are the same run.
With it, the command prints one JSON document on stdout and nothing else
there. Everything else it would have printed -- notes, warnings, the reason
for a refusal -- goes to stderr. The exit code is the one the text run returns
(the table is in docs/reference/cli.md), and a run that refuses still prints
a document: its own kind when it got far enough to have one (a refused plan is
a plan with outcome: "refused"), otherwise an error document carrying
the exit code and everything written to stderr.
Every document starts with the same three fields:
schema versions the whole interface. A field may be added within a major
version; removing a field or changing what one means bumps the major, and a
front end refuses a major it does not know, by name. engine is the installed
engine's version.
A real install is never driven through JSON. install --json and
uninstall --json require --dry-run: their document is the plan. A front
end runs the real command in the operator's own terminal, where sudo, every
consent gate (D-021) and every disclosure are the CLI's, then reads
status --json again. A command with no JSON form refuses --json with an
error document and runs nothing.
These documents are for local programs, not for pasting. station carries
the callsign, grid square and every other station value, because a local front
end needs them to fill a form. plan carries what the text plan prints: the
operator's account, paths in their home, and the station's map regions by
name. It never carries a rendered configuration file, so the callsign in one is
not in it. Do not paste either into an issue, a forum or a chat: a callsign
resolves to a name and a licence address, and a grid square or a map region
says where the station is. doctor and update keep the count-only rule
their text follows.
--help and --version under --json print to stderr and emit no document.
Commands¶
hammunition artifactshammunition doctorhammunition hardware gps resume reporthammunition hardware statehammunition install(with--dry-runonly)hammunition listhammunition logshammunition maps activatehammunition maps areashammunition maps infra importhammunition maps infra removehammunition maps phonehammunition maps regionshammunition maps repeaters importhammunition maps repeaters listhammunition maps repeaters removehammunition reference bookshammunition secrets statushammunition self update(with--dry-runonly)hammunition serviceshammunition show PROFILE(profile document);hammunition show UNIT --json(unit document)hammunition station sethammunition station showhammunition statushammunition transactionshammunition uninstall(with--dry-runonly)hammunition update
docs/reference/cli.md names the document each one prints, in its own section.
Kinds¶
| kind | document |
|---|---|
areas |
AreasDocument |
areas-activate |
ActivateDocument |
artifacts |
ArtifactsDocument |
books |
BooksDocument |
catalog |
CatalogDocument |
doctor |
DoctorDocument |
error |
ErrorDocument |
gps-resume-report |
GpsResumeReportDocument |
hardware |
HardwareDocument |
infra |
InfraDocument |
infra-removed |
InfraRemovedDocument |
logs |
LogsDocument |
phone |
PhoneDocument |
plan |
PlanDocument |
profile |
ProfileDocument |
regions |
RegionsDocument |
repeaters |
RepeatersDocument |
repeaters-list |
RepeatersListDocument |
repeaters-removed |
RepeatersRemovedDocument |
secrets |
SecretsDocument |
self-update |
SelfUpdateDocument |
services |
ServicesDocument |
station |
StationDocument |
station-set |
StationSetDocument |
status |
StatusDocument |
transactions |
TransactionsDocument |
unit |
UnitDocument |
update |
UpdateDocument |
areas¶
Every area with files on disk, whether it is active, and what is always active. Read-only: nothing is written or fetched.
| field | type | meaning |
|---|---|---|
active_areas |
list of string or null | the station's active_areas: null (unset) means everything loaded is active; an empty list means none is |
areas |
list of AreaView |
states first, then regions, each by name |
always_active |
list of string | the layers that belong to no area (the operator's own import, ACMA, OpenStreetMap's repeaters, every infrastructure theme today), by layer id: they are registered whichever areas are active |
unloaded |
list of string | entries of active_areas that match nothing loaded: accepted, since the operator may fetch them next |
AreaView¶
One state or region with files on disk.
| field | type | meaning |
|---|---|---|
area |
string | a state code (OH, or RepeaterBook's state_id outside the US) or a map region (north-america/us/ohio; the file slug when the station no longer names it) |
kind |
string | state or region |
active |
boolean | whether it is drawn and registered: everything is while active_areas is unset. A state and the region that is the same ground (OH, north-america/us/ohio) are active together |
layers |
list of AreaLayerView |
what is loaded for it |
size_bytes |
integer | every layer's files together |
day |
string or null | the newest layer's date; null when none is known |
AreaLayerView¶
One thing loaded for an area.
| field | type | meaning |
|---|---|---|
id |
string | for a state, the repeater layer's id (repeaterbook-OH); for a region, extract (the OpenStreetMap extract), navit (the converted Navit map) or tiles (the browser map's vector tiles) |
kind |
string | repeaters, extract, navit or tiles |
rows |
integer or null | repeaters in the layer; null for a region's files |
size_bytes |
integer | the layer's files on disk, as the engine measures them |
day |
string or null | YYYY-MM-DD: a repeater layer's date; a region's snapshot or file date; null when unknown |
files |
list of string | the files that make it up, as they are on disk |
JSON Schema
{
"$defs": {
"AreaLayerView": {
"additionalProperties": false,
"description": "One thing loaded for an area.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"kind": {
"title": "Kind",
"type": "string"
},
"rows": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Rows"
},
"size_bytes": {
"title": "Size Bytes",
"type": "integer"
},
"day": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Day"
},
"files": {
"items": {
"type": "string"
},
"title": "Files",
"type": "array"
}
},
"required": [
"id",
"kind",
"rows",
"size_bytes",
"day",
"files"
],
"title": "AreaLayerView",
"type": "object"
},
"AreaView": {
"additionalProperties": false,
"description": "One state or region with files on disk.",
"properties": {
"area": {
"title": "Area",
"type": "string"
},
"kind": {
"title": "Kind",
"type": "string"
},
"active": {
"title": "Active",
"type": "boolean"
},
"layers": {
"items": {
"$ref": "#/$defs/AreaLayerView"
},
"title": "Layers",
"type": "array"
},
"size_bytes": {
"title": "Size Bytes",
"type": "integer"
},
"day": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Day"
}
},
"required": [
"area",
"kind",
"active",
"layers",
"size_bytes",
"day"
],
"title": "AreaView",
"type": "object"
}
},
"additionalProperties": false,
"description": "Every area with files on disk, whether it is active, and what is\nalways active. Read-only: nothing is written or fetched.",
"properties": {
"active_areas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Active Areas"
},
"areas": {
"items": {
"$ref": "#/$defs/AreaView"
},
"title": "Areas",
"type": "array"
},
"always_active": {
"items": {
"type": "string"
},
"title": "Always Active",
"type": "array"
},
"unloaded": {
"items": {
"type": "string"
},
"title": "Unloaded",
"type": "array"
}
},
"required": [
"active_areas",
"areas",
"always_active",
"unloaded"
],
"title": "AreasDocument",
"type": "object"
}
areas-activate¶
maps activate: the station value written, and what each program was
told. Nothing is deleted, whichever areas are deactivated.
| field | type | meaning |
|---|---|---|
dry_run |
boolean | true when nothing was written |
before |
list of string or null | active_areas before; null was unset |
after |
list of string or null | active_areas after: null for --all (everything loaded), an empty list for --none |
changed |
boolean | whether the station value differs |
unloaded |
list of string | areas named that match nothing loaded; accepted all the same |
poi_files |
list of string | the .poi files QMapShack's POI collections will list: the active areas' and every layer that belongs to no area |
poi_paths |
list of string | what QMapShack's [Canvas] poiPaths names for them: the layer directories while everything is active, else overlays/active-poi, a directory of links to the files |
links_added |
list of string | links made in that directory |
links_dropped |
list of string | links taken out of it (only links: no layer file is touched) |
navit_overlays |
list of string | the layers' Navit textfiles in Navit's map set |
navit_regions |
list of string | the converted region maps left in Navit's map set, by file slug; empty when Navit has none installed |
navit_left_out |
list of string | the converted region maps left out of it |
browser |
BrowserView |
the browser map's list |
registered |
list of RegistrationView |
QMapShack's and Navit's, in that order; empty for a dry run |
notes |
list of string | sentences the text prints |
BrowserView¶
What the browser map (reference serve) will list.
| field | type | meaning |
|---|---|---|
regions |
list of string | the vector-tile files served, by file slug: the active regions' only |
overlays |
list of string | the infrastructure layers drawn, by layer id |
RegistrationView¶
What a program was told about the layer.
| field | type | meaning |
|---|---|---|
program |
string | qmapshack or navit |
config |
string | the file edited or written |
outcome |
string | added, already there, written, removed, not there, not written or refused |
detail |
string | the sentence the text prints after the outcome |
JSON Schema
{
"$defs": {
"BrowserView": {
"additionalProperties": false,
"description": "What the browser map (`reference serve`) will list.",
"properties": {
"regions": {
"items": {
"type": "string"
},
"title": "Regions",
"type": "array"
},
"overlays": {
"items": {
"type": "string"
},
"title": "Overlays",
"type": "array"
}
},
"required": [
"regions",
"overlays"
],
"title": "BrowserView",
"type": "object"
},
"RegistrationView": {
"additionalProperties": false,
"description": "What a program was told about the layer.",
"properties": {
"program": {
"title": "Program",
"type": "string"
},
"config": {
"title": "Config",
"type": "string"
},
"outcome": {
"title": "Outcome",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"program",
"config",
"outcome",
"detail"
],
"title": "RegistrationView",
"type": "object"
}
},
"additionalProperties": false,
"description": "``maps activate``: the station value written, and what each program was\ntold. Nothing is deleted, whichever areas are deactivated.",
"properties": {
"dry_run": {
"title": "Dry Run",
"type": "boolean"
},
"before": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Before"
},
"after": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "After"
},
"changed": {
"title": "Changed",
"type": "boolean"
},
"unloaded": {
"items": {
"type": "string"
},
"title": "Unloaded",
"type": "array"
},
"poi_files": {
"items": {
"type": "string"
},
"title": "Poi Files",
"type": "array"
},
"poi_paths": {
"items": {
"type": "string"
},
"title": "Poi Paths",
"type": "array"
},
"links_added": {
"items": {
"type": "string"
},
"title": "Links Added",
"type": "array"
},
"links_dropped": {
"items": {
"type": "string"
},
"title": "Links Dropped",
"type": "array"
},
"navit_overlays": {
"items": {
"type": "string"
},
"title": "Navit Overlays",
"type": "array"
},
"navit_regions": {
"items": {
"type": "string"
},
"title": "Navit Regions",
"type": "array"
},
"navit_left_out": {
"items": {
"type": "string"
},
"title": "Navit Left Out",
"type": "array"
},
"browser": {
"$ref": "#/$defs/BrowserView"
},
"registered": {
"items": {
"$ref": "#/$defs/RegistrationView"
},
"title": "Registered",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
}
},
"required": [
"dry_run",
"before",
"after",
"changed",
"unloaded",
"poi_files",
"poi_paths",
"links_added",
"links_dropped",
"navit_overlays",
"navit_regions",
"navit_left_out",
"browser",
"registered",
"notes"
],
"title": "ActivateDocument",
"type": "object"
}
artifacts¶
Every remote data artifact the engine would fetch for the selection
given (D-070): data units, map regions, terrain tiles and reference
books. No station file is read; the regions and books are the ones on
the command line. What cannot be listed is listed as deferred, with the
reason, never dropped.
| field | type | meaning |
|---|---|---|
map_regions |
list of string | the --map-regions given; empty when none |
map_freshness |
string | the --map-freshness given, yearly when none |
reference_books |
list of string | the --reference-books given (Kiwix book ids, D-066); empty when none |
units |
list of string | the units listed, in order |
artifacts |
list of ArtifactEntry |
one entry per artifact, deferred ones included |
ArtifactEntry¶
One remote artifact, or one the selection cannot list and why.
| field | type | meaning |
|---|---|---|
unit |
string | the catalog unit (osm-regions, dem-copernicus, country-files, kiwix-library) |
name |
string or null | the artifact's stable name within the unit: a region path, a tile name, a data file's name, a Kiwix book id as the pin file names it. A LAN mirror serves it at <mirror>/<unit>/<name>. Null only for a deferred entry that covers the whole unit |
url |
string or null | the publisher URL the engine itself fetches; null when deferred |
check |
string or null | how the download is verified: sha256 (pinned by Hammunition), md5-publisher (Geofabrik's published MD5), etag-md5 (the Copernicus object's ETag), sha1-publisher (the SHA-1 and size in CoMaps' own map index at the pinned commit, carried in the catalog), sha256-publisher (no unit uses it today) or unverified-zip (the ACMA register: no digest exists, so the zip's own CRC-32s and the tables its reader needs are checked; D-074, amended 2026-10-01) or unverified-fetch (an on-request repeater list of unit repeater-snapshots: no digest, no licence stated by its publisher, only size and date can be checked; D-078); null when deferred |
digest |
string or null | the expected digest, in hex, of the kind check names: the pin, or the publisher's checksum as the engine read it while resolving; null when deferred and for unverified-zip and unverified-fetch, which have none |
checksum_url |
string or null | where a publisher checksum is read: the .md5 beside a Geofabrik file, or the tile URL whose HEAD carries the ETag; null for a pinned sha256 and when deferred |
size |
integer or null | bytes, known before the fetch (for unverified-zip and unverified-fetch, the publisher's HEAD today: the file changes; null for unverified-fetch when the server states no length); null when deferred |
licence |
string | the licence line the plan prints for the unit, or for a Kiwix book that book's own |
deferred |
string or null | null, or why this artifact cannot be listed for this selection |
JSON Schema
{
"$defs": {
"ArtifactEntry": {
"additionalProperties": false,
"description": "One remote artifact, or one the selection cannot list and why.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
},
"check": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Check"
},
"digest": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Digest"
},
"checksum_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Checksum Url"
},
"size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Size"
},
"licence": {
"title": "Licence",
"type": "string"
},
"deferred": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Deferred"
}
},
"required": [
"unit",
"name",
"url",
"check",
"digest",
"checksum_url",
"size",
"licence",
"deferred"
],
"title": "ArtifactEntry",
"type": "object"
}
},
"additionalProperties": false,
"description": "Every remote data artifact the engine would fetch for the selection\ngiven (D-070): `data` units, map regions, terrain tiles and reference\nbooks. No station file is read; the regions and books are the ones on\nthe command line. What cannot be listed is listed as deferred, with the\nreason, never dropped.",
"properties": {
"map_regions": {
"items": {
"type": "string"
},
"title": "Map Regions",
"type": "array"
},
"map_freshness": {
"title": "Map Freshness",
"type": "string"
},
"reference_books": {
"items": {
"type": "string"
},
"title": "Reference Books",
"type": "array"
},
"units": {
"items": {
"type": "string"
},
"title": "Units",
"type": "array"
},
"artifacts": {
"items": {
"$ref": "#/$defs/ArtifactEntry"
},
"title": "Artifacts",
"type": "array"
}
},
"required": [
"map_regions",
"map_freshness",
"reference_books",
"units",
"artifacts"
],
"title": "ArtifactsDocument",
"type": "object"
}
books¶
The Kiwix books the catalog offers. Read from the catalog and the disk; nothing is fetched.
| field | type | meaning |
|---|---|---|
books |
list of BookRow |
every book in catalog/data/kiwix-books.yaml, in its order |
BookRow¶
One book the catalog offers, with its pin.
| field | type | meaning |
|---|---|---|
id |
string | the id station config takes (station set --reference-books) |
title |
string | what the book is |
file |
string or null | the pinned dated file; null when the book is not pinned |
size |
integer or null | bytes of the pinned file; null when not pinned |
licence |
string | the publisher's licence line, printed in the plan too |
licence_url |
string | where the publisher states it |
note |
string or null | anything else the book list says of it |
chosen |
boolean | whether station config chooses it |
installed |
boolean | whether its pinned file is installed |
JSON Schema
{
"$defs": {
"BookRow": {
"additionalProperties": false,
"description": "One book the catalog offers, with its pin.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
},
"file": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File"
},
"size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Size"
},
"licence": {
"title": "Licence",
"type": "string"
},
"licence_url": {
"title": "Licence Url",
"type": "string"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
},
"chosen": {
"title": "Chosen",
"type": "boolean"
},
"installed": {
"title": "Installed",
"type": "boolean"
}
},
"required": [
"id",
"title",
"file",
"size",
"licence",
"licence_url",
"note",
"chosen",
"installed"
],
"title": "BookRow",
"type": "object"
}
},
"additionalProperties": false,
"description": "The Kiwix books the catalog offers. Read from the catalog and the disk;\nnothing is fetched.",
"properties": {
"books": {
"items": {
"$ref": "#/$defs/BookRow"
},
"title": "Books",
"type": "array"
}
},
"required": [
"books"
],
"title": "BooksDocument",
"type": "object"
}
catalog¶
Every profile and unit the catalog offers, and what resolves here.
| field | type | meaning |
|---|---|---|
what |
string | all, packages or profiles, as asked |
target |
TargetView or null |
the system; null when /etc/os-release is unreadable |
profiles |
list of ProfileEntry |
by name; empty when what is packages |
packages |
list of PackageEntry |
by name; empty when what is profiles |
TargetView¶
What /etc/os-release said, verbatim, with the one line the text prints.
| field | type | meaning |
|---|---|---|
distro |
string | ID from /etc/os-release |
version |
string | VERSION_ID; empty when the file declares none |
arch |
string | the machine architecture install blocks are selected by |
id_like |
list of string | ID_LIKE, split on whitespace |
pretty_name |
string or null | PRETTY_NAME, when declared |
description |
string | exactly what the text prints after Target: |
debian_family |
boolean | whether the engine will install on this system |
ProfileEntry¶
One profile in the catalog.
| field | type | meaning |
|---|---|---|
name |
string | the profile |
summary |
string | one line |
stage |
string | 1.0 or post-1.0 |
packages |
list of string | its member units |
consent_gated |
boolean | installing it presents a consent gate (D-021) |
documentation |
ProfileDocs |
its documentation |
members |
integer | how many catalog units the profile names; no target filtering |
installed |
integer | how many of those the transaction log records as installed here (the same reading status reports as completed); 0 when the log is absent |
installed_size_bytes |
integer or null | the sum of dpkg's Installed-Size (KiB, converted to bytes) over the installed members whose install method on this target is apt; null when dpkg is unavailable or no installed member is apt. Source, git, binary and data members contribute nothing in this release, so the figure is a floor, not the profile's disk use |
ProfileDocs¶
The documentation every profile carries (CLAUDE.md).
| field | type | meaning |
|---|---|---|
what_it_installs |
string | what the profile installs |
why_together |
string | why those things belong together |
deliberately_excludes |
string | what it leaves out, and why |
manual_configuration |
string | what the operator still sets up by hand |
disk_footprint_hint |
string or null | a disk estimate, when the profile states one |
PackageEntry¶
One unit in the catalog.
| field | type | meaning |
|---|---|---|
name |
string | the unit |
version |
string | the manifest's version |
summary |
string | one line |
categories |
list of string | its tags |
status |
string | supported, broken, retired or unverifiable |
methods |
list of string | the install method of every block, in manifest order |
resolves_here |
string or null | the method that resolves on this target; null when none does or the target is unknown |
JSON Schema
{
"$defs": {
"PackageEntry": {
"additionalProperties": false,
"description": "One unit in the catalog.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"summary": {
"title": "Summary",
"type": "string"
},
"categories": {
"items": {
"type": "string"
},
"title": "Categories",
"type": "array"
},
"status": {
"title": "Status",
"type": "string"
},
"methods": {
"items": {
"type": "string"
},
"title": "Methods",
"type": "array"
},
"resolves_here": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Resolves Here"
}
},
"required": [
"name",
"version",
"summary",
"categories",
"status",
"methods",
"resolves_here"
],
"title": "PackageEntry",
"type": "object"
},
"ProfileDocs": {
"additionalProperties": false,
"description": "The documentation every profile carries (CLAUDE.md).",
"properties": {
"what_it_installs": {
"title": "What It Installs",
"type": "string"
},
"why_together": {
"title": "Why Together",
"type": "string"
},
"deliberately_excludes": {
"title": "Deliberately Excludes",
"type": "string"
},
"manual_configuration": {
"title": "Manual Configuration",
"type": "string"
},
"disk_footprint_hint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Disk Footprint Hint"
}
},
"required": [
"what_it_installs",
"why_together",
"deliberately_excludes",
"manual_configuration",
"disk_footprint_hint"
],
"title": "ProfileDocs",
"type": "object"
},
"ProfileEntry": {
"additionalProperties": false,
"description": "One profile in the catalog.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"summary": {
"title": "Summary",
"type": "string"
},
"stage": {
"title": "Stage",
"type": "string"
},
"packages": {
"items": {
"type": "string"
},
"title": "Packages",
"type": "array"
},
"consent_gated": {
"title": "Consent Gated",
"type": "boolean"
},
"documentation": {
"$ref": "#/$defs/ProfileDocs"
},
"members": {
"title": "Members",
"type": "integer"
},
"installed": {
"title": "Installed",
"type": "integer"
},
"installed_size_bytes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Installed Size Bytes"
}
},
"required": [
"name",
"summary",
"stage",
"packages",
"consent_gated",
"documentation",
"members",
"installed",
"installed_size_bytes"
],
"title": "ProfileEntry",
"type": "object"
},
"TargetView": {
"additionalProperties": false,
"description": "What `/etc/os-release` said, verbatim, with the one line the text prints.",
"properties": {
"distro": {
"title": "Distro",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"arch": {
"title": "Arch",
"type": "string"
},
"id_like": {
"items": {
"type": "string"
},
"title": "Id Like",
"type": "array"
},
"pretty_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pretty Name"
},
"description": {
"title": "Description",
"type": "string"
},
"debian_family": {
"title": "Debian Family",
"type": "boolean"
}
},
"required": [
"distro",
"version",
"arch",
"id_like",
"pretty_name",
"description",
"debian_family"
],
"title": "TargetView",
"type": "object"
}
},
"additionalProperties": false,
"description": "Every profile and unit the catalog offers, and what resolves here.",
"properties": {
"what": {
"title": "What",
"type": "string"
},
"target": {
"anyOf": [
{
"$ref": "#/$defs/TargetView"
},
{
"type": "null"
}
]
},
"profiles": {
"items": {
"$ref": "#/$defs/ProfileEntry"
},
"title": "Profiles",
"type": "array"
},
"packages": {
"items": {
"$ref": "#/$defs/PackageEntry"
},
"title": "Packages",
"type": "array"
}
},
"required": [
"what",
"target",
"profiles",
"packages"
],
"title": "CatalogDocument",
"type": "object"
}
doctor¶
The read-only health check: is this machine ready? Exit 1 when blocking.
| field | type | meaning |
|---|---|---|
checks |
list of CheckView |
in the order a person should read them |
fails |
integer | blocking |
warns |
integer | to look at |
healthy |
integer | ok or info |
CheckView¶
One thing looked at, its verdict, and how to fix it.
| field | type | meaning |
|---|---|---|
name |
string | the check |
status |
string | ok, info, warn (limits what installs) or fail (blocking) |
detail |
string | what was found |
fix |
string or null | the one command or step that fixes it |
fix_argv |
list[str] or null | argv for a single command fix; null when the fix is advice rather than a command |
JSON Schema
{
"$defs": {
"CheckView": {
"additionalProperties": false,
"description": "One thing looked at, its verdict, and how to fix it.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"status": {
"title": "Status",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"fix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Fix"
},
"fix_argv": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Fix Argv"
}
},
"required": [
"name",
"status",
"detail",
"fix",
"fix_argv"
],
"title": "CheckView",
"type": "object"
}
},
"additionalProperties": false,
"description": "The read-only health check: is this machine ready? Exit 1 when blocking.",
"properties": {
"checks": {
"items": {
"$ref": "#/$defs/CheckView"
},
"title": "Checks",
"type": "array"
},
"fails": {
"title": "Fails",
"type": "integer"
},
"warns": {
"title": "Warns",
"type": "integer"
},
"healthy": {
"title": "Healthy",
"type": "integer"
}
},
"required": [
"checks",
"fails",
"warns",
"healthy"
],
"title": "DoctorDocument",
"type": "object"
}
error¶
Printed when a command ends without a document of its own: its
arguments did not parse, it has no JSON form, a real install was asked
for under --json, or it refused before resolving anything (no catalog,
an unreadable target). The exit code is the one the text run returns.
| field | type | meaning |
|---|---|---|
command |
string | the verb, e.g. status or hardware state; empty when the arguments did not parse |
exit_code |
integer | the process exit code; the table is in docs/reference/cli.md |
message |
string | everything the command wrote to stderr, which is where the reason is |
JSON Schema
{
"additionalProperties": false,
"description": "Printed when a command ends without a document of its own: its\narguments did not parse, it has no JSON form, a real install was asked\nfor under `--json`, or it refused before resolving anything (no catalog,\nan unreadable target). The exit code is the one the text run returns.",
"properties": {
"command": {
"title": "Command",
"type": "string"
},
"exit_code": {
"title": "Exit Code",
"type": "integer"
},
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"command",
"exit_code",
"message"
],
"title": "ErrorDocument",
"type": "object"
}
gps-resume-report¶
Whether the GPS resume step is installed as this engine writes it, what its last run did, and whether the receiver is delivering data now.
| field | type | meaning |
|---|---|---|
files |
list of FileView |
the script, the unit and the tmpfiles line |
enabled |
boolean | the unit is wanted by all four sleep targets |
unit |
UnitView |
the unit's state |
gpsd_answered |
boolean | gpsd answered ?DEVICES; |
gpsd_devices |
list of string | the paths gpsd lists |
receivers |
list of ReceiverView |
each /dev/gpsN; empty when none is attached |
data_window |
seconds the data check watched for | |
log_path |
string | where the step writes its last run's lines |
log_present |
boolean | the log exists; /run is cleared at boot |
log_modified |
string or null | the log's modification time, UTC; null when absent |
log_lines |
list of string | the last run's lines, newest last, at most 40 |
findings |
list of string | what is wrong and what to run; empty when nothing is |
FileView¶
One file the resume step installs, compared with what this engine would write now.
| field | type | meaning |
|---|---|---|
path |
string | where it is installed |
state |
string | current (byte for byte what this engine writes), differs, wrong-mode (the script is not 0755), absent or unreadable |
UnitView¶
systemctl show of the resume unit; no privilege needed.
| field | type | meaning |
|---|---|---|
load_state |
string or null | loaded or not-found; null when systemctl did not answer |
unit_file_state |
string or null | enabled, disabled, ...; null when unknown |
active_state |
string or null | inactive between runs is normal for a oneshot |
result |
string or null | success or what failed |
exec_main_status |
string or null | the script's last exit status; 0 when data was seen |
active_enter |
string or null | when the unit last became active, as systemd prints it |
exec_main_exit |
string or null | when the script last exited, as systemd prints it |
error |
string or null | why systemctl could not be asked, when it could not |
ReceiverView¶
One /dev/gpsN and what gpsd and the bus say about it.
| field | type | meaning |
|---|---|---|
link |
string | the /dev/gpsN link |
node |
string | the device node it names |
listed_by_gpsd |
boolean or null | gpsd's ?DEVICES; lists it; null when gpsd did not answer |
data_seconds |
seconds until the first SKY or TPV report in the data window; null when silent | |
usb |
UsbView |
the USB facts the step relies on |
UsbView¶
The receiver's own USB device, found as the resume step finds it.
| field | type | meaning |
|---|---|---|
device |
string or null | the sysfs device directory; null when it was not found |
vendor |
string or null | idVendor |
product |
string or null | idProduct |
authorized |
string or null | the authorized file's content (1 is on) |
error |
string or null | why the step could not find it, when it could not |
JSON Schema
{
"$defs": {
"FileView": {
"additionalProperties": false,
"description": "One file the resume step installs, compared with what this engine would write now.",
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"state": {
"title": "State",
"type": "string"
}
},
"required": [
"path",
"state"
],
"title": "FileView",
"type": "object"
},
"ReceiverView": {
"additionalProperties": false,
"description": "One /dev/gpsN and what gpsd and the bus say about it.",
"properties": {
"link": {
"title": "Link",
"type": "string"
},
"node": {
"title": "Node",
"type": "string"
},
"listed_by_gpsd": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Listed By Gpsd"
},
"data_seconds": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Data Seconds"
},
"usb": {
"$ref": "#/$defs/UsbView"
}
},
"required": [
"link",
"node",
"listed_by_gpsd",
"data_seconds",
"usb"
],
"title": "ReceiverView",
"type": "object"
},
"UnitView": {
"additionalProperties": false,
"description": "``systemctl show`` of the resume unit; no privilege needed.",
"properties": {
"load_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Load State"
},
"unit_file_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Unit File State"
},
"active_state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Active State"
},
"result": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Result"
},
"exec_main_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Exec Main Status"
},
"active_enter": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Active Enter"
},
"exec_main_exit": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Exec Main Exit"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
}
},
"required": [
"load_state",
"unit_file_state",
"active_state",
"result",
"exec_main_status",
"active_enter",
"exec_main_exit",
"error"
],
"title": "UnitView",
"type": "object"
},
"UsbView": {
"additionalProperties": false,
"description": "The receiver's own USB device, found as the resume step finds it.",
"properties": {
"device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"vendor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Vendor"
},
"product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"authorized": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorized"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
}
},
"required": [
"device",
"vendor",
"product",
"authorized",
"error"
],
"title": "UsbView",
"type": "object"
}
},
"additionalProperties": false,
"description": "Whether the GPS resume step is installed as this engine writes it, what its\nlast run did, and whether the receiver is delivering data now.",
"properties": {
"files": {
"items": {
"$ref": "#/$defs/FileView"
},
"title": "Files",
"type": "array"
},
"enabled": {
"title": "Enabled",
"type": "boolean"
},
"unit": {
"$ref": "#/$defs/UnitView"
},
"gpsd_answered": {
"title": "Gpsd Answered",
"type": "boolean"
},
"gpsd_devices": {
"items": {
"type": "string"
},
"title": "Gpsd Devices",
"type": "array"
},
"receivers": {
"items": {
"$ref": "#/$defs/ReceiverView"
},
"title": "Receivers",
"type": "array"
},
"data_window": {
"title": "Data Window",
"type": "number"
},
"log_path": {
"title": "Log Path",
"type": "string"
},
"log_present": {
"title": "Log Present",
"type": "boolean"
},
"log_modified": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Log Modified"
},
"log_lines": {
"items": {
"type": "string"
},
"title": "Log Lines",
"type": "array"
},
"findings": {
"items": {
"type": "string"
},
"title": "Findings",
"type": "array"
}
},
"required": [
"files",
"enabled",
"unit",
"gpsd_answered",
"gpsd_devices",
"receivers",
"data_window",
"log_path",
"log_present",
"log_modified",
"log_lines",
"findings"
],
"title": "GpsResumeReportDocument",
"type": "object"
}
hardware¶
Which catalogued devices can be parked, which are parked now, and which are kept parked across reboots -- attached or not.
Read fresh from sysfs (and the kept-off rules file) on every call, unprivileged.
| field | type | meaning |
|---|---|---|
devices |
list of DeviceView |
attached devices first, then kept-but-absent ones |
skipped |
list of SkippedView |
attached but not parkable right now |
kept_error |
string or null | why the kept-off entries could not be read; null when they were |
DeviceView¶
A catalogued, parkable device -- attached now, or kept parked and not.
| field | type | meaning |
|---|---|---|
name |
string | the catalog entry |
summary |
string | one line; empty for a kept entry with nothing attached |
address |
string | the USB bus address, e.g. 1-4: what tells two of a kind apart |
identifier |
string | vendor:product as the bus reported it |
method |
string | how it is parked, e.g. usb_deauthorize |
parked |
boolean or null | parked now; null for a kept entry with nothing attached -- there is nothing on the bus to read a state off |
kept |
boolean | kept parked across reboots |
attached |
boolean | plugged in now; a kept entry may name a device that is not |
SkippedView¶
A catalogued device that is attached but cannot be parked right now.
| field | type | meaning |
|---|---|---|
unit |
string | the catalog entry |
why |
string | why not |
JSON Schema
{
"$defs": {
"DeviceView": {
"additionalProperties": false,
"description": "A catalogued, parkable device -- attached now, or kept parked and not.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"summary": {
"title": "Summary",
"type": "string"
},
"address": {
"title": "Address",
"type": "string"
},
"identifier": {
"title": "Identifier",
"type": "string"
},
"method": {
"title": "Method",
"type": "string"
},
"parked": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Parked"
},
"kept": {
"title": "Kept",
"type": "boolean"
},
"attached": {
"title": "Attached",
"type": "boolean"
}
},
"required": [
"name",
"summary",
"address",
"identifier",
"method",
"parked",
"kept",
"attached"
],
"title": "DeviceView",
"type": "object"
},
"SkippedView": {
"additionalProperties": false,
"description": "A catalogued device that is attached but cannot be parked right now.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"why": {
"title": "Why",
"type": "string"
}
},
"required": [
"unit",
"why"
],
"title": "SkippedView",
"type": "object"
}
},
"additionalProperties": false,
"description": "Which catalogued devices can be parked, which are parked now, and\nwhich are kept parked across reboots -- attached or not.\n\nRead fresh from sysfs (and the kept-off rules file) on every call,\nunprivileged.",
"properties": {
"devices": {
"items": {
"$ref": "#/$defs/DeviceView"
},
"title": "Devices",
"type": "array"
},
"skipped": {
"items": {
"$ref": "#/$defs/SkippedView"
},
"title": "Skipped",
"type": "array"
},
"kept_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Kept Error"
}
},
"required": [
"devices",
"skipped",
"kept_error"
],
"title": "HardwareDocument",
"type": "object"
}
infra¶
Infrastructure layers written from one source (D-075). Counts, paths, names and licence lines only: no place, position or region is carried.
| field | type | meaning |
|---|---|---|
route |
string | osm, nasr, eia, wri, fcc-asr or nwr |
licences |
list of string | the source's licence line, printed before anything |
inputs |
list of InfraInputView |
what was read |
read |
integer | objects, rows or records read that belong in a layer |
skipped |
list of SkipView |
rows left out, by reason; first is empty when several extracts were read |
outside |
integer | rows of a nationwide or worldwide file outside the regions' boxes; 0 for osm |
merged |
integer | points two extracts both held, kept once; 0 but for osm |
notes |
list of string | sentences the text prints: an extract left out (by number), what another source covers |
layers |
list of InfraLayerView |
each layer, in layer order |
directory |
string | where the layers are, mode 0700 |
registered |
list of RegistrationView |
QMapShack's and Navit's, in that order, for every overlay layer present |
InfraInputView¶
One input read.
| field | type | meaning |
|---|---|---|
path |
string | the installed file, or a fetch's URL; for osm-extract, the directory of the region extracts, never a region's name |
format |
string | osm-extract, faa-nasr-apt, eia-860m, wri-gppd, fcc-asr or nwr-ccl |
sha256 |
string | the digest of what was read; empty for osm-extract, whose extracts' digests would name the regions |
SkipView¶
Rows of one input left out for one reason.
| field | type | meaning |
|---|---|---|
reason |
string | why, e.g. no usable position or no callsign |
count |
integer | how many rows |
first |
list of integer | the first five: line numbers in a CSV, row numbers in JSON, waypoint numbers in a GPX |
InfraLayerView¶
One layer this import wrote, or found empty.
| field | type | meaning |
|---|---|---|
layer_id |
string | a theme (osm-medical, osm-responders, osm-supply, osm-shelter-candidates, osm-transport, osm-power, osm-telecom, osm-water, faa-airports, eia-plants, wri-plants, fcc-towers or nwr) followed by - and the region's file slug for a per-region layer, the theme alone for a merged one |
name |
string | the layer's name, as QMapShack and the browser map show it |
written |
integer | points in the layer; 0 when this import found none |
files |
list of string | the files written, mode 0600: GPX, POI, Navit textfile, GeoJSON; empty when none |
removed |
list of string | an earlier version's files, deleted because this import found no point for it |
active |
boolean | whether the layer's area is active (D-082): true for a merged layer, which has no area, and while the station's active_areas is unset |
area |
string or null | the region the layer is for, as its extract's file slug (D-082, #327); null for a merged layer across every region |
JSON Schema
{
"$defs": {
"InfraInputView": {
"additionalProperties": false,
"description": "One input read.",
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"format": {
"title": "Format",
"type": "string"
},
"sha256": {
"title": "Sha256",
"type": "string"
}
},
"required": [
"path",
"format",
"sha256"
],
"title": "InfraInputView",
"type": "object"
},
"InfraLayerView": {
"additionalProperties": false,
"description": "One layer this import wrote, or found empty.",
"properties": {
"layer_id": {
"title": "Layer Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"written": {
"title": "Written",
"type": "integer"
},
"files": {
"items": {
"type": "string"
},
"title": "Files",
"type": "array"
},
"removed": {
"items": {
"type": "string"
},
"title": "Removed",
"type": "array"
},
"active": {
"title": "Active",
"type": "boolean"
},
"area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Area"
}
},
"required": [
"layer_id",
"name",
"written",
"files",
"removed",
"active",
"area"
],
"title": "InfraLayerView",
"type": "object"
},
"RegistrationView": {
"additionalProperties": false,
"description": "What a program was told about the layer.",
"properties": {
"program": {
"title": "Program",
"type": "string"
},
"config": {
"title": "Config",
"type": "string"
},
"outcome": {
"title": "Outcome",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"program",
"config",
"outcome",
"detail"
],
"title": "RegistrationView",
"type": "object"
},
"SkipView": {
"additionalProperties": false,
"description": "Rows of one input left out for one reason.",
"properties": {
"reason": {
"title": "Reason",
"type": "string"
},
"count": {
"title": "Count",
"type": "integer"
},
"first": {
"items": {
"type": "integer"
},
"title": "First",
"type": "array"
}
},
"required": [
"reason",
"count",
"first"
],
"title": "SkipView",
"type": "object"
}
},
"additionalProperties": false,
"description": "Infrastructure layers written from one source (D-075). Counts, paths,\nnames and licence lines only: no place, position or region is carried.",
"properties": {
"route": {
"title": "Route",
"type": "string"
},
"licences": {
"items": {
"type": "string"
},
"title": "Licences",
"type": "array"
},
"inputs": {
"items": {
"$ref": "#/$defs/InfraInputView"
},
"title": "Inputs",
"type": "array"
},
"read": {
"title": "Read",
"type": "integer"
},
"skipped": {
"items": {
"$ref": "#/$defs/SkipView"
},
"title": "Skipped",
"type": "array"
},
"outside": {
"title": "Outside",
"type": "integer"
},
"merged": {
"title": "Merged",
"type": "integer"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
},
"layers": {
"items": {
"$ref": "#/$defs/InfraLayerView"
},
"title": "Layers",
"type": "array"
},
"directory": {
"title": "Directory",
"type": "string"
},
"registered": {
"items": {
"$ref": "#/$defs/RegistrationView"
},
"title": "Registered",
"type": "array"
}
},
"required": [
"route",
"licences",
"inputs",
"read",
"skipped",
"outside",
"merged",
"notes",
"layers",
"directory",
"registered"
],
"title": "InfraDocument",
"type": "object"
}
infra-removed¶
Infrastructure layers deleted and unregistered. Removing nothing is not an error: every list is then empty.
| field | type | meaning |
|---|---|---|
directory |
string | where the layers are |
layers |
list of string | the layer ids asked for: the one --layer named, else every layer |
removed |
list of string | the files deleted |
unregistered |
list of RegistrationView |
QMapShack's and Navit's, in that order, for the overlay layers left |
JSON Schema
{
"$defs": {
"RegistrationView": {
"additionalProperties": false,
"description": "What a program was told about the layer.",
"properties": {
"program": {
"title": "Program",
"type": "string"
},
"config": {
"title": "Config",
"type": "string"
},
"outcome": {
"title": "Outcome",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"program",
"config",
"outcome",
"detail"
],
"title": "RegistrationView",
"type": "object"
}
},
"additionalProperties": false,
"description": "Infrastructure layers deleted and unregistered. Removing nothing is\nnot an error: every list is then empty.",
"properties": {
"directory": {
"title": "Directory",
"type": "string"
},
"layers": {
"items": {
"type": "string"
},
"title": "Layers",
"type": "array"
},
"removed": {
"items": {
"type": "string"
},
"title": "Removed",
"type": "array"
},
"unregistered": {
"items": {
"$ref": "#/$defs/RegistrationView"
},
"title": "Unregistered",
"type": "array"
}
},
"required": [
"directory",
"layers",
"removed",
"unregistered"
],
"title": "InfraRemovedDocument",
"type": "object"
}
logs¶
The run logs on this machine for this operator, newest first, and the limits rotation holds them to (D-077).
| field | type | meaning |
|---|---|---|
directory |
string | the log directory, <state dir>/logs |
total_bytes |
integer | bytes across every run log |
max_files |
integer | rotation keeps at most this many run logs |
max_bytes |
integer | rotation keeps at most this many bytes of run logs |
runs |
list of RunEntry |
one entry per run log, newest first |
RunEntry¶
One run's log file.
| field | type | meaning |
|---|---|---|
path |
string | absolute path of the log; tail -f it while the run is going |
started |
string | ISO 8601 UTC time the run began, from the file's name |
command |
string | the command as the file's name spells it: install, hardware-apply, maps-qmapshack |
pid |
integer | the process id of the run |
size |
integer | bytes |
result |
string | how the run ended: ok, failed, refused or not confirmed (the exit code's words), running (a live process holds the file), or incomplete (no result line and nothing holds the file: the run was killed) |
exit_code |
integer or null | the run's exit status; null for running and incomplete |
JSON Schema
{
"$defs": {
"RunEntry": {
"additionalProperties": false,
"description": "One run's log file.",
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"started": {
"title": "Started",
"type": "string"
},
"command": {
"title": "Command",
"type": "string"
},
"pid": {
"title": "Pid",
"type": "integer"
},
"size": {
"title": "Size",
"type": "integer"
},
"result": {
"title": "Result",
"type": "string"
},
"exit_code": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Exit Code"
}
},
"required": [
"path",
"started",
"command",
"pid",
"size",
"result",
"exit_code"
],
"title": "RunEntry",
"type": "object"
}
},
"additionalProperties": false,
"description": "The run logs on this machine for this operator, newest first, and the\nlimits rotation holds them to (D-077).",
"properties": {
"directory": {
"title": "Directory",
"type": "string"
},
"total_bytes": {
"title": "Total Bytes",
"type": "integer"
},
"max_files": {
"title": "Max Files",
"type": "integer"
},
"max_bytes": {
"title": "Max Bytes",
"type": "integer"
},
"runs": {
"items": {
"$ref": "#/$defs/RunEntry"
},
"title": "Runs",
"type": "array"
}
},
"required": [
"directory",
"total_bytes",
"max_files",
"max_bytes",
"runs"
],
"title": "LogsDocument",
"type": "object"
}
phone¶
The phone files gathered into one folder with a SHA256SUMS, and the routes to a phone. Names carry region slugs: for local programs, not for pasting. Nothing was transferred.
| field | type | meaning |
|---|---|---|
directory |
string | the folder, under the operator's XDG data directory |
sums |
string | the SHA256SUMS file beside them |
files |
list of PhoneFileLine |
every phone file now in the folder |
removed |
list of string | our files removed because their region is gone |
missing |
list of string | phone units with nothing installed |
routes |
list of PhoneRouteLine |
the ways to carry the folder to a phone |
PhoneFileLine¶
One phone file in the folder.
| field | type | meaning |
|---|---|---|
unit |
string | the unit that built it: mapsforge-map, mapsforge-poi or osm-garmin |
name |
string | its name in the folder, <region slug>.<map\|poi\|img> |
size |
integer | bytes |
sha256 |
string | its sha256, as written in SHA256SUMS |
copied |
boolean | true when this run copied it; false when the copy was already current |
PhoneRouteLine¶
One way to carry the folder to a phone. The engine runs none of them.
| field | type | meaning |
|---|---|---|
name |
string | the route |
laptop |
string | what the laptop needs |
phone |
string | what the phone needs |
commands |
list of string | commands for the operator to run, in order; may be empty |
note |
string | how to use it, and what it binds or modifies |
JSON Schema
{
"$defs": {
"PhoneFileLine": {
"additionalProperties": false,
"description": "One phone file in the folder.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"size": {
"title": "Size",
"type": "integer"
},
"sha256": {
"title": "Sha256",
"type": "string"
},
"copied": {
"title": "Copied",
"type": "boolean"
}
},
"required": [
"unit",
"name",
"size",
"sha256",
"copied"
],
"title": "PhoneFileLine",
"type": "object"
},
"PhoneRouteLine": {
"additionalProperties": false,
"description": "One way to carry the folder to a phone. The engine runs none of them.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"laptop": {
"title": "Laptop",
"type": "string"
},
"phone": {
"title": "Phone",
"type": "string"
},
"commands": {
"items": {
"type": "string"
},
"title": "Commands",
"type": "array"
},
"note": {
"title": "Note",
"type": "string"
}
},
"required": [
"name",
"laptop",
"phone",
"commands",
"note"
],
"title": "PhoneRouteLine",
"type": "object"
}
},
"additionalProperties": false,
"description": "The phone files gathered into one folder with a SHA256SUMS, and the\nroutes to a phone. Names carry region slugs: for local programs, not for\npasting. Nothing was transferred.",
"properties": {
"directory": {
"title": "Directory",
"type": "string"
},
"sums": {
"title": "Sums",
"type": "string"
},
"files": {
"items": {
"$ref": "#/$defs/PhoneFileLine"
},
"title": "Files",
"type": "array"
},
"removed": {
"items": {
"type": "string"
},
"title": "Removed",
"type": "array"
},
"missing": {
"items": {
"type": "string"
},
"title": "Missing",
"type": "array"
},
"routes": {
"items": {
"$ref": "#/$defs/PhoneRouteLine"
},
"title": "Routes",
"type": "array"
}
},
"required": [
"directory",
"sums",
"files",
"removed",
"missing",
"routes"
],
"title": "PhoneDocument",
"type": "object"
}
plan¶
The plan install --dry-run or uninstall --dry-run prints, as data.
A refused transaction is still a plan, with outcome: "refused", every
blocker, and exit code 2. Includes the paths of files written for the
operator; for local programs, not for pasting.
| field | type | meaning |
|---|---|---|
action |
string | install or uninstall |
requested |
list of string | the names given on the command line |
outcome |
string | planned, or refused with the blockers |
step_count |
integer | the number of steps in this transaction; zero when refused |
target |
TargetView |
the system planned against |
blockers |
list of BlockerLine |
empty unless refused |
install |
InstallPlanView or null |
the install plan; null for an uninstall or a refusal |
removal |
RemovalPlanView or null |
the removal plan; null for an install or a refusal |
BlockerLine¶
One reason the transaction cannot be planned.
| field | type | meaning |
|---|---|---|
subject |
string | what is blocked |
reason |
string | why |
remedy |
string or null | what to do about it |
InstallPlanView¶
Everything an install will do, section by section as the text prints it.
| field | type | meaning |
|---|---|---|
packages |
list of PackageLine |
every unit, in the order it installs |
displaced |
list of DisplacedLine |
distribution packages displaced or shadowed |
apt_release |
ReleaseSection or null |
present when apt resolves from another release |
no_recommends |
NoRecommendsSection or null |
present when a unit opted out of Recommends |
repos |
list of RepoLine |
third-party repositories added |
mirror |
MirrorSection or null |
the LAN mirror data downloads try first (D-070); null when none is set |
data |
list of DataLine |
offline data downloaded |
maps |
MapSectionView or null |
the station's map regions (D-057); null when no map unit or nothing to disclose |
memberships |
list of MembershipLine |
group membership changes |
file_capabilities |
list of FileCapabilityLine |
opt-in file capabilities applied to installed binaries |
consent_gates |
list of GateLine |
gates the real run presents |
config_files |
list of ConfigLine |
configuration written |
user_services |
list of UserServiceLine |
systemd user services written and enabled (D-073); empty when none |
desktops_read |
DesktopsReadView or null |
present when a unit in the request is for particular desktops and the session files were read (D-060); null otherwise |
deferrals |
list of DeferralLine |
what will NOT happen |
notes |
list of string | the plan's notes |
records |
RecordsLine or null |
where the transaction log goes |
sudo |
SudoLine or null |
present when a run as a user mixes root steps with steps that are not (D-062); null when run as root or when sudo is needed by every step or none |
commands |
list of StepView |
every step, in order |
suggestion_notes |
list of string | what happened to the profiles' suggestion groups; the text prints these as note: lines |
region_notes |
list of string | notes from resolving the map regions; the text prints these as note: lines |
publisher_checks |
list of PublisherCheckLine |
one line per data item already on disk: whether its publisher was asked at plan time (#197); empty when the plan holds no data unit with installed items |
PackageLine¶
One catalog unit in the plan.
| field | type | meaning |
|---|---|---|
name |
string | the catalog unit |
method |
string | the install method of the block that resolved here |
state |
string | will install, will build, will fetch+install, will convert or already installed; a map unit reads already installed only when the map section says nothing is left to do |
requested_by |
list of string | requested, or the profiles and units that pulled it in |
apt |
list of AptLine |
the apt packages it resolves to, build dependencies included |
AptLine¶
One apt package a unit resolves to.
| field | type | meaning |
|---|---|---|
package |
string | the apt package name |
outstanding |
boolean | not installed yet; + in the text, = when already present |
build_only |
boolean | a build dependency, not the software asked for |
DisplacedLine¶
An installed distribution package a unit displaces or shadows (D-022).
| field | type | meaning |
|---|---|---|
package |
string | the distribution package, which stays installed |
declared_by |
string | the unit whose manifest declares the conflict |
ReleaseSection¶
apt packages taken from another release this machine installs from (D-038).
| field | type | meaning |
|---|---|---|
release |
string | the --target-release the apt step runs with |
packages |
list of string | the packages that come from that release |
NoRecommendsSection¶
apt packages installed by a second command without Recommends (D-052).
| field | type | meaning |
|---|---|---|
units |
list of string | the units whose manifests asked for it |
packages |
list of string | the packages that second command installs |
RepoLine¶
A third-party apt repository the transaction adds, behind its own gate (D-040).
| field | type | meaning |
|---|---|---|
name |
string | the repository's name, which names its two files |
unit |
string | the unit that needs it |
packages |
list of string | the apt packages it is expected to supply |
uri |
string | the archive URI |
suites |
list of string | apt suites |
components |
list of string | apt components |
key_fingerprint |
string | the pinned signing-key fingerprint |
sources |
string | the .sources file written |
keyring |
string | the keyring file written |
consent_env_var |
string | must equal the key fingerprint for a scripted run |
MirrorSection¶
The LAN mirror a data download is asked for first (D-070).
| field | type | meaning |
|---|---|---|
url |
string | the mirror's base URL, from station config |
ignored |
boolean | true when --no-mirror ignores it for this run |
text |
string | what the plan prints about it |
DataLine¶
An offline-data unit: sizes and licence, before anything downloads (D-049).
| field | type | meaning |
|---|---|---|
unit |
string | the data unit |
total_size |
integer | bytes, every artifact together |
total_human |
string | the total as the text prints it |
licence |
string | the licence the data is under |
licence_url |
string | where that licence is stated |
artifacts |
list of DataArtifactLine |
each file fetched |
installs_under |
string | where it is installed, relative to the prefix |
verified_by |
string | how the download is checked: sha256, pinned by Hammunition for a data block; for a register block (D-074, amended 2026-10-01) a sentence starting unverified: that says what is checked instead |
approximate |
boolean | the sizes are a measurement of a file that changes, not a declaration the fetch checks (a register block) |
DataArtifactLine¶
One file of an offline dataset.
| field | type | meaning |
|---|---|---|
url |
string | where it is fetched from |
size |
integer | bytes, as declared and verified on fetch; for a register block the size measured when the unit was written, since the file changes daily (approximate) |
size_human |
string | the size as the text prints it |
MapSectionView¶
The station's map regions (D-057). Names where the operator is: local only.
| field | type | meaning |
|---|---|---|
fetch |
list of RegionLine |
downloaded and installed this run |
current |
list of RegionLine |
already installed at the resolved snapshot |
convert |
list of ConvertLine |
converted for Navit this run |
kept |
list of KeptLine |
could not be checked; the installed copy stays |
licence |
string | the map data's licence |
licence_url |
string | where it is stated |
download_total |
integer | bytes downloaded |
download_total_human |
string | as the text prints it |
disk_total |
integer | bytes: the download plus the estimated converted maps |
disk_total_human |
string | as the text prints it |
estimate_note |
string | how the conversion estimate was measured |
terrain |
TerrainSectionView or null |
terrain tiles and QMapShack's maps (D-061); null when no terrain unit is planned |
boundaries |
BoundaryLine or null |
the country-border file merged into each region with osmium merge before maptool; null when the converter has none |
unknown_country |
boolean | maptool runs with -U: a town outside every country boundary is indexed under the pseudo-country Unknown instead of being dropped |
RegionLine¶
One map region file.
| field | type | meaning |
|---|---|---|
region |
string | the Geofabrik region path |
snapshot |
string | the dated snapshot |
size |
integer | bytes |
size_human |
string | the size as the text prints it |
verified_by |
string | how the download is checked |
nothing_to_do |
boolean | already installed and not being converted |
ConvertLine¶
A region converted for Navit this run.
| field | type | meaning |
|---|---|---|
region |
string | the Geofabrik region path |
snapshot |
string | the dated snapshot |
estimate |
integer | bytes the converted map is estimated to take |
estimate_human |
string | that estimate as the text prints it |
countries |
list of string | ISO 3166-1 alpha-2 codes whose closed border is merged into the region first; empty when none is known or there is no boundary file |
converter_changed |
boolean | converted again only because an older converter built the installed map |
KeptLine¶
An installed region that could not be checked for a newer map; kept.
| field | type | meaning |
|---|---|---|
region |
string | the Geofabrik region path |
snapshot |
string or null | the installed snapshot, when recorded |
reason |
string | why it could not be checked |
TerrainSectionView¶
Terrain, and what is built for QMapShack (D-061). Names where the operator is: local only.
| field | type | meaning |
|---|---|---|
regions |
list of TerrainRegionLine |
tiles per region |
fetch |
list of TileLine |
tiles downloaded this run |
current |
integer | tiles already installed |
licence |
string | the elevation data's licence |
licence_url |
string | where it is stated |
download_total |
integer | bytes of tiles downloaded |
download_total_human |
string | as the text prints it |
garmin |
list of GarminLine |
Garmin maps built this run |
routino_regions |
integer | regions the Routino database is rebuilt over; 0 when current |
routino_estimate |
integer | bytes the rebuilt database is estimated to take |
routino_estimate_human |
string | as the text prints it |
contours |
integer | tiles whose contours are drawn this run |
contours_estimate |
integer | bytes those contours are estimated to take |
contours_estimate_human |
string | as the text prints it |
brouter_regions |
integer | regions BRouter's routing files are rebuilt over; 0 when current (D-063) |
brouter_tiles |
integer | terrain tiles folded into them as elevation |
brouter_estimate |
integer | bytes the rebuilt routing files are estimated to take |
brouter_estimate_human |
string | as the text prints it |
disk_total |
integer | bytes: the tiles plus everything estimated to be built |
disk_total_human |
string | as the text prints it |
estimate_note |
string | how the estimates were measured |
topo |
TopoSectionView or null |
USGS US Topo quads and their mosaic (D-068); null when neither unit is planned |
contours_from |
string | the provider the contours and QMapShack's elevation are drawn from this run: copernicus-glo30, or usgs-3dep when the station chose it (D-068, amended 2026-10-01) |
bare_earth |
BareEarthSectionView or null |
USGS 3DEP (D-068, amended 2026-10-01); null when no 3DEP unit is planned |
fstopo |
FsTopoSectionView or null |
Forest Service FSTopo quads and their map (D-068, amended 2026-10-01); null when neither is planned |
splat_tiles |
integer | tiles SPLAT's terrain (SDF files) is made for this run, for SPLAT! and Signal-Server (D-061, amended 2026-10-02) |
splat_estimate |
integer | bytes those files are estimated to take |
splat_estimate_human |
string | as the text prints it |
TerrainRegionLine¶
The terrain tiles one region needs (D-061).
| field | type | meaning |
|---|---|---|
region |
string | the Geofabrik region path |
tiles |
integer | tiles that exist for its outline |
unpublished |
integer | squares of its outline Copernicus publishes no tile for: sea, or land it does not release; the tile list cannot say which |
no_terrain |
boolean | true when its outline touches squares and every one is unpublished: no terrain is installed for this region, and the plan warns so; its maps still install |
download |
integer | bytes of its tiles downloaded this run; a tile two regions share counts in both |
download_human |
string | as the text prints it |
TileLine¶
One terrain tile downloaded this run.
| field | type | meaning |
|---|---|---|
tile |
string | the Copernicus GLO-30 tile name; it encodes a latitude and longitude |
size |
integer | bytes |
size_human |
string | the size as the text prints it |
verified_by |
string | how the download is checked |
GarminLine¶
A region mkgmap builds a Garmin map from this run.
| field | type | meaning |
|---|---|---|
region |
string | the Geofabrik region path |
snapshot |
string | the dated snapshot |
estimate |
integer | bytes the map is estimated to take |
estimate_human |
string | that estimate as the text prints it |
TopoSectionView¶
USGS US Topo sheets and QMapShack's mosaic of them (D-068). Local only.
| field | type | meaning |
|---|---|---|
regions |
list of TopoRegionLine |
quads per region |
no_quads |
list of string | regions no US Topo quad covers (outside the United States); nothing is fetched for them |
fetch |
list of QuadLine |
quads downloaded this run |
current |
integer | quads already installed |
licence |
string | the sheets' licence |
licence_url |
string | where it is stated |
download_total |
integer | bytes of quads downloaded |
download_total_human |
string | as the text prints it |
warp |
integer | quads warped for QMapShack this run |
warp_estimate |
integer | bytes the warped quads are estimated to take |
warp_estimate_human |
string | as the text prints it |
disk_total |
integer | bytes: the downloads plus the warped quads |
disk_total_human |
string | as the text prints it |
estimate_note |
string | how the estimate was measured |
selection |
string | how the station's bound chose the sheets: a radius around the grid square (the default), the --topo-regions, or every sheet (--topo-all); empty when not known |
size_consent |
string or null | the one sentence the install asks a typed yes about, which --yes does not answer: set when --topo-all is chosen or the download and warped copies exceed 10 GB; null otherwise |
TopoRegionLine¶
The US Topo quads one region needs (D-068).
| field | type | meaning |
|---|---|---|
region |
string | the Geofabrik region path |
quads |
integer | quads whose box its outline touches |
size |
integer | bytes of all its quads, installed or not |
size_human |
string | as the text prints it |
download |
integer | bytes of its quads downloaded this run; a quad two regions share counts in both |
download_human |
string | as the text prints it |
QuadLine¶
One US Topo quad downloaded this run.
| field | type | meaning |
|---|---|---|
quad |
string | the quad's file name without .tif: state, map name and edition date |
size |
integer | bytes |
size_human |
string | the size as the text prints it |
verified_by |
string | how the download is checked |
BareEarthSectionView¶
USGS 3DEP bare-earth elevation (D-068, amended 2026-10-01). Local only.
| field | type | meaning |
|---|---|---|
chosen |
boolean | whether the station's dem_source is 3dep; when false nothing is fetched, any installed 3DEP tile is removed, and QMapShack's elevation is Copernicus's |
regions |
list of TerrainRegionLine |
3DEP tiles per region and what each downloads this run (about ten times Copernicus) |
fetch |
list of TileLine |
3DEP tiles downloaded this run |
current |
integer | 3DEP tiles already installed |
licence |
string | the elevation data's licence |
licence_url |
string | where it is stated |
download_total |
integer | bytes of 3DEP tiles downloaded |
download_total_human |
string | as the text prints it |
FsTopoSectionView¶
Forest Service FSTopo sheets and QMapShack's FSTopo map (D-068, amended 2026-10-01). Local only.
| field | type | meaning |
|---|---|---|
regions |
list of SheetRegionLine |
quads per region |
no_quads |
list of string | regions no FSTopo quad covers (no National Forest land); nothing is fetched for them |
fetch |
list of QuadLine |
quads downloaded this run |
unverified |
integer | of those, quads fetched with no checksum: the Forest Service publishes none and Hammunition has pinned none |
current |
integer | quads already installed |
licence |
string | the sheets' licence |
licence_url |
string | where it is stated |
download_total |
integer | bytes of quads downloaded |
download_total_human |
string | as the text prints it |
convert |
integer | quads converted to tiled RGB for QMapShack this run |
convert_estimate |
integer | bytes the converted quads are estimated to take |
convert_estimate_human |
string | as the text prints it |
disk_total |
integer | bytes: the downloads plus the converted quads |
disk_total_human |
string | as the text prints it |
estimate_note |
string | how the estimate was measured |
SheetRegionLine¶
The FSTopo quads one region needs (D-068, amended 2026-10-01).
| field | type | meaning |
|---|---|---|
region |
string | the Geofabrik region path |
quads |
integer | quads whose box its outline touches |
download |
integer | bytes of its quads downloaded this run; a quad two regions share counts in both |
download_human |
string | as the text prints it |
all_pinned |
boolean | every quad it needs has a sha256 pinned by Hammunition, so none is unverified |
BoundaryLine¶
The country-border file merged into each region before conversion.
| field | type | meaning |
|---|---|---|
title |
string | what the file is |
url |
string | where it is fetched from |
size |
integer | bytes, as declared and verified on fetch |
size_human |
string | the size as the text prints it |
licence |
string | the licence the data is under |
verified_by |
string | how the download is checked |
MembershipLine¶
A group the operator is added to, and what it grants.
| field | type | meaning |
|---|---|---|
user |
string | the account added |
group |
string | the group |
package |
string | the unit that needs it |
detail |
string | what membership grants |
reverse_hint |
string or null | how to undo it by hand, when the manifest says |
FileCapabilityLine¶
A capability grant to one installed binary.
| field | type | meaning |
|---|---|---|
unit |
string | the catalog unit |
path |
string | the installed binary receiving capabilities |
capabilities |
list of string | Linux capabilities set with permitted/effective flags |
detail |
string | why the capability grant is available |
GateLine¶
A consent gate the real run will present (D-021). Never answered through JSON.
| field | type | meaning |
|---|---|---|
profile |
string | the gated profile or optional system change |
env_var |
string | the scripted-consent variable the gate reads |
risk_lines |
list of string | one line per disclosed capability |
ConfigLine¶
A configuration file the transaction writes.
| field | type | meaning |
|---|---|---|
unit |
string | the unit whose manifest templates it |
path |
string | the file written |
mode |
string | its octal mode |
append |
boolean | appended to rather than written |
backup_existing |
boolean | an existing file is backed up first |
fills |
list of string | the station values templated into it, by name (callsign, grid_square, ax25_callsign, latitude ...); never the values themselves |
UserServiceLine¶
A systemd user service the transaction writes and enables (D-073 §6b).
The command line is rendered with the device serial elided, and the station values are named, never quoted — the same privacy split as the rest of the plan.
| field | type | meaning |
|---|---|---|
unit |
string | the catalog unit carrying it |
name |
string | the systemd user unit, without .service |
path |
string | the unit file written, under the operator's ~/.config/systemd/user/ |
exec |
string | the service's command line, with the device serial elided |
fills |
list of string | the station values that fed it, by name; never the values |
listen |
string | the loopback address:port it binds, e.g. 127.0.0.1:4532 |
starts_now |
boolean | whether the plan restarts it now (a rig service whose radio's port is present) |
DesktopsReadView¶
What the session files said, when a unit in the request is for particular desktops (D-060).
| field | type | meaning |
|---|---|---|
desktops |
list of string | the desktops the catalog knows that the session files offer (kde, xfce, ...) |
unrecognised |
list of string | session files read that named no desktop the catalog knows (cosmic.desktop) |
summary |
string | the line the text prints under the heading |
DeferralLine¶
Part of the request that will not happen; the rest still does (D-035, D-039, D-060).
| field | type | meaning |
|---|---|---|
kind |
string | config (a file not written) or package (a member not installed: the target lacks it, or, D-060, the machine has no session for the desktop it is for; or, #200, a publisher did not answer for some of its items after the retries) |
subject |
string | what is deferred |
what |
string | what will not happen |
why |
string | what is missing |
remedy |
string | what the operator can do about it |
RecordsLine¶
Where the transaction log is written.
| field | type | meaning |
|---|---|---|
log |
string | the transaction log file |
handed_to |
string or null | the operator it is chowned to, under sudo |
SudoLine¶
How a run as a user keeps sudo from asking twice (D-062).
| field | type | meaning |
|---|---|---|
keepalive |
boolean | true when the run validates sudo once and refreshes its ticket until the run ends; false when --no-sudo-keepalive turned it off |
interval_seconds |
integer | seconds between sudo -n -v refreshes |
text |
string | what the plan prints about it |
StepView¶
One step, exactly as the real run performs it.
| field | type | meaning |
|---|---|---|
description |
string | why the step runs |
display |
string | the line the text prints after $, copy-pasteable |
argv |
list of string | the argv executed, escalation applied; empty for an in-process step |
action |
string or null | the in-process step's kind (fetch, extract, ...); null for a command |
requires_root |
boolean | whether it runs as root |
sources |
list of string | for a data download (a data artifact, a map region, a terrain tile), the URLs it is fetched from in the order tried: the LAN mirror, then the publisher (D-070); the publisher alone with no mirror; empty for any other step |
index |
integer | this step's 1-based position in execution order |
long_running |
boolean | true when the backend knows the step can take several minutes (a submodule fetch, a compile, a venv install, a node build); the text prints one fixed note under it and claims no duration (#270) |
PublisherCheckLine¶
What the plan did about one installed data item's publisher (#197).
| field | type | meaning |
|---|---|---|
unit |
string | the data unit the item belongs to |
item |
string | the tile, sheet, book or map |
checked |
boolean | whether the plan asked the item's publisher; false for an item the log attributes as installed less than seven days ago, and for one on disk the log does not attribute |
reason |
string | why, in a sentence; a failed re-check says so and that the copy is kept |
attributed |
string or null | the date of the attribution in the log (YYYY-MM-DD); null when the log has none |
RemovalPlanView¶
Everything an uninstall will do, section by section as the text prints it.
| field | type | meaning |
|---|---|---|
to_remove |
list of UnitPackages |
apt packages removed, per unit |
artifacts |
list of ArtifactLine |
files and trees removed |
left_unattributed |
list of UnitFiles |
present, but the log does not attribute it |
left_foreign |
list of UnitPackages |
installed, but not by this engine |
already_absent |
list of UnitPackages |
nothing to remove |
not_reversed |
string | what uninstall does not undo, by design (D-004) |
commands |
list of StepView |
every step, in order |
UnitPackages¶
A unit and apt packages.
| field | type | meaning |
|---|---|---|
unit |
string | the catalog unit |
packages |
list of string | apt packages |
ArtifactLine¶
A file or tree the removal deletes, and why it is this engine's to delete.
| field | type | meaning |
|---|---|---|
unit |
string | the catalog unit |
kind |
string | venv, tree, binary, wrapper, desktop-entry or apt-repo |
path |
string | what is removed |
basis |
string | namespaced, log or marker: how it is known to be ours |
UnitFiles¶
A unit and files.
| field | type | meaning |
|---|---|---|
unit |
string | the catalog unit |
paths |
list of string | files on disk |
JSON Schema
{
"$defs": {
"AptLine": {
"additionalProperties": false,
"description": "One apt package a unit resolves to.",
"properties": {
"package": {
"title": "Package",
"type": "string"
},
"outstanding": {
"title": "Outstanding",
"type": "boolean"
},
"build_only": {
"title": "Build Only",
"type": "boolean"
}
},
"required": [
"package",
"outstanding",
"build_only"
],
"title": "AptLine",
"type": "object"
},
"ArtifactLine": {
"additionalProperties": false,
"description": "A file or tree the removal deletes, and why it is this engine's to delete.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"kind": {
"title": "Kind",
"type": "string"
},
"path": {
"title": "Path",
"type": "string"
},
"basis": {
"title": "Basis",
"type": "string"
}
},
"required": [
"unit",
"kind",
"path",
"basis"
],
"title": "ArtifactLine",
"type": "object"
},
"BareEarthSectionView": {
"additionalProperties": false,
"description": "USGS 3DEP bare-earth elevation (D-068, amended 2026-10-01). Local only.",
"properties": {
"chosen": {
"title": "Chosen",
"type": "boolean"
},
"regions": {
"items": {
"$ref": "#/$defs/TerrainRegionLine"
},
"title": "Regions",
"type": "array"
},
"fetch": {
"items": {
"$ref": "#/$defs/TileLine"
},
"title": "Fetch",
"type": "array"
},
"current": {
"title": "Current",
"type": "integer"
},
"licence": {
"title": "Licence",
"type": "string"
},
"licence_url": {
"title": "Licence Url",
"type": "string"
},
"download_total": {
"title": "Download Total",
"type": "integer"
},
"download_total_human": {
"title": "Download Total Human",
"type": "string"
}
},
"required": [
"chosen",
"regions",
"fetch",
"current",
"licence",
"licence_url",
"download_total",
"download_total_human"
],
"title": "BareEarthSectionView",
"type": "object"
},
"BlockerLine": {
"additionalProperties": false,
"description": "One reason the transaction cannot be planned.",
"properties": {
"subject": {
"title": "Subject",
"type": "string"
},
"reason": {
"title": "Reason",
"type": "string"
},
"remedy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Remedy"
}
},
"required": [
"subject",
"reason",
"remedy"
],
"title": "BlockerLine",
"type": "object"
},
"BoundaryLine": {
"additionalProperties": false,
"description": "The country-border file merged into each region before conversion.",
"properties": {
"title": {
"title": "Title",
"type": "string"
},
"url": {
"title": "Url",
"type": "string"
},
"size": {
"title": "Size",
"type": "integer"
},
"size_human": {
"title": "Size Human",
"type": "string"
},
"licence": {
"title": "Licence",
"type": "string"
},
"verified_by": {
"title": "Verified By",
"type": "string"
}
},
"required": [
"title",
"url",
"size",
"size_human",
"licence",
"verified_by"
],
"title": "BoundaryLine",
"type": "object"
},
"ConfigLine": {
"additionalProperties": false,
"description": "A configuration file the transaction writes.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"path": {
"title": "Path",
"type": "string"
},
"mode": {
"title": "Mode",
"type": "string"
},
"append": {
"title": "Append",
"type": "boolean"
},
"backup_existing": {
"title": "Backup Existing",
"type": "boolean"
},
"fills": {
"items": {
"type": "string"
},
"title": "Fills",
"type": "array"
}
},
"required": [
"unit",
"path",
"mode",
"append",
"backup_existing",
"fills"
],
"title": "ConfigLine",
"type": "object"
},
"ConvertLine": {
"additionalProperties": false,
"description": "A region converted for Navit this run.",
"properties": {
"region": {
"title": "Region",
"type": "string"
},
"snapshot": {
"title": "Snapshot",
"type": "string"
},
"estimate": {
"title": "Estimate",
"type": "integer"
},
"estimate_human": {
"title": "Estimate Human",
"type": "string"
},
"countries": {
"items": {
"type": "string"
},
"title": "Countries",
"type": "array"
},
"converter_changed": {
"title": "Converter Changed",
"type": "boolean"
}
},
"required": [
"region",
"snapshot",
"estimate",
"estimate_human",
"countries",
"converter_changed"
],
"title": "ConvertLine",
"type": "object"
},
"DataArtifactLine": {
"additionalProperties": false,
"description": "One file of an offline dataset.",
"properties": {
"url": {
"title": "Url",
"type": "string"
},
"size": {
"title": "Size",
"type": "integer"
},
"size_human": {
"title": "Size Human",
"type": "string"
}
},
"required": [
"url",
"size",
"size_human"
],
"title": "DataArtifactLine",
"type": "object"
},
"DataLine": {
"additionalProperties": false,
"description": "An offline-data unit: sizes and licence, before anything downloads (D-049).",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"total_size": {
"title": "Total Size",
"type": "integer"
},
"total_human": {
"title": "Total Human",
"type": "string"
},
"licence": {
"title": "Licence",
"type": "string"
},
"licence_url": {
"title": "Licence Url",
"type": "string"
},
"artifacts": {
"items": {
"$ref": "#/$defs/DataArtifactLine"
},
"title": "Artifacts",
"type": "array"
},
"installs_under": {
"title": "Installs Under",
"type": "string"
},
"verified_by": {
"title": "Verified By",
"type": "string"
},
"approximate": {
"title": "Approximate",
"type": "boolean"
}
},
"required": [
"unit",
"total_size",
"total_human",
"licence",
"licence_url",
"artifacts",
"installs_under",
"verified_by",
"approximate"
],
"title": "DataLine",
"type": "object"
},
"DeferralLine": {
"additionalProperties": false,
"description": "Part of the request that will not happen; the rest still does (D-035, D-039, D-060).",
"properties": {
"kind": {
"title": "Kind",
"type": "string"
},
"subject": {
"title": "Subject",
"type": "string"
},
"what": {
"title": "What",
"type": "string"
},
"why": {
"title": "Why",
"type": "string"
},
"remedy": {
"title": "Remedy",
"type": "string"
}
},
"required": [
"kind",
"subject",
"what",
"why",
"remedy"
],
"title": "DeferralLine",
"type": "object"
},
"DesktopsReadView": {
"additionalProperties": false,
"description": "What the session files said, when a unit in the request is for particular desktops (D-060).",
"properties": {
"desktops": {
"items": {
"type": "string"
},
"title": "Desktops",
"type": "array"
},
"unrecognised": {
"items": {
"type": "string"
},
"title": "Unrecognised",
"type": "array"
},
"summary": {
"title": "Summary",
"type": "string"
}
},
"required": [
"desktops",
"unrecognised",
"summary"
],
"title": "DesktopsReadView",
"type": "object"
},
"DisplacedLine": {
"additionalProperties": false,
"description": "An installed distribution package a unit displaces or shadows (D-022).",
"properties": {
"package": {
"title": "Package",
"type": "string"
},
"declared_by": {
"title": "Declared By",
"type": "string"
}
},
"required": [
"package",
"declared_by"
],
"title": "DisplacedLine",
"type": "object"
},
"FileCapabilityLine": {
"additionalProperties": false,
"description": "A capability grant to one installed binary.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"path": {
"title": "Path",
"type": "string"
},
"capabilities": {
"items": {
"type": "string"
},
"title": "Capabilities",
"type": "array"
},
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"unit",
"path",
"capabilities",
"detail"
],
"title": "FileCapabilityLine",
"type": "object"
},
"FsTopoSectionView": {
"additionalProperties": false,
"description": "Forest Service FSTopo sheets and QMapShack's FSTopo map (D-068,\namended 2026-10-01). Local only.",
"properties": {
"regions": {
"items": {
"$ref": "#/$defs/SheetRegionLine"
},
"title": "Regions",
"type": "array"
},
"no_quads": {
"items": {
"type": "string"
},
"title": "No Quads",
"type": "array"
},
"fetch": {
"items": {
"$ref": "#/$defs/QuadLine"
},
"title": "Fetch",
"type": "array"
},
"unverified": {
"title": "Unverified",
"type": "integer"
},
"current": {
"title": "Current",
"type": "integer"
},
"licence": {
"title": "Licence",
"type": "string"
},
"licence_url": {
"title": "Licence Url",
"type": "string"
},
"download_total": {
"title": "Download Total",
"type": "integer"
},
"download_total_human": {
"title": "Download Total Human",
"type": "string"
},
"convert": {
"title": "Convert",
"type": "integer"
},
"convert_estimate": {
"title": "Convert Estimate",
"type": "integer"
},
"convert_estimate_human": {
"title": "Convert Estimate Human",
"type": "string"
},
"disk_total": {
"title": "Disk Total",
"type": "integer"
},
"disk_total_human": {
"title": "Disk Total Human",
"type": "string"
},
"estimate_note": {
"title": "Estimate Note",
"type": "string"
}
},
"required": [
"regions",
"no_quads",
"fetch",
"unverified",
"current",
"licence",
"licence_url",
"download_total",
"download_total_human",
"convert",
"convert_estimate",
"convert_estimate_human",
"disk_total",
"disk_total_human",
"estimate_note"
],
"title": "FsTopoSectionView",
"type": "object"
},
"GarminLine": {
"additionalProperties": false,
"description": "A region mkgmap builds a Garmin map from this run.",
"properties": {
"region": {
"title": "Region",
"type": "string"
},
"snapshot": {
"title": "Snapshot",
"type": "string"
},
"estimate": {
"title": "Estimate",
"type": "integer"
},
"estimate_human": {
"title": "Estimate Human",
"type": "string"
}
},
"required": [
"region",
"snapshot",
"estimate",
"estimate_human"
],
"title": "GarminLine",
"type": "object"
},
"GateLine": {
"additionalProperties": false,
"description": "A consent gate the real run will present (D-021). Never answered through JSON.",
"properties": {
"profile": {
"title": "Profile",
"type": "string"
},
"env_var": {
"title": "Env Var",
"type": "string"
},
"risk_lines": {
"items": {
"type": "string"
},
"title": "Risk Lines",
"type": "array"
}
},
"required": [
"profile",
"env_var",
"risk_lines"
],
"title": "GateLine",
"type": "object"
},
"InstallPlanView": {
"additionalProperties": false,
"description": "Everything an install will do, section by section as the text prints it.",
"properties": {
"packages": {
"items": {
"$ref": "#/$defs/PackageLine"
},
"title": "Packages",
"type": "array"
},
"displaced": {
"items": {
"$ref": "#/$defs/DisplacedLine"
},
"title": "Displaced",
"type": "array"
},
"apt_release": {
"anyOf": [
{
"$ref": "#/$defs/ReleaseSection"
},
{
"type": "null"
}
]
},
"no_recommends": {
"anyOf": [
{
"$ref": "#/$defs/NoRecommendsSection"
},
{
"type": "null"
}
]
},
"repos": {
"items": {
"$ref": "#/$defs/RepoLine"
},
"title": "Repos",
"type": "array"
},
"mirror": {
"anyOf": [
{
"$ref": "#/$defs/MirrorSection"
},
{
"type": "null"
}
]
},
"data": {
"items": {
"$ref": "#/$defs/DataLine"
},
"title": "Data",
"type": "array"
},
"maps": {
"anyOf": [
{
"$ref": "#/$defs/MapSectionView"
},
{
"type": "null"
}
]
},
"memberships": {
"items": {
"$ref": "#/$defs/MembershipLine"
},
"title": "Memberships",
"type": "array"
},
"file_capabilities": {
"items": {
"$ref": "#/$defs/FileCapabilityLine"
},
"title": "File Capabilities",
"type": "array"
},
"consent_gates": {
"items": {
"$ref": "#/$defs/GateLine"
},
"title": "Consent Gates",
"type": "array"
},
"config_files": {
"items": {
"$ref": "#/$defs/ConfigLine"
},
"title": "Config Files",
"type": "array"
},
"user_services": {
"items": {
"$ref": "#/$defs/UserServiceLine"
},
"title": "User Services",
"type": "array"
},
"desktops_read": {
"anyOf": [
{
"$ref": "#/$defs/DesktopsReadView"
},
{
"type": "null"
}
]
},
"deferrals": {
"items": {
"$ref": "#/$defs/DeferralLine"
},
"title": "Deferrals",
"type": "array"
},
"notes": {
"items": {
"type": "string"
},
"title": "Notes",
"type": "array"
},
"records": {
"anyOf": [
{
"$ref": "#/$defs/RecordsLine"
},
{
"type": "null"
}
]
},
"sudo": {
"anyOf": [
{
"$ref": "#/$defs/SudoLine"
},
{
"type": "null"
}
]
},
"commands": {
"items": {
"$ref": "#/$defs/StepView"
},
"title": "Commands",
"type": "array"
},
"suggestion_notes": {
"items": {
"type": "string"
},
"title": "Suggestion Notes",
"type": "array"
},
"region_notes": {
"items": {
"type": "string"
},
"title": "Region Notes",
"type": "array"
},
"publisher_checks": {
"items": {
"$ref": "#/$defs/PublisherCheckLine"
},
"title": "Publisher Checks",
"type": "array"
}
},
"required": [
"packages",
"displaced",
"apt_release",
"no_recommends",
"repos",
"mirror",
"data",
"maps",
"memberships",
"file_capabilities",
"consent_gates",
"config_files",
"user_services",
"desktops_read",
"deferrals",
"notes",
"records",
"sudo",
"commands",
"suggestion_notes",
"region_notes",
"publisher_checks"
],
"title": "InstallPlanView",
"type": "object"
},
"KeptLine": {
"additionalProperties": false,
"description": "An installed region that could not be checked for a newer map; kept.",
"properties": {
"region": {
"title": "Region",
"type": "string"
},
"snapshot": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Snapshot"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"region",
"snapshot",
"reason"
],
"title": "KeptLine",
"type": "object"
},
"MapSectionView": {
"additionalProperties": false,
"description": "The station's map regions (D-057). Names where the operator is: local only.",
"properties": {
"fetch": {
"items": {
"$ref": "#/$defs/RegionLine"
},
"title": "Fetch",
"type": "array"
},
"current": {
"items": {
"$ref": "#/$defs/RegionLine"
},
"title": "Current",
"type": "array"
},
"convert": {
"items": {
"$ref": "#/$defs/ConvertLine"
},
"title": "Convert",
"type": "array"
},
"kept": {
"items": {
"$ref": "#/$defs/KeptLine"
},
"title": "Kept",
"type": "array"
},
"licence": {
"title": "Licence",
"type": "string"
},
"licence_url": {
"title": "Licence Url",
"type": "string"
},
"download_total": {
"title": "Download Total",
"type": "integer"
},
"download_total_human": {
"title": "Download Total Human",
"type": "string"
},
"disk_total": {
"title": "Disk Total",
"type": "integer"
},
"disk_total_human": {
"title": "Disk Total Human",
"type": "string"
},
"estimate_note": {
"title": "Estimate Note",
"type": "string"
},
"terrain": {
"anyOf": [
{
"$ref": "#/$defs/TerrainSectionView"
},
{
"type": "null"
}
]
},
"boundaries": {
"anyOf": [
{
"$ref": "#/$defs/BoundaryLine"
},
{
"type": "null"
}
]
},
"unknown_country": {
"title": "Unknown Country",
"type": "boolean"
}
},
"required": [
"fetch",
"current",
"convert",
"kept",
"licence",
"licence_url",
"download_total",
"download_total_human",
"disk_total",
"disk_total_human",
"estimate_note",
"terrain",
"boundaries",
"unknown_country"
],
"title": "MapSectionView",
"type": "object"
},
"MembershipLine": {
"additionalProperties": false,
"description": "A group the operator is added to, and what it grants.",
"properties": {
"user": {
"title": "User",
"type": "string"
},
"group": {
"title": "Group",
"type": "string"
},
"package": {
"title": "Package",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"reverse_hint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reverse Hint"
}
},
"required": [
"user",
"group",
"package",
"detail",
"reverse_hint"
],
"title": "MembershipLine",
"type": "object"
},
"MirrorSection": {
"additionalProperties": false,
"description": "The LAN mirror a data download is asked for first (D-070).",
"properties": {
"url": {
"title": "Url",
"type": "string"
},
"ignored": {
"title": "Ignored",
"type": "boolean"
},
"text": {
"title": "Text",
"type": "string"
}
},
"required": [
"url",
"ignored",
"text"
],
"title": "MirrorSection",
"type": "object"
},
"NoRecommendsSection": {
"additionalProperties": false,
"description": "apt packages installed by a second command without Recommends (D-052).",
"properties": {
"units": {
"items": {
"type": "string"
},
"title": "Units",
"type": "array"
},
"packages": {
"items": {
"type": "string"
},
"title": "Packages",
"type": "array"
}
},
"required": [
"units",
"packages"
],
"title": "NoRecommendsSection",
"type": "object"
},
"PackageLine": {
"additionalProperties": false,
"description": "One catalog unit in the plan.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"method": {
"title": "Method",
"type": "string"
},
"state": {
"title": "State",
"type": "string"
},
"requested_by": {
"items": {
"type": "string"
},
"title": "Requested By",
"type": "array"
},
"apt": {
"items": {
"$ref": "#/$defs/AptLine"
},
"title": "Apt",
"type": "array"
}
},
"required": [
"name",
"method",
"state",
"requested_by",
"apt"
],
"title": "PackageLine",
"type": "object"
},
"PublisherCheckLine": {
"additionalProperties": false,
"description": "What the plan did about one installed data item's publisher (#197).",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"item": {
"title": "Item",
"type": "string"
},
"checked": {
"title": "Checked",
"type": "boolean"
},
"reason": {
"title": "Reason",
"type": "string"
},
"attributed": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Attributed"
}
},
"required": [
"unit",
"item",
"checked",
"reason",
"attributed"
],
"title": "PublisherCheckLine",
"type": "object"
},
"QuadLine": {
"additionalProperties": false,
"description": "One US Topo quad downloaded this run.",
"properties": {
"quad": {
"title": "Quad",
"type": "string"
},
"size": {
"title": "Size",
"type": "integer"
},
"size_human": {
"title": "Size Human",
"type": "string"
},
"verified_by": {
"title": "Verified By",
"type": "string"
}
},
"required": [
"quad",
"size",
"size_human",
"verified_by"
],
"title": "QuadLine",
"type": "object"
},
"RecordsLine": {
"additionalProperties": false,
"description": "Where the transaction log is written.",
"properties": {
"log": {
"title": "Log",
"type": "string"
},
"handed_to": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Handed To"
}
},
"required": [
"log",
"handed_to"
],
"title": "RecordsLine",
"type": "object"
},
"RegionLine": {
"additionalProperties": false,
"description": "One map region file.",
"properties": {
"region": {
"title": "Region",
"type": "string"
},
"snapshot": {
"title": "Snapshot",
"type": "string"
},
"size": {
"title": "Size",
"type": "integer"
},
"size_human": {
"title": "Size Human",
"type": "string"
},
"verified_by": {
"title": "Verified By",
"type": "string"
},
"nothing_to_do": {
"title": "Nothing To Do",
"type": "boolean"
}
},
"required": [
"region",
"snapshot",
"size",
"size_human",
"verified_by",
"nothing_to_do"
],
"title": "RegionLine",
"type": "object"
},
"ReleaseSection": {
"additionalProperties": false,
"description": "apt packages taken from another release this machine installs from (D-038).",
"properties": {
"release": {
"title": "Release",
"type": "string"
},
"packages": {
"items": {
"type": "string"
},
"title": "Packages",
"type": "array"
}
},
"required": [
"release",
"packages"
],
"title": "ReleaseSection",
"type": "object"
},
"RemovalPlanView": {
"additionalProperties": false,
"description": "Everything an uninstall will do, section by section as the text prints it.",
"properties": {
"to_remove": {
"items": {
"$ref": "#/$defs/UnitPackages"
},
"title": "To Remove",
"type": "array"
},
"artifacts": {
"items": {
"$ref": "#/$defs/ArtifactLine"
},
"title": "Artifacts",
"type": "array"
},
"left_unattributed": {
"items": {
"$ref": "#/$defs/UnitFiles"
},
"title": "Left Unattributed",
"type": "array"
},
"left_foreign": {
"items": {
"$ref": "#/$defs/UnitPackages"
},
"title": "Left Foreign",
"type": "array"
},
"already_absent": {
"items": {
"$ref": "#/$defs/UnitPackages"
},
"title": "Already Absent",
"type": "array"
},
"not_reversed": {
"title": "Not Reversed",
"type": "string"
},
"commands": {
"items": {
"$ref": "#/$defs/StepView"
},
"title": "Commands",
"type": "array"
}
},
"required": [
"to_remove",
"artifacts",
"left_unattributed",
"left_foreign",
"already_absent",
"not_reversed",
"commands"
],
"title": "RemovalPlanView",
"type": "object"
},
"RepoLine": {
"additionalProperties": false,
"description": "A third-party apt repository the transaction adds, behind its own gate (D-040).",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"unit": {
"title": "Unit",
"type": "string"
},
"packages": {
"items": {
"type": "string"
},
"title": "Packages",
"type": "array"
},
"uri": {
"title": "Uri",
"type": "string"
},
"suites": {
"items": {
"type": "string"
},
"title": "Suites",
"type": "array"
},
"components": {
"items": {
"type": "string"
},
"title": "Components",
"type": "array"
},
"key_fingerprint": {
"title": "Key Fingerprint",
"type": "string"
},
"sources": {
"title": "Sources",
"type": "string"
},
"keyring": {
"title": "Keyring",
"type": "string"
},
"consent_env_var": {
"title": "Consent Env Var",
"type": "string"
}
},
"required": [
"name",
"unit",
"packages",
"uri",
"suites",
"components",
"key_fingerprint",
"sources",
"keyring",
"consent_env_var"
],
"title": "RepoLine",
"type": "object"
},
"SheetRegionLine": {
"additionalProperties": false,
"description": "The FSTopo quads one region needs (D-068, amended 2026-10-01).",
"properties": {
"region": {
"title": "Region",
"type": "string"
},
"quads": {
"title": "Quads",
"type": "integer"
},
"download": {
"title": "Download",
"type": "integer"
},
"download_human": {
"title": "Download Human",
"type": "string"
},
"all_pinned": {
"title": "All Pinned",
"type": "boolean"
}
},
"required": [
"region",
"quads",
"download",
"download_human",
"all_pinned"
],
"title": "SheetRegionLine",
"type": "object"
},
"StepView": {
"additionalProperties": false,
"description": "One step, exactly as the real run performs it.",
"properties": {
"description": {
"title": "Description",
"type": "string"
},
"display": {
"title": "Display",
"type": "string"
},
"argv": {
"items": {
"type": "string"
},
"title": "Argv",
"type": "array"
},
"action": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Action"
},
"requires_root": {
"title": "Requires Root",
"type": "boolean"
},
"sources": {
"items": {
"type": "string"
},
"title": "Sources",
"type": "array"
},
"index": {
"title": "Index",
"type": "integer"
},
"long_running": {
"default": false,
"title": "Long Running",
"type": "boolean"
}
},
"required": [
"description",
"display",
"argv",
"action",
"requires_root",
"sources",
"index"
],
"title": "StepView",
"type": "object"
},
"SudoLine": {
"additionalProperties": false,
"description": "How a run as a user keeps sudo from asking twice (D-062).",
"properties": {
"keepalive": {
"title": "Keepalive",
"type": "boolean"
},
"interval_seconds": {
"title": "Interval Seconds",
"type": "integer"
},
"text": {
"title": "Text",
"type": "string"
}
},
"required": [
"keepalive",
"interval_seconds",
"text"
],
"title": "SudoLine",
"type": "object"
},
"TargetView": {
"additionalProperties": false,
"description": "What `/etc/os-release` said, verbatim, with the one line the text prints.",
"properties": {
"distro": {
"title": "Distro",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"arch": {
"title": "Arch",
"type": "string"
},
"id_like": {
"items": {
"type": "string"
},
"title": "Id Like",
"type": "array"
},
"pretty_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pretty Name"
},
"description": {
"title": "Description",
"type": "string"
},
"debian_family": {
"title": "Debian Family",
"type": "boolean"
}
},
"required": [
"distro",
"version",
"arch",
"id_like",
"pretty_name",
"description",
"debian_family"
],
"title": "TargetView",
"type": "object"
},
"TerrainRegionLine": {
"additionalProperties": false,
"description": "The terrain tiles one region needs (D-061).",
"properties": {
"region": {
"title": "Region",
"type": "string"
},
"tiles": {
"title": "Tiles",
"type": "integer"
},
"unpublished": {
"title": "Unpublished",
"type": "integer"
},
"no_terrain": {
"title": "No Terrain",
"type": "boolean"
},
"download": {
"title": "Download",
"type": "integer"
},
"download_human": {
"title": "Download Human",
"type": "string"
}
},
"required": [
"region",
"tiles",
"unpublished",
"no_terrain",
"download",
"download_human"
],
"title": "TerrainRegionLine",
"type": "object"
},
"TerrainSectionView": {
"additionalProperties": false,
"description": "Terrain, and what is built for QMapShack (D-061). Names where the operator is: local only.",
"properties": {
"regions": {
"items": {
"$ref": "#/$defs/TerrainRegionLine"
},
"title": "Regions",
"type": "array"
},
"fetch": {
"items": {
"$ref": "#/$defs/TileLine"
},
"title": "Fetch",
"type": "array"
},
"current": {
"title": "Current",
"type": "integer"
},
"licence": {
"title": "Licence",
"type": "string"
},
"licence_url": {
"title": "Licence Url",
"type": "string"
},
"download_total": {
"title": "Download Total",
"type": "integer"
},
"download_total_human": {
"title": "Download Total Human",
"type": "string"
},
"garmin": {
"items": {
"$ref": "#/$defs/GarminLine"
},
"title": "Garmin",
"type": "array"
},
"routino_regions": {
"title": "Routino Regions",
"type": "integer"
},
"routino_estimate": {
"title": "Routino Estimate",
"type": "integer"
},
"routino_estimate_human": {
"title": "Routino Estimate Human",
"type": "string"
},
"contours": {
"title": "Contours",
"type": "integer"
},
"contours_estimate": {
"title": "Contours Estimate",
"type": "integer"
},
"contours_estimate_human": {
"title": "Contours Estimate Human",
"type": "string"
},
"brouter_regions": {
"title": "Brouter Regions",
"type": "integer"
},
"brouter_tiles": {
"title": "Brouter Tiles",
"type": "integer"
},
"brouter_estimate": {
"title": "Brouter Estimate",
"type": "integer"
},
"brouter_estimate_human": {
"title": "Brouter Estimate Human",
"type": "string"
},
"disk_total": {
"title": "Disk Total",
"type": "integer"
},
"disk_total_human": {
"title": "Disk Total Human",
"type": "string"
},
"estimate_note": {
"title": "Estimate Note",
"type": "string"
},
"topo": {
"anyOf": [
{
"$ref": "#/$defs/TopoSectionView"
},
{
"type": "null"
}
]
},
"contours_from": {
"title": "Contours From",
"type": "string"
},
"bare_earth": {
"anyOf": [
{
"$ref": "#/$defs/BareEarthSectionView"
},
{
"type": "null"
}
]
},
"fstopo": {
"anyOf": [
{
"$ref": "#/$defs/FsTopoSectionView"
},
{
"type": "null"
}
]
},
"splat_tiles": {
"title": "Splat Tiles",
"type": "integer"
},
"splat_estimate": {
"title": "Splat Estimate",
"type": "integer"
},
"splat_estimate_human": {
"title": "Splat Estimate Human",
"type": "string"
}
},
"required": [
"regions",
"fetch",
"current",
"licence",
"licence_url",
"download_total",
"download_total_human",
"garmin",
"routino_regions",
"routino_estimate",
"routino_estimate_human",
"contours",
"contours_estimate",
"contours_estimate_human",
"brouter_regions",
"brouter_tiles",
"brouter_estimate",
"brouter_estimate_human",
"disk_total",
"disk_total_human",
"estimate_note",
"topo",
"contours_from",
"bare_earth",
"fstopo",
"splat_tiles",
"splat_estimate",
"splat_estimate_human"
],
"title": "TerrainSectionView",
"type": "object"
},
"TileLine": {
"additionalProperties": false,
"description": "One terrain tile downloaded this run.",
"properties": {
"tile": {
"title": "Tile",
"type": "string"
},
"size": {
"title": "Size",
"type": "integer"
},
"size_human": {
"title": "Size Human",
"type": "string"
},
"verified_by": {
"title": "Verified By",
"type": "string"
}
},
"required": [
"tile",
"size",
"size_human",
"verified_by"
],
"title": "TileLine",
"type": "object"
},
"TopoRegionLine": {
"additionalProperties": false,
"description": "The US Topo quads one region needs (D-068).",
"properties": {
"region": {
"title": "Region",
"type": "string"
},
"quads": {
"title": "Quads",
"type": "integer"
},
"size": {
"title": "Size",
"type": "integer"
},
"size_human": {
"title": "Size Human",
"type": "string"
},
"download": {
"title": "Download",
"type": "integer"
},
"download_human": {
"title": "Download Human",
"type": "string"
}
},
"required": [
"region",
"quads",
"size",
"size_human",
"download",
"download_human"
],
"title": "TopoRegionLine",
"type": "object"
},
"TopoSectionView": {
"additionalProperties": false,
"description": "USGS US Topo sheets and QMapShack's mosaic of them (D-068). Local only.",
"properties": {
"regions": {
"items": {
"$ref": "#/$defs/TopoRegionLine"
},
"title": "Regions",
"type": "array"
},
"no_quads": {
"items": {
"type": "string"
},
"title": "No Quads",
"type": "array"
},
"fetch": {
"items": {
"$ref": "#/$defs/QuadLine"
},
"title": "Fetch",
"type": "array"
},
"current": {
"title": "Current",
"type": "integer"
},
"licence": {
"title": "Licence",
"type": "string"
},
"licence_url": {
"title": "Licence Url",
"type": "string"
},
"download_total": {
"title": "Download Total",
"type": "integer"
},
"download_total_human": {
"title": "Download Total Human",
"type": "string"
},
"warp": {
"title": "Warp",
"type": "integer"
},
"warp_estimate": {
"title": "Warp Estimate",
"type": "integer"
},
"warp_estimate_human": {
"title": "Warp Estimate Human",
"type": "string"
},
"disk_total": {
"title": "Disk Total",
"type": "integer"
},
"disk_total_human": {
"title": "Disk Total Human",
"type": "string"
},
"estimate_note": {
"title": "Estimate Note",
"type": "string"
},
"selection": {
"title": "Selection",
"type": "string"
},
"size_consent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Size Consent"
}
},
"required": [
"regions",
"no_quads",
"fetch",
"current",
"licence",
"licence_url",
"download_total",
"download_total_human",
"warp",
"warp_estimate",
"warp_estimate_human",
"disk_total",
"disk_total_human",
"estimate_note",
"selection",
"size_consent"
],
"title": "TopoSectionView",
"type": "object"
},
"UnitFiles": {
"additionalProperties": false,
"description": "A unit and files.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"paths": {
"items": {
"type": "string"
},
"title": "Paths",
"type": "array"
}
},
"required": [
"unit",
"paths"
],
"title": "UnitFiles",
"type": "object"
},
"UnitPackages": {
"additionalProperties": false,
"description": "A unit and apt packages.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"packages": {
"items": {
"type": "string"
},
"title": "Packages",
"type": "array"
}
},
"required": [
"unit",
"packages"
],
"title": "UnitPackages",
"type": "object"
},
"UserServiceLine": {
"additionalProperties": false,
"description": "A systemd user service the transaction writes and enables (D-073 §6b).\n\nThe command line is rendered with the device serial elided, and the\nstation values are named, never quoted — the same privacy split as the\nrest of the plan.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"path": {
"title": "Path",
"type": "string"
},
"exec": {
"title": "Exec",
"type": "string"
},
"fills": {
"items": {
"type": "string"
},
"title": "Fills",
"type": "array"
},
"listen": {
"title": "Listen",
"type": "string"
},
"starts_now": {
"title": "Starts Now",
"type": "boolean"
}
},
"required": [
"unit",
"name",
"path",
"exec",
"fills",
"listen",
"starts_now"
],
"title": "UserServiceLine",
"type": "object"
}
},
"additionalProperties": false,
"description": "The plan `install --dry-run` or `uninstall --dry-run` prints, as data.\n\nA refused transaction is still a `plan`, with `outcome: \"refused\"`, every\nblocker, and exit code 2. Includes the paths of files written for the\noperator; for local programs, not for pasting.",
"properties": {
"action": {
"title": "Action",
"type": "string"
},
"requested": {
"items": {
"type": "string"
},
"title": "Requested",
"type": "array"
},
"outcome": {
"title": "Outcome",
"type": "string"
},
"step_count": {
"title": "Step Count",
"type": "integer"
},
"target": {
"$ref": "#/$defs/TargetView"
},
"blockers": {
"items": {
"$ref": "#/$defs/BlockerLine"
},
"title": "Blockers",
"type": "array"
},
"install": {
"anyOf": [
{
"$ref": "#/$defs/InstallPlanView"
},
{
"type": "null"
}
]
},
"removal": {
"anyOf": [
{
"$ref": "#/$defs/RemovalPlanView"
},
{
"type": "null"
}
]
}
},
"required": [
"action",
"requested",
"outcome",
"step_count",
"target",
"blockers",
"install",
"removal"
],
"title": "PlanDocument",
"type": "object"
}
profile¶
One profile, everything show prints, disclosure included.
| field | type | meaning |
|---|---|---|
name |
string | the profile |
summary |
string | one line |
stage |
string | 1.0 or post-1.0 |
documentation |
ProfileDocs |
its documentation |
consent |
ConsentView or null |
its consent gate; null when ungated |
packages |
list of string | its member units |
suggests_one_of |
list of SuggestionView |
choices it offers |
ConsentView¶
A profile's consent gate, as show discloses it.
| field | type | meaning |
|---|---|---|
env_var |
string | the scripted-consent variable |
risk_categories |
list of string | the capabilities disclosed |
disclosure |
string | the exact text the gate shows |
SuggestionView¶
A choice the profile offers when nothing already answers it.
| field | type | meaning |
|---|---|---|
name |
string | what is suggested, e.g. a logger |
reason |
string | why |
options |
list of string | the units offered |
recommended |
string or null | the default choice |
detect_commands |
list of string | commands whose presence means one is installed |
JSON Schema
{
"$defs": {
"ConsentView": {
"additionalProperties": false,
"description": "A profile's consent gate, as `show` discloses it.",
"properties": {
"env_var": {
"title": "Env Var",
"type": "string"
},
"risk_categories": {
"items": {
"type": "string"
},
"title": "Risk Categories",
"type": "array"
},
"disclosure": {
"title": "Disclosure",
"type": "string"
}
},
"required": [
"env_var",
"risk_categories",
"disclosure"
],
"title": "ConsentView",
"type": "object"
},
"ProfileDocs": {
"additionalProperties": false,
"description": "The documentation every profile carries (CLAUDE.md).",
"properties": {
"what_it_installs": {
"title": "What It Installs",
"type": "string"
},
"why_together": {
"title": "Why Together",
"type": "string"
},
"deliberately_excludes": {
"title": "Deliberately Excludes",
"type": "string"
},
"manual_configuration": {
"title": "Manual Configuration",
"type": "string"
},
"disk_footprint_hint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Disk Footprint Hint"
}
},
"required": [
"what_it_installs",
"why_together",
"deliberately_excludes",
"manual_configuration",
"disk_footprint_hint"
],
"title": "ProfileDocs",
"type": "object"
},
"SuggestionView": {
"additionalProperties": false,
"description": "A choice the profile offers when nothing already answers it.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"reason": {
"title": "Reason",
"type": "string"
},
"options": {
"items": {
"type": "string"
},
"title": "Options",
"type": "array"
},
"recommended": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Recommended"
},
"detect_commands": {
"items": {
"type": "string"
},
"title": "Detect Commands",
"type": "array"
}
},
"required": [
"name",
"reason",
"options",
"recommended",
"detect_commands"
],
"title": "SuggestionView",
"type": "object"
}
},
"additionalProperties": false,
"description": "One profile, everything `show` prints, disclosure included.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"summary": {
"title": "Summary",
"type": "string"
},
"stage": {
"title": "Stage",
"type": "string"
},
"documentation": {
"$ref": "#/$defs/ProfileDocs"
},
"consent": {
"anyOf": [
{
"$ref": "#/$defs/ConsentView"
},
{
"type": "null"
}
]
},
"packages": {
"items": {
"type": "string"
},
"title": "Packages",
"type": "array"
},
"suggests_one_of": {
"items": {
"$ref": "#/$defs/SuggestionView"
},
"title": "Suggests One Of",
"type": "array"
}
},
"required": [
"name",
"summary",
"stage",
"documentation",
"consent",
"packages",
"suggests_one_of"
],
"title": "ProfileDocument",
"type": "object"
}
regions¶
Geofabrik's region paths, filtered. Fetched from Geofabrik's index when this command runs, and only then; nothing here is the operator's.
| field | type | meaning |
|---|---|---|
filter |
string or null | the case-insensitive substring asked for; null for every region |
regions |
list of string | the matching region paths, in the index's order |
JSON Schema
{
"additionalProperties": false,
"description": "Geofabrik's region paths, filtered. Fetched from Geofabrik's index when\nthis command runs, and only then; nothing here is the operator's.",
"properties": {
"filter": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Filter"
},
"regions": {
"items": {
"type": "string"
},
"title": "Regions",
"type": "array"
}
},
"required": [
"filter",
"regions"
],
"title": "RegionsDocument",
"type": "object"
}
repeaters¶
A repeater layer written from the operator's own export, hearham's list on request (D-064), or one of D-074's sources. Counts and paths only: no repeater's callsign or position, and no region, is carried.
| field | type | meaning |
|---|---|---|
layer_id |
string | export (D-064's layer), open-repeater, osm, etcc, brandmeister or aprs-heard (D-074), acma (D-074, amended 2026-10-01), repeaterbook-<AREA> (one per state, #325) |
layer |
string | the layer's name, as QMapShack's project and POI file show it |
exported |
string | YYYY-MM-DD: --exported, else the oldest input's modification date; a fetch's own date |
licences |
list of string | each source's licence text, printed before anything |
inputs |
list of InputView |
each file read, in the order given |
read |
integer | rows read over every input |
skipped |
integer | rows left out over every input |
merged |
integer | rows merged into another: same callsign, output frequency and position to 0.01 degree |
written |
integer | repeaters in the layer |
directory |
string | where the layer's files are, mode 0700 |
files |
list of string | the files written, mode 0600: GPX, POI, Navit textfile and the rows as data |
registered |
list of RegistrationView |
QMapShack's and Navit's, in that order, for every layer present |
all_sources |
AllSourcesView |
the all-sources file, rebuilt after the write |
InputView¶
One file read.
| field | type | meaning |
|---|---|---|
path |
string | the file as given; a fetch's URL; for osm-extract, the directory of the region extracts, never a region's name |
format |
string | repeaterbook-gpx, repeaterbook-csv, hearham-json or hand-csv (D-064); open-repeater-json, osm-extract, etcc-csv, brandmeister-json or direwolf-log (D-074); acma-register (D-074, amended 2026-10-01) |
read |
integer | rows, objects, devices or waypoints in it; for acma-register, the transmitters on amateur repeater licences |
used |
integer | of those, the ones kept: a position and a callsign or frequency |
skipped |
list of SkipView |
the rest, by reason |
sha256 |
string | the digest of what was read (several logs: of their bytes in order); empty for osm-extract, whose extracts' digests would name the regions |
AllSourcesView¶
repeaters-all.gpx: the directory layers joined (D-074).
| field | type | meaning |
|---|---|---|
file |
string or null | the file, mode 0600; null when fewer than two directory layers could be read, and the file is then absent |
name |
string | its name, Repeaters (all sources, YYYY-MM-DD); empty when null |
layers |
list of string | the layer ids joined, in layer order |
written |
integer | repeaters in it |
merged |
integer | rows joined to another layer's: the same output frequency, and within 0.02 degree, or the same callsign within 0.25 degree |
skipped |
list of LayerSkipView |
layers that could not be read |
error |
string or null | why the file could not be rebuilt (the command then exits 1); null when it was |
LayerSkipView¶
A layer the all-sources file could not read.
| field | type | meaning |
|---|---|---|
layer |
string | the layer's id |
reason |
string | why it was left out |
JSON Schema
{
"$defs": {
"AllSourcesView": {
"additionalProperties": false,
"description": "``repeaters-all.gpx``: the directory layers joined (D-074).",
"properties": {
"file": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File"
},
"name": {
"title": "Name",
"type": "string"
},
"layers": {
"items": {
"type": "string"
},
"title": "Layers",
"type": "array"
},
"written": {
"title": "Written",
"type": "integer"
},
"merged": {
"title": "Merged",
"type": "integer"
},
"skipped": {
"items": {
"$ref": "#/$defs/LayerSkipView"
},
"title": "Skipped",
"type": "array"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
}
},
"required": [
"file",
"name",
"layers",
"written",
"merged",
"skipped",
"error"
],
"title": "AllSourcesView",
"type": "object"
},
"InputView": {
"additionalProperties": false,
"description": "One file read.",
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"format": {
"title": "Format",
"type": "string"
},
"read": {
"title": "Read",
"type": "integer"
},
"used": {
"title": "Used",
"type": "integer"
},
"skipped": {
"items": {
"$ref": "#/$defs/SkipView"
},
"title": "Skipped",
"type": "array"
},
"sha256": {
"title": "Sha256",
"type": "string"
}
},
"required": [
"path",
"format",
"read",
"used",
"skipped",
"sha256"
],
"title": "InputView",
"type": "object"
},
"LayerSkipView": {
"additionalProperties": false,
"description": "A layer the all-sources file could not read.",
"properties": {
"layer": {
"title": "Layer",
"type": "string"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"layer",
"reason"
],
"title": "LayerSkipView",
"type": "object"
},
"RegistrationView": {
"additionalProperties": false,
"description": "What a program was told about the layer.",
"properties": {
"program": {
"title": "Program",
"type": "string"
},
"config": {
"title": "Config",
"type": "string"
},
"outcome": {
"title": "Outcome",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"program",
"config",
"outcome",
"detail"
],
"title": "RegistrationView",
"type": "object"
},
"SkipView": {
"additionalProperties": false,
"description": "Rows of one input left out for one reason.",
"properties": {
"reason": {
"title": "Reason",
"type": "string"
},
"count": {
"title": "Count",
"type": "integer"
},
"first": {
"items": {
"type": "integer"
},
"title": "First",
"type": "array"
}
},
"required": [
"reason",
"count",
"first"
],
"title": "SkipView",
"type": "object"
}
},
"additionalProperties": false,
"description": "A repeater layer written from the operator's own export, hearham's\nlist on request (D-064), or one of D-074's sources. Counts and paths\nonly: no repeater's callsign or position, and no region, is carried.",
"properties": {
"layer_id": {
"title": "Layer Id",
"type": "string"
},
"layer": {
"title": "Layer",
"type": "string"
},
"exported": {
"title": "Exported",
"type": "string"
},
"licences": {
"items": {
"type": "string"
},
"title": "Licences",
"type": "array"
},
"inputs": {
"items": {
"$ref": "#/$defs/InputView"
},
"title": "Inputs",
"type": "array"
},
"read": {
"title": "Read",
"type": "integer"
},
"skipped": {
"title": "Skipped",
"type": "integer"
},
"merged": {
"title": "Merged",
"type": "integer"
},
"written": {
"title": "Written",
"type": "integer"
},
"directory": {
"title": "Directory",
"type": "string"
},
"files": {
"items": {
"type": "string"
},
"title": "Files",
"type": "array"
},
"registered": {
"items": {
"$ref": "#/$defs/RegistrationView"
},
"title": "Registered",
"type": "array"
},
"all_sources": {
"$ref": "#/$defs/AllSourcesView"
}
},
"required": [
"layer_id",
"layer",
"exported",
"licences",
"inputs",
"read",
"skipped",
"merged",
"written",
"directory",
"files",
"registered",
"all_sources"
],
"title": "RepeatersDocument",
"type": "object"
}
repeaters-list¶
The repeater layers on this machine, read back, for a program. Read-only:
nothing is written, fetched or rebuilt. A layer that cannot be read is in
skipped and the rest is returned, with exit 0; an empty directory is an
empty document. Carries every row, so it is for local programs, not for
pasting. D-074 (amended 2026-10-04).
| field | type | meaning |
|---|---|---|
directory |
string | where the layers are |
layers |
list of LayerView |
every layer read, in layer order, the heard layer (aprs-heard) included |
skipped |
list of LayerSkipView |
layers asked for or present that were not read, and why: no rows file, an unreadable one, an id that is not a layer, a layer not present |
rows |
list of RowView |
the layers joined as repeaters-all.gpx is (D-074), in memory, without the heard layer |
merged |
integer | rows joined to another layer's |
credits |
list of string | one attribution or licence text per distinct source present, to print beside the map |
centre |
CentreView or null |
where distances are measured from: --near, else the station's grid square when one is set; null when neither, and every row's distance_km is then null |
within_km |
--within: rows farther than this from centre were left out; null when not asked |
LayerView¶
One layer read from the overlay directory.
| field | type | meaning |
|---|---|---|
id |
string | the layer's id: export, acma, open-repeater, osm, etcc, brandmeister, aprs-heard, repeaterbook (the earlier merged layer) or repeaterbook-<AREA>, one per state (repeaterbook-OH; RepeaterBook's state_id outside the US) |
area |
string or null | the <AREA> of a per-state layer (OH, CA01), null for every other layer, so a front end can group by it |
active |
boolean | whether the layer's area is active (D-082): true for a layer that belongs to no area, and for every layer while the station's active_areas is unset. A front end draws only active layers by default |
name |
string | the layer's name, as QMapShack's project shows it |
description |
string | the layer's description, which carries each source's licence |
day |
string | YYYY-MM-DD: the layer's date |
rows |
integer | repeaters in the layer |
sources |
list of string | the distinct sources of its rows, as repeaterbook-api, open-repeater-json and the like |
personal_use |
boolean | true when any source is RepeaterBook's: its terms keep the rows on this machine (D-081) |
unverified |
boolean | true when any source is one the engine records as unverified: hearham, ETCC, Brandmeister, the ACMA register, RepeaterBook's API |
files |
list of string | the layer's files that exist: GPX, POI, Navit, rows |
RowView¶
One repeater, after the layers were joined.
| field | type | meaning |
|---|---|---|
callsign |
string | empty only for a waypoint whose name gave none |
output_hz |
integer | output frequency in Hz; 0 only when a waypoint gave none |
offset_hz |
integer or null | transmit minus receive in Hz, signed; null when unknown |
tone |
string | CTCSS in Hz as text; empty for none |
mode |
string | FM, FM, DMR and the like: modes joined, or the source's own words when they say more than the vocabulary does; empty when unknown |
modes |
list of string | what it speaks, from FM, DMR, D-STAR, YSF, P25, NXDN, M17, TETRA, ATV, in that order; empty when the source says nothing or says a word outside the list (which stays in mode) |
band |
string | 10m, 6m, 2m, 1.25m, 70cm, 33cm, 23cm, 13cm from the output frequency, else other |
digital |
object | digital details the source supplied, never invented: dmr_color_code, dmr_network, dmr_id, dstar_module, dstar_gateway, ysf_dgid, p25_nac, nxdn_ran; empty when it supplied none |
distance_km |
great-circle kilometres from centre (haversine, 6371.0088 km sphere); null when there is no centre |
|
bearing_deg |
initial bearing from centre in degrees, 0 to 360, 0 north; null when there is no centre |
|
place |
string | where it is, as the source says |
notes |
string | the source's notes |
use |
string | OPEN, CLOSED and the like; empty when unknown |
status |
string | the source's status; empty when unknown |
updated |
string | when the source last updated it; empty when unknown |
label |
string | a waypoint's name, when it gave no callsign or frequency |
lat |
degrees north | |
lon |
degrees east | |
source |
string | the source of the row kept, best first (D-074's precedence) |
also |
list of string | other sources that list the same machine, best first |
layer |
string | the id of the layer the kept row came from |
personal_use |
boolean | true when the source or any of also is RepeaterBook's: do not serve this row beyond the machine (D-081) |
CentreView¶
The point distances and bearings are measured from.
| field | type | meaning |
|---|---|---|
lat |
degrees north | |
lon |
degrees east | |
source |
string | argument (--near) or station (the station's grid square: the centre of its square, so a program that shows this is showing the operator's area) |
JSON Schema
{
"$defs": {
"CentreView": {
"additionalProperties": false,
"description": "The point distances and bearings are measured from.",
"properties": {
"lat": {
"title": "Lat",
"type": "number"
},
"lon": {
"title": "Lon",
"type": "number"
},
"source": {
"title": "Source",
"type": "string"
}
},
"required": [
"lat",
"lon",
"source"
],
"title": "CentreView",
"type": "object"
},
"LayerSkipView": {
"additionalProperties": false,
"description": "A layer the all-sources file could not read.",
"properties": {
"layer": {
"title": "Layer",
"type": "string"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"layer",
"reason"
],
"title": "LayerSkipView",
"type": "object"
},
"LayerView": {
"additionalProperties": false,
"description": "One layer read from the overlay directory.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"area": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Area"
},
"active": {
"title": "Active",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"description": {
"title": "Description",
"type": "string"
},
"day": {
"title": "Day",
"type": "string"
},
"rows": {
"title": "Rows",
"type": "integer"
},
"sources": {
"items": {
"type": "string"
},
"title": "Sources",
"type": "array"
},
"personal_use": {
"title": "Personal Use",
"type": "boolean"
},
"unverified": {
"title": "Unverified",
"type": "boolean"
},
"files": {
"items": {
"type": "string"
},
"title": "Files",
"type": "array"
}
},
"required": [
"id",
"area",
"active",
"name",
"description",
"day",
"rows",
"sources",
"personal_use",
"unverified",
"files"
],
"title": "LayerView",
"type": "object"
},
"RowView": {
"additionalProperties": false,
"description": "One repeater, after the layers were joined.",
"properties": {
"callsign": {
"title": "Callsign",
"type": "string"
},
"output_hz": {
"title": "Output Hz",
"type": "integer"
},
"offset_hz": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Offset Hz"
},
"tone": {
"title": "Tone",
"type": "string"
},
"mode": {
"title": "Mode",
"type": "string"
},
"modes": {
"items": {
"type": "string"
},
"title": "Modes",
"type": "array"
},
"band": {
"title": "Band",
"type": "string"
},
"digital": {
"additionalProperties": {
"type": "string"
},
"title": "Digital",
"type": "object"
},
"distance_km": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Distance Km"
},
"bearing_deg": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Bearing Deg"
},
"place": {
"title": "Place",
"type": "string"
},
"notes": {
"title": "Notes",
"type": "string"
},
"use": {
"title": "Use",
"type": "string"
},
"status": {
"title": "Status",
"type": "string"
},
"updated": {
"title": "Updated",
"type": "string"
},
"label": {
"title": "Label",
"type": "string"
},
"lat": {
"title": "Lat",
"type": "number"
},
"lon": {
"title": "Lon",
"type": "number"
},
"source": {
"title": "Source",
"type": "string"
},
"also": {
"items": {
"type": "string"
},
"title": "Also",
"type": "array"
},
"layer": {
"title": "Layer",
"type": "string"
},
"personal_use": {
"title": "Personal Use",
"type": "boolean"
}
},
"required": [
"callsign",
"output_hz",
"offset_hz",
"tone",
"mode",
"modes",
"band",
"digital",
"distance_km",
"bearing_deg",
"place",
"notes",
"use",
"status",
"updated",
"label",
"lat",
"lon",
"source",
"also",
"layer",
"personal_use"
],
"title": "RowView",
"type": "object"
}
},
"additionalProperties": false,
"description": "The repeater layers on this machine, read back, for a program. Read-only:\nnothing is written, fetched or rebuilt. A layer that cannot be read is in\n`skipped` and the rest is returned, with exit 0; an empty directory is an\nempty document. Carries every row, so it is for local programs, not for\npasting. D-074 (amended 2026-10-04).",
"properties": {
"directory": {
"title": "Directory",
"type": "string"
},
"layers": {
"items": {
"$ref": "#/$defs/LayerView"
},
"title": "Layers",
"type": "array"
},
"skipped": {
"items": {
"$ref": "#/$defs/LayerSkipView"
},
"title": "Skipped",
"type": "array"
},
"rows": {
"items": {
"$ref": "#/$defs/RowView"
},
"title": "Rows",
"type": "array"
},
"merged": {
"title": "Merged",
"type": "integer"
},
"credits": {
"items": {
"type": "string"
},
"title": "Credits",
"type": "array"
},
"centre": {
"anyOf": [
{
"$ref": "#/$defs/CentreView"
},
{
"type": "null"
}
]
},
"within_km": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Within Km"
}
},
"required": [
"directory",
"layers",
"skipped",
"rows",
"merged",
"credits",
"centre",
"within_km"
],
"title": "RepeatersListDocument",
"type": "object"
}
repeaters-removed¶
Repeater layers deleted and unregistered. Removing nothing is not an error: every list is then empty.
| field | type | meaning |
|---|---|---|
directory |
string | where the layers are |
layers |
list of string | the layer ids asked for: the one --layer named, else every layer |
removed |
list of string | the files deleted |
unregistered |
list of RegistrationView |
QMapShack's and Navit's, in that order, for the layers left |
all_sources |
AllSourcesView |
the all-sources file, rebuilt from what is left |
JSON Schema
{
"$defs": {
"AllSourcesView": {
"additionalProperties": false,
"description": "``repeaters-all.gpx``: the directory layers joined (D-074).",
"properties": {
"file": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File"
},
"name": {
"title": "Name",
"type": "string"
},
"layers": {
"items": {
"type": "string"
},
"title": "Layers",
"type": "array"
},
"written": {
"title": "Written",
"type": "integer"
},
"merged": {
"title": "Merged",
"type": "integer"
},
"skipped": {
"items": {
"$ref": "#/$defs/LayerSkipView"
},
"title": "Skipped",
"type": "array"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
}
},
"required": [
"file",
"name",
"layers",
"written",
"merged",
"skipped",
"error"
],
"title": "AllSourcesView",
"type": "object"
},
"LayerSkipView": {
"additionalProperties": false,
"description": "A layer the all-sources file could not read.",
"properties": {
"layer": {
"title": "Layer",
"type": "string"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"layer",
"reason"
],
"title": "LayerSkipView",
"type": "object"
},
"RegistrationView": {
"additionalProperties": false,
"description": "What a program was told about the layer.",
"properties": {
"program": {
"title": "Program",
"type": "string"
},
"config": {
"title": "Config",
"type": "string"
},
"outcome": {
"title": "Outcome",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"program",
"config",
"outcome",
"detail"
],
"title": "RegistrationView",
"type": "object"
}
},
"additionalProperties": false,
"description": "Repeater layers deleted and unregistered. Removing nothing is not an\nerror: every list is then empty.",
"properties": {
"directory": {
"title": "Directory",
"type": "string"
},
"layers": {
"items": {
"type": "string"
},
"title": "Layers",
"type": "array"
},
"removed": {
"items": {
"type": "string"
},
"title": "Removed",
"type": "array"
},
"unregistered": {
"items": {
"$ref": "#/$defs/RegistrationView"
},
"title": "Unregistered",
"type": "array"
},
"all_sources": {
"$ref": "#/$defs/AllSourcesView"
}
},
"required": [
"directory",
"layers",
"removed",
"unregistered",
"all_sources"
],
"title": "RepeatersRemovedDocument",
"type": "object"
}
secrets¶
The secrets the engine knows and whether each is available now. Never a value, a prefix of one or its length.
| field | type | meaning |
|---|---|---|
doppler |
DopplerView |
the Doppler side of the answer |
secrets |
list of SecretView |
one entry per secret in the engine's registry |
DopplerView¶
Whether Doppler could answer: names set in the station and the CLI present.
| field | type | meaning |
|---|---|---|
project |
string or null | the station's Doppler project name; null when not set |
config |
string or null | the station's Doppler config name; null when not set |
configured |
boolean | both names are set in the station |
cli_on_path |
boolean | the doppler command is on PATH |
SecretView¶
One secret: its state now, how it would be answered and how to provide it.
| field | type | meaning |
|---|---|---|
name |
string | the environment variable and the Doppler secret name |
purpose |
string | what the secret is for, in a sentence |
available |
boolean | a source would answer: the variable is set, or Doppler is named and its CLI is present |
source |
string | environment, doppler (named and installed; not asked here) or none |
detail |
string | one sentence on why source is what it is |
unit |
string or null | the catalog unit that must be installed to use it, if any |
command |
string | the first command the secret unlocks |
get_url |
string | where to get one |
get_how |
string | what to ask for there |
doc |
string | the repository page that explains it |
ways |
list of string | the exact ways to provide it, as commands to run |
JSON Schema
{
"$defs": {
"DopplerView": {
"additionalProperties": false,
"description": "Whether Doppler could answer: names set in the station and the CLI present.",
"properties": {
"project": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project"
},
"config": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Config"
},
"configured": {
"title": "Configured",
"type": "boolean"
},
"cli_on_path": {
"title": "Cli On Path",
"type": "boolean"
}
},
"required": [
"project",
"config",
"configured",
"cli_on_path"
],
"title": "DopplerView",
"type": "object"
},
"SecretView": {
"additionalProperties": false,
"description": "One secret: its state now, how it would be answered and how to provide it.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"purpose": {
"title": "Purpose",
"type": "string"
},
"available": {
"title": "Available",
"type": "boolean"
},
"source": {
"title": "Source",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"unit": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Unit"
},
"command": {
"title": "Command",
"type": "string"
},
"get_url": {
"title": "Get Url",
"type": "string"
},
"get_how": {
"title": "Get How",
"type": "string"
},
"doc": {
"title": "Doc",
"type": "string"
},
"ways": {
"items": {
"type": "string"
},
"title": "Ways",
"type": "array"
}
},
"required": [
"name",
"purpose",
"available",
"source",
"detail",
"unit",
"command",
"get_url",
"get_how",
"doc",
"ways"
],
"title": "SecretView",
"type": "object"
}
},
"additionalProperties": false,
"description": "The secrets the engine knows and whether each is available now. Never a\nvalue, a prefix of one or its length.",
"properties": {
"doppler": {
"$ref": "#/$defs/DopplerView"
},
"secrets": {
"items": {
"$ref": "#/$defs/SecretView"
},
"title": "Secrets",
"type": "array"
}
},
"required": [
"doppler",
"secrets"
],
"title": "SecretsDocument",
"type": "object"
}
self-update¶
What self-update --dry-run would do to the engine's own checkout.
| field | type | meaning |
|---|---|---|
checkout |
string | the git work tree the running engine was imported from |
release |
boolean | whether --release chose the newest v* tag over origin/main |
target |
string | the ref the checkout would fast-forward to |
up_to_date |
boolean | the checkout already has the target; bootstrap still re-runs, which is what repairs a venv whose installed version lags |
checkout_version |
string or null | the version pyproject.toml declares now |
installed_version |
string or null | the version the venv's metadata reports now |
arriving |
list of string | git log --oneline HEAD..<target>, newest first, after the fetch; empty when up to date |
steps |
list of StepView |
the commands, in the order they run |
dry_run |
boolean | always true: a real run is never driven through JSON |
StepView¶
One command the update would run.
| field | type | meaning |
|---|---|---|
description |
string | what the step does, in words |
argv |
list of string | the command, argv form |
JSON Schema
{
"$defs": {
"StepView": {
"additionalProperties": false,
"description": "One command the update would run.",
"properties": {
"description": {
"title": "Description",
"type": "string"
},
"argv": {
"items": {
"type": "string"
},
"title": "Argv",
"type": "array"
}
},
"required": [
"description",
"argv"
],
"title": "StepView",
"type": "object"
}
},
"additionalProperties": false,
"description": "What `self-update --dry-run` would do to the engine's own checkout.",
"properties": {
"checkout": {
"title": "Checkout",
"type": "string"
},
"release": {
"title": "Release",
"type": "boolean"
},
"target": {
"title": "Target",
"type": "string"
},
"up_to_date": {
"title": "Up To Date",
"type": "boolean"
},
"checkout_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Checkout Version"
},
"installed_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Installed Version"
},
"arriving": {
"items": {
"type": "string"
},
"title": "Arriving",
"type": "array"
},
"steps": {
"items": {
"$ref": "#/$defs/StepView"
},
"title": "Steps",
"type": "array"
},
"dry_run": {
"title": "Dry Run",
"type": "boolean"
}
},
"required": [
"checkout",
"release",
"target",
"up_to_date",
"checkout_version",
"installed_version",
"arriving",
"steps",
"dry_run"
],
"title": "SelfUpdateDocument",
"type": "object"
}
services¶
The services the privileged helper may start, stop, enable and disable, with what each is doing now.
Read fresh on every call, unprivileged, by asking the installed helper
(hammunition-devctl services state); the engine adds nothing to it.
| field | type | meaning |
|---|---|---|
version |
integer | the helper contract's services document version; 1 |
services |
list of ServiceView |
every service in the helper's lists, an uninstalled one included (enabled: not-found) |
linger |
LingerView or null |
whether user services outlive the login session; null when the helper did not say |
ServiceView¶
One service the helper may start, stop, enable and disable by name.
| field | type | meaning |
|---|---|---|
name |
string | the name hammunition services start\|stop\|enable\|disable takes |
unit |
string | the systemd unit the name stands for, e.g. gpsd.socket |
scope |
string | user (the operator's own systemd) or system |
description |
string | one line, as the helper's service list words it |
active |
string | active, inactive, failed, activating or unknown: what is running now |
enabled |
string | enabled, disabled, static, not-found or unknown: whether it starts at boot (system) or login (user). not-found means the unit is not installed |
root |
boolean | true when changing it asks for a password (system scope); false when the helper acts for the operator alone |
LingerView¶
Whether the operator's user services keep running after logout.
| field | type | meaning |
|---|---|---|
state |
string | on or off |
ours |
boolean | true when Hammunition turned it on, so it is Hammunition's to turn off |
JSON Schema
{
"$defs": {
"LingerView": {
"additionalProperties": false,
"description": "Whether the operator's user services keep running after logout.",
"properties": {
"state": {
"title": "State",
"type": "string"
},
"ours": {
"title": "Ours",
"type": "boolean"
}
},
"required": [
"state",
"ours"
],
"title": "LingerView",
"type": "object"
},
"ServiceView": {
"additionalProperties": false,
"description": "One service the helper may start, stop, enable and disable by name.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"unit": {
"title": "Unit",
"type": "string"
},
"scope": {
"title": "Scope",
"type": "string"
},
"description": {
"title": "Description",
"type": "string"
},
"active": {
"title": "Active",
"type": "string"
},
"enabled": {
"title": "Enabled",
"type": "string"
},
"root": {
"title": "Root",
"type": "boolean"
}
},
"required": [
"name",
"unit",
"scope",
"description",
"active",
"enabled",
"root"
],
"title": "ServiceView",
"type": "object"
}
},
"additionalProperties": false,
"description": "The services the privileged helper may start, stop, enable and disable,\nwith what each is doing now.\n\nRead fresh on every call, unprivileged, by asking the installed helper\n(`hammunition-devctl services state`); the engine adds nothing to it.",
"properties": {
"version": {
"title": "Version",
"type": "integer"
},
"services": {
"items": {
"$ref": "#/$defs/ServiceView"
},
"title": "Services",
"type": "array"
},
"linger": {
"anyOf": [
{
"$ref": "#/$defs/LingerView"
},
{
"type": "null"
}
]
}
},
"required": [
"version",
"services",
"linger"
],
"title": "ServicesDocument",
"type": "object"
}
station¶
The saved station values, the values themselves included -- map regions among them, per D-057.
For a local front end filling in a form. Not for pasting into an issue, a forum or a chat: a callsign resolves to a name and a licence address, and a grid square or a map region says where the station is.
| field | type | meaning |
|---|---|---|
path |
string | the station file |
file_exists |
boolean | whether that file exists yet |
callsign |
string or null | the callsign; null when not set |
grid_square |
string or null | the Maidenhead locator; null when not set |
node_alias |
string or null | the packet node alias; null when not set |
map_regions |
list of string | Geofabrik region paths carrying offline map data; empty when none are set |
map_freshness |
string or null | how often map data is refreshed: yearly, monthly or latest; null means the yearly default applies |
reference_books |
list of string | Kiwix book ids chosen for kiwix-library (D-066); empty when none are chosen |
mirror |
string or null | the LAN mirror the verified fetch tries before the publisher, the same digest checked either way (D-070); null when none is set |
rig |
string or null | the station's radio: a catalog device id or hamlib: |
rig_device |
string or null | the serial port the rig is reached on — the full by-id path, for the operator's own screen (the plan, doctor and status elide the serial); null when not set |
rig_baud |
integer or null | the CAT serial speed; null when not set or for a PTT-only rig |
rig_ptt_line |
string or null | for a PTT-only rig: rts, dtr or vox; null for a CAT rig or when not set |
rig_owner |
string or null | who holds the port: rigctld (the default when unset) or flrig; null when not set |
dem_source |
string | where QMapShack's elevation is drawn from: copernicus (the default, also when unset) or 3dep, USGS bare earth (D-068, amended 2026-10-01) |
topo_radius_km |
integer | how far from the grid square's centre US Topo sheets, FSTopo sheets and 3DEP tiles are selected, in km: 100 when unset, 0 for none (D-068, amended 2026-10-02) |
topo_regions |
list of string | the map regions the topographic selection is narrowed to, a subset of map_regions; empty when it is not narrowed |
topo_all |
boolean | whether every sheet of every region is selected, as before the bound; false when unset |
active_areas |
list of string or null | the areas drawn and registered (D-082): US state codes and map region names; null when unset, which means everything loaded is active; an empty list means none is |
secrets_doppler_project |
string or null | the Doppler project a keyed download's key is read from when its environment variable is not set (D-081); a name, never a token; null when not set |
secrets_doppler_config |
string or null | the Doppler config within that project (D-081); null when not set |
JSON Schema
{
"additionalProperties": false,
"description": "The saved station values, the values themselves included -- map\nregions among them, per D-057.\n\nFor a local front end filling in a form. Not for pasting into an issue,\na forum or a chat: a callsign resolves to a name and a licence address,\nand a grid square or a map region says where the station is.",
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"file_exists": {
"title": "File Exists",
"type": "boolean"
},
"callsign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Callsign"
},
"grid_square": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Grid Square"
},
"node_alias": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Node Alias"
},
"map_regions": {
"items": {
"type": "string"
},
"title": "Map Regions",
"type": "array"
},
"map_freshness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Map Freshness"
},
"reference_books": {
"items": {
"type": "string"
},
"title": "Reference Books",
"type": "array"
},
"mirror": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mirror"
},
"rig": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rig"
},
"rig_device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rig Device"
},
"rig_baud": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Rig Baud"
},
"rig_ptt_line": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rig Ptt Line"
},
"rig_owner": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rig Owner"
},
"dem_source": {
"title": "Dem Source",
"type": "string"
},
"topo_radius_km": {
"title": "Topo Radius Km",
"type": "integer"
},
"topo_regions": {
"items": {
"type": "string"
},
"title": "Topo Regions",
"type": "array"
},
"topo_all": {
"title": "Topo All",
"type": "boolean"
},
"active_areas": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Active Areas"
},
"secrets_doppler_project": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secrets Doppler Project"
},
"secrets_doppler_config": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secrets Doppler Config"
}
},
"required": [
"path",
"file_exists",
"callsign",
"grid_square",
"node_alias",
"map_regions",
"map_freshness",
"reference_books",
"mirror",
"rig",
"rig_device",
"rig_baud",
"rig_ptt_line",
"rig_owner",
"dem_source",
"topo_radius_km",
"topo_regions",
"topo_all",
"active_areas",
"secrets_doppler_project",
"secrets_doppler_config"
],
"title": "StationDocument",
"type": "object"
}
station-set¶
What station set saved, left as-is, or refused for a local front end.
This contains station values and is for local programs, not for pasting into an issue, forum or chat.
| field | type | meaning |
|---|---|---|
saved |
object | station keys written and their new values |
unchanged |
object | given station keys already equal to their stored values |
refused |
list of StationSetRefusal |
given flags the CLI refused |
file |
string | the station configuration file path |
StationSetRefusal¶
One station-set flag the CLI refused, including its original value.
| field | type | meaning |
|---|---|---|
key |
string | the station setting named by the flag |
value |
string or integer or boolean or null | the value given to the flag |
reason |
string | the CLI's reason for refusing this flag |
JSON Schema
{
"$defs": {
"StationSetRefusal": {
"additionalProperties": false,
"description": "One station-set flag the CLI refused, including its original value.",
"properties": {
"key": {
"title": "Key",
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Value"
},
"reason": {
"title": "Reason",
"type": "string"
}
},
"required": [
"key",
"value",
"reason"
],
"title": "StationSetRefusal",
"type": "object"
}
},
"additionalProperties": false,
"description": "What station set saved, left as-is, or refused for a local front end.\n\nThis contains station values and is for local programs, not for pasting\ninto an issue, forum or chat.",
"properties": {
"saved": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "boolean"
},
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
]
},
"title": "Saved",
"type": "object"
},
"unchanged": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "boolean"
},
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
]
},
"title": "Unchanged",
"type": "object"
},
"refused": {
"items": {
"$ref": "#/$defs/StationSetRefusal"
},
"title": "Refused",
"type": "array"
},
"file": {
"title": "File",
"type": "string"
}
},
"required": [
"saved",
"unchanged",
"refused",
"file"
],
"title": "StationSetDocument",
"type": "object"
}
status¶
What this machine is, what the catalog holds, and what has been done here.
| field | type | meaning |
|---|---|---|
target |
TargetView |
the system |
catalog |
CatalogSummary |
the catalog read |
log_path |
string | the transaction log file |
log_entries |
integer | events in the log |
latest |
LatestTransaction or null |
the most recent transaction; null when the log records none |
recorded_units |
list of RecordedUnit |
every unit an install or uninstall here named, first-seen order |
CatalogSummary¶
The catalog this run read.
| field | type | meaning |
|---|---|---|
path |
string | the catalog directory |
packages |
integer | manifests loaded |
resolvable |
integer | of those, the ones with an install block for this target |
profiles |
integer | profiles loaded |
LatestTransaction¶
The most recent transaction_begin in the log, and how it ended.
| field | type | meaning |
|---|---|---|
when |
string or null | its timestamp, ISO 8601, when recorded |
outcome |
string | completed, failed, or interrupted (no ending recorded: killed, or still running) |
completed_commands |
integer or null | commands that ran; null when interrupted |
intended |
list of string | the apt packages it set out to install |
verified |
boolean or null | the D-031 effect check's verdict; null when the log predates it or the run did not end |
checks |
integer | effect checks recorded |
unconfirmed |
list of CheckLine |
the checks that failed |
deferred |
list of LoggedDeferral |
what it deferred |
CheckLine¶
An effect the transaction could not confirm afterwards (D-031).
| field | type | meaning |
|---|---|---|
subject |
string | what was checked |
detail |
string | what was found instead |
LoggedDeferral¶
Something that transaction deferred by design (D-035, D-039).
| field | type | meaning |
|---|---|---|
kind |
string | config or package |
subject |
string | what was deferred |
what |
string | what did not happen |
why |
string | what was missing |
RecordedUnit¶
A unit some install or uninstall here named, and how the latest one ended.
Not a claim that the unit is installed now: update --json compares the
machine. A unit the catalog no longer carries has null method and pin.
| field | type | meaning |
|---|---|---|
name |
string | the catalog unit |
last_named |
string or null | when the latest install or uninstall naming it began |
last_outcome |
string | an install's completed, failed or interrupted; an uninstall's removed, removal failed or removal interrupted |
completed_in_failed_run |
string or null | when the install that completed this unit began, if that install then failed or was killed after the unit's last step (unit_end); null otherwise |
catalog_version |
string or null | the manifest's version today |
method |
string or null | the install method that resolves on this target |
pin |
string or null | the catalog's pin for a built unit; null for apt |
JSON Schema
{
"$defs": {
"CatalogSummary": {
"additionalProperties": false,
"description": "The catalog this run read.",
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"packages": {
"title": "Packages",
"type": "integer"
},
"resolvable": {
"title": "Resolvable",
"type": "integer"
},
"profiles": {
"title": "Profiles",
"type": "integer"
}
},
"required": [
"path",
"packages",
"resolvable",
"profiles"
],
"title": "CatalogSummary",
"type": "object"
},
"CheckLine": {
"additionalProperties": false,
"description": "An effect the transaction could not confirm afterwards (D-031).",
"properties": {
"subject": {
"title": "Subject",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"subject",
"detail"
],
"title": "CheckLine",
"type": "object"
},
"LatestTransaction": {
"additionalProperties": false,
"description": "The most recent `transaction_begin` in the log, and how it ended.",
"properties": {
"when": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "When"
},
"outcome": {
"title": "Outcome",
"type": "string"
},
"completed_commands": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Completed Commands"
},
"intended": {
"items": {
"type": "string"
},
"title": "Intended",
"type": "array"
},
"verified": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Verified"
},
"checks": {
"title": "Checks",
"type": "integer"
},
"unconfirmed": {
"items": {
"$ref": "#/$defs/CheckLine"
},
"title": "Unconfirmed",
"type": "array"
},
"deferred": {
"items": {
"$ref": "#/$defs/LoggedDeferral"
},
"title": "Deferred",
"type": "array"
}
},
"required": [
"when",
"outcome",
"completed_commands",
"intended",
"verified",
"checks",
"unconfirmed",
"deferred"
],
"title": "LatestTransaction",
"type": "object"
},
"LoggedDeferral": {
"additionalProperties": false,
"description": "Something that transaction deferred by design (D-035, D-039).",
"properties": {
"kind": {
"title": "Kind",
"type": "string"
},
"subject": {
"title": "Subject",
"type": "string"
},
"what": {
"title": "What",
"type": "string"
},
"why": {
"title": "Why",
"type": "string"
}
},
"required": [
"kind",
"subject",
"what",
"why"
],
"title": "LoggedDeferral",
"type": "object"
},
"RecordedUnit": {
"additionalProperties": false,
"description": "A unit some install or uninstall here named, and how the latest one ended.\n\nNot a claim that the unit is installed now: `update --json` compares the\nmachine. A unit the catalog no longer carries has null method and pin.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"last_named": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Named"
},
"last_outcome": {
"title": "Last Outcome",
"type": "string"
},
"completed_in_failed_run": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed In Failed Run"
},
"catalog_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Catalog Version"
},
"method": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Method"
},
"pin": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pin"
}
},
"required": [
"name",
"last_named",
"last_outcome",
"completed_in_failed_run",
"catalog_version",
"method",
"pin"
],
"title": "RecordedUnit",
"type": "object"
},
"TargetView": {
"additionalProperties": false,
"description": "What `/etc/os-release` said, verbatim, with the one line the text prints.",
"properties": {
"distro": {
"title": "Distro",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"arch": {
"title": "Arch",
"type": "string"
},
"id_like": {
"items": {
"type": "string"
},
"title": "Id Like",
"type": "array"
},
"pretty_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pretty Name"
},
"description": {
"title": "Description",
"type": "string"
},
"debian_family": {
"title": "Debian Family",
"type": "boolean"
}
},
"required": [
"distro",
"version",
"arch",
"id_like",
"pretty_name",
"description",
"debian_family"
],
"title": "TargetView",
"type": "object"
}
},
"additionalProperties": false,
"description": "What this machine is, what the catalog holds, and what has been done here.",
"properties": {
"target": {
"$ref": "#/$defs/TargetView"
},
"catalog": {
"$ref": "#/$defs/CatalogSummary"
},
"log_path": {
"title": "Log Path",
"type": "string"
},
"log_entries": {
"title": "Log Entries",
"type": "integer"
},
"latest": {
"anyOf": [
{
"$ref": "#/$defs/LatestTransaction"
},
{
"type": "null"
}
]
},
"recorded_units": {
"items": {
"$ref": "#/$defs/RecordedUnit"
},
"title": "Recorded Units",
"type": "array"
}
},
"required": [
"target",
"catalog",
"log_path",
"log_entries",
"latest",
"recorded_units"
],
"title": "StatusDocument",
"type": "object"
}
transactions¶
The transaction history, oldest first, across archives and the live log.
| field | type | meaning |
|---|---|---|
transactions |
list of TransactionEntry |
transaction rows in chronological order, oldest first |
TransactionEntry¶
One install or uninstall recorded in the transaction log.
| field | type | meaning |
|---|---|---|
id |
integer | its one-based position in chronological transaction history |
began |
string | the begin event's ISO 8601 timestamp |
ended |
string or null | the matching end event's timestamp, or null without one |
command |
string | the command that began the transaction, such as install |
units |
list of string | unit names recorded by the begin event |
deferred |
list of string | unit names deferred by the begin event (D-039) |
result |
string | ok, failed, aborted or in-progress |
log |
string or null | the D-077 run-log path recorded at transaction start, or null |
JSON Schema
{
"$defs": {
"TransactionEntry": {
"additionalProperties": false,
"description": "One install or uninstall recorded in the transaction log.",
"properties": {
"id": {
"title": "Id",
"type": "integer"
},
"began": {
"title": "Began",
"type": "string"
},
"ended": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ended"
},
"command": {
"title": "Command",
"type": "string"
},
"units": {
"items": {
"type": "string"
},
"title": "Units",
"type": "array"
},
"deferred": {
"items": {
"type": "string"
},
"title": "Deferred",
"type": "array"
},
"result": {
"title": "Result",
"type": "string"
},
"log": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Log"
}
},
"required": [
"id",
"began",
"ended",
"command",
"units",
"deferred",
"result",
"log"
],
"title": "TransactionEntry",
"type": "object"
}
},
"additionalProperties": false,
"description": "The transaction history, oldest first, across archives and the live log.",
"properties": {
"transactions": {
"items": {
"$ref": "#/$defs/TransactionEntry"
},
"title": "Transactions",
"type": "array"
}
},
"required": [
"transactions"
],
"title": "TransactionsDocument",
"type": "object"
}
unit¶
One unit's manifest. JSON only: the text show describes profiles.
| field | type | meaning |
|---|---|---|
name |
string | the unit |
resolves_here |
string or null | the method that resolves on this target |
manifest |
object | the manifest as its YAML sets it, unset fields left out; every field is documented in docs/reference/schema.md |
JSON Schema
{
"additionalProperties": false,
"description": "One unit's manifest. JSON only: the text `show` describes profiles.",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"resolves_here": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Resolves Here"
},
"manifest": {
"additionalProperties": true,
"title": "Manifest",
"type": "object"
}
},
"required": [
"name",
"resolves_here",
"manifest"
],
"title": "UnitDocument",
"type": "object"
}
update¶
Installed versus the catalog, as a report. Nothing runs (D-053).
| field | type | meaning |
|---|---|---|
target |
TargetView |
the system |
from_log |
boolean | the units compared are every unit the transaction log names |
rows |
list of UpdateRowView |
one per unit compared |
counts |
UpdateCounts |
rows per state |
lists_note |
string | how old the local apt lists are; the report compares against them |
upgrade_command |
string or null | takes apt's differing candidates; null when none |
rebuild_command |
string or null | rebuilds every unit behind the pin; null when none |
upstream_declared |
list of string | units whose probe would ask upstream |
upstream |
list of UpstreamRowView or null |
the upstream comparison; null unless --upstream asked for it |
UpdateRowView¶
One unit: installed versus the catalog.
| field | type | meaning |
|---|---|---|
unit |
string | the catalog unit |
state |
string | up to date, candidate differs, behind the pin, not installed, unknown, re-checked on install, manual or retired |
detail |
string | what was compared, as the text prints it |
strategy |
string | the manifest's update strategy |
upgradable |
list of string | apt packages whose candidate differs |
UpdateCounts¶
How many rows are in each state.
| field | type | meaning |
|---|---|---|
up_to_date |
integer | up to date |
candidate_differs |
integer | apt would change them on its next upgrade |
behind_pin |
integer | built at an earlier pin, or never verified here |
not_installed |
integer | not on this machine |
unknown |
integer | nothing on disk can be checked |
on_install |
integer | resolved again on every install |
manual |
integer | re-pinned by hand |
retired |
integer | catalog units retained as retired |
UpstreamRowView¶
The catalog's pin against what upstream publishes (--upstream only).
| field | type | meaning |
|---|---|---|
unit |
string | the catalog unit |
method |
string | the probe used |
catalog |
string | the catalog's pin |
upstream |
string or null | what upstream publishes; null when it could not be read |
state |
string | the verdict |
detail |
string | what was found |
JSON Schema
{
"$defs": {
"TargetView": {
"additionalProperties": false,
"description": "What `/etc/os-release` said, verbatim, with the one line the text prints.",
"properties": {
"distro": {
"title": "Distro",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"arch": {
"title": "Arch",
"type": "string"
},
"id_like": {
"items": {
"type": "string"
},
"title": "Id Like",
"type": "array"
},
"pretty_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pretty Name"
},
"description": {
"title": "Description",
"type": "string"
},
"debian_family": {
"title": "Debian Family",
"type": "boolean"
}
},
"required": [
"distro",
"version",
"arch",
"id_like",
"pretty_name",
"description",
"debian_family"
],
"title": "TargetView",
"type": "object"
},
"UpdateCounts": {
"additionalProperties": false,
"description": "How many rows are in each state.",
"properties": {
"up_to_date": {
"title": "Up To Date",
"type": "integer"
},
"candidate_differs": {
"title": "Candidate Differs",
"type": "integer"
},
"behind_pin": {
"title": "Behind Pin",
"type": "integer"
},
"not_installed": {
"title": "Not Installed",
"type": "integer"
},
"unknown": {
"title": "Unknown",
"type": "integer"
},
"on_install": {
"title": "On Install",
"type": "integer"
},
"manual": {
"title": "Manual",
"type": "integer"
},
"retired": {
"title": "Retired",
"type": "integer"
}
},
"required": [
"up_to_date",
"candidate_differs",
"behind_pin",
"not_installed",
"unknown",
"on_install",
"manual",
"retired"
],
"title": "UpdateCounts",
"type": "object"
},
"UpdateRowView": {
"additionalProperties": false,
"description": "One unit: installed versus the catalog.",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"state": {
"title": "State",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"strategy": {
"title": "Strategy",
"type": "string"
},
"upgradable": {
"items": {
"type": "string"
},
"title": "Upgradable",
"type": "array"
}
},
"required": [
"unit",
"state",
"detail",
"strategy",
"upgradable"
],
"title": "UpdateRowView",
"type": "object"
},
"UpstreamRowView": {
"additionalProperties": false,
"description": "The catalog's pin against what upstream publishes (`--upstream` only).",
"properties": {
"unit": {
"title": "Unit",
"type": "string"
},
"method": {
"title": "Method",
"type": "string"
},
"catalog": {
"title": "Catalog",
"type": "string"
},
"upstream": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Upstream"
},
"state": {
"title": "State",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
}
},
"required": [
"unit",
"method",
"catalog",
"upstream",
"state",
"detail"
],
"title": "UpstreamRowView",
"type": "object"
}
},
"additionalProperties": false,
"description": "Installed versus the catalog, as a report. Nothing runs (D-053).",
"properties": {
"target": {
"$ref": "#/$defs/TargetView"
},
"from_log": {
"title": "From Log",
"type": "boolean"
},
"rows": {
"items": {
"$ref": "#/$defs/UpdateRowView"
},
"title": "Rows",
"type": "array"
},
"counts": {
"$ref": "#/$defs/UpdateCounts"
},
"lists_note": {
"title": "Lists Note",
"type": "string"
},
"upgrade_command": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Upgrade Command"
},
"rebuild_command": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rebuild Command"
},
"upstream_declared": {
"items": {
"type": "string"
},
"title": "Upstream Declared",
"type": "array"
},
"upstream": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/UpstreamRowView"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Upstream"
}
},
"required": [
"target",
"from_log",
"rows",
"counts",
"lists_note",
"upgrade_command",
"rebuild_command",
"upstream_declared",
"upstream"
],
"title": "UpdateDocument",
"type": "object"
}