TAPPaaS configuration schemas
This directory holds the JSON-Schema (draft 2020-12) field definitions for every typed configuration object in TAPPaaS. Each type has:
- a schema here in
schemas/(the field definitions + validation rules), - a live location under
~/config/on thetappaas-cicdmothership (the deployed instances), and - an owning manager that performs all create/read/update/delete through verbs.
Admins drive verbs, not JSON (ADR-007). You never hand-edit these files — the owning manager writes validated config and a
reconcilepushes it to the live system. Hand-editing remains possible but is only valid when followed by the manager'sreconcile. Every write is schema- + reference-validated first.
configuration.json (the old monolith) is retired — it was split into
site.json + per-environment files + per-module config (this is why there is no
configuration.md anymore).
The configuration objects
| Object | Schema (schemas/) |
Live location (~/config/) |
Owning manager — CRUD verbs |
|---|---|---|---|
| Site (singleton) | site-fields.json |
site.json |
site-manager — site show/modify; location list/show/add/modify/delete; node list/add/delete; repository list/add/delete/reconcile; validate; reconcile [--deep] |
| Environment | environment-fields.json |
environments/<env>.json |
environment-manager — add/modify/delete/list/show/validate; reconcile [--deep] (env + its zone via network; --deep → consuming modules). --dns-mode per-service|wildcard |
| Organization | organization-fields.json |
identities/organizations/<name>.json |
identity-manager — org add/modify/delete/list/show |
| Group | group-fields.json |
people/groups/<name>.json |
identity-manager — group add/modify/delete/list/show |
| Role | role-fields.json |
people/roles/<name>.json |
identity-manager — role add/modify/delete/list/show |
| User | user-fields.json |
people/users/<name>.json |
identity-manager — user add/modify/delete/list/show. People-wide: reconcile (push → Authentik; alias sync), validate |
| Module (deployed) | module-fields.json |
<module>.json |
module-manager — module add/modify/delete/list/show/validate/reconcile/test/snapshot-vm. add=deploy, modify=redeploy, reconcile=re-apply current config (leaf) |
| Module catalog | module-catalog-fields.json |
src/module-catalog.json (in each repo) |
site-manager — repository add/delete/list/reconcile (registers/clones the repo that ships the catalog), and repository validate-catalog [<name>] [--strict], which is what actually checks a catalog against this schema and against the repository (#463: a moduleJson that exists, stack/vmid agreeing with the module, one name and one VMID each, no module left unlisted). Reports; only --strict is fatal |
| Zones | zones-fields.json |
zones.json |
network-manager — add/delete/list/show/exists (the zone keyword is an optional legacy prefix); validate (alias zones-check); init/merge/distribute (aliases zones-init/zones-merge/zones-distribute); reconcile [--apply] [--only <plane>]. (No free-form modify — state + access-to are governed by the lifecycle + init/merge.) |
| Shares | shares-fields.json |
shares.json |
storage-manager — nfs show; nfs share add/modify/delete/purge; nfs grant/revoke; nfs converge; validate (ADR-029 v0.9) |
| Positions | positions-fields.json |
positions.json |
asset-manager — room …, rack list/show/add/modify/delete; asset list/show/add/record/modify/remove/receive/fault/repaired/dispose/allocate/release (device … their old names); port add/modify/remove; place, place list/show/modify, unplace; cable list/add/remove/split/join; faceplates list/show; validate. The site's physical assets and where they are: rooms in the site's locations, racks, placements, every box as an asset with its ports (ADR-040 D9), stage and role (D7; interim, until the CMDB); the device records of other managers are not touched |
Module console files (console-fields.json)
Like service-fields.json, console-fields.json describes a file in a module's SOURCE tree, not a
~/config/ object: <module>/console.json, the sections and operations the module adds to its
page in the console. The console checks it when it reads a page and shows a bad entry as an error in
its place. The console's README describes what each key does.
Service field manifests (service-fields.json)
service-fields.json is the odd one out: it does not describe a ~/config/
object at all. It is the schema for services/<service>/fields.json — the
per-provider manifest ADR-020 introduces, which lives in a module's SOURCE tree
next to the scripts that perform the change.
The two module schemas answer different questions and neither duplicates the other:
| Question | Answered by |
|---|---|
What fields exist, what do they mean, what is the default, and which service uses each one (usedBy)? |
module-fields.json |
| For that (field, service) pair — what does changing it cost after install, and how is the change applied? | services/<service>/fields.json |
The change class is keyed by the pair, not the field, which is why the
manifest sits with the service rather than in the field schema. module-manager
validate lints it: a service that ships a fields.json must classify every
field module-fields.json says it owns, using the classes the schema defines. A
service with no fields.json has not been migrated to the contract yet and is
skipped.
The operator-facing surface it unlocks is documented in the module-manager
README: modify <module> --set field=value, which refuses an immutable or
recreate field before it writes anything and rejects a mixed --set whole; and
the two — only two — ways to authorize a change that needs downtime, modify
--force (an operator, now) and the per-module rebootOk (a standing permission
honoured in the scheduled sweep and in site-manager update --allow-disruption).
--force is neither: it proceeds past a refusal and never reboots.
Objects without a schema in this directory
| Object | Live location | Owner / how it's written |
|---|---|---|
| Switch / AP topology | switch-configuration-{actual,desired}.json |
schema is network/switch-configuration-schema.json; switch-manager / ap-manager (add-controller/add-switch/add-port/interrogate/reconcile), driven by network-manager reconcile --only switch|ap. |
| TLS cert refids | cert-refids.json |
runtime state (no schema) — written by acme-setup.sh, keyed by environment name. An environment's domains.dnsMode (environment-manager --dns-mode) selects whether a wildcard cert refid is stored here. |
| Backup policy | not a file — the .backup block on site.json / environments/<env>.json / <module>.json (cascade: module > env > site) |
backup-manager — modify <module> writes the module .backup layer; site/env layers via site/environment modify. list/show/validate/reconcile (resolve cascade → PBS via pbs-controller); restore. |
Sizes: small, medium, large
site.json and each environments/<env>.json say how big they are expected to be, in size:
| Size | Meant for |
|---|---|
small |
A few users. One node, or up to three small ones. A test or lab system. |
medium |
The default. Up to about 50 concurrent users, many modules in one or two environments. |
large |
100+ users. Three or more large nodes, possibly many environments. |
An environment without a size takes the site's; a site without one is medium. A module's
cluster:vm / cluster:lxc block states cores, memory and diskSize for medium and may add
coresSmallLarge, memorySmallLarge and diskSmallLarge, each [small, large]: at install a small site or
environment takes the small value, a large one the large value (module-manager, "How big a guest is"). A disk's
minimum is never below the template the guest is cloned from, because a disk cannot shrink.
Conventions
validate— every config manager exposes avalidateverb (the schema + reference-integrity gate). Writes are validated before they land.reconcile— pushes config → live. Shallow by default;--deepcascades into dependents (site → people + network + environments → modules);--applycommits (default is preview). Reconcile is idempotent.Managers vs controllers — managers own configuration (these objects) and the verb front door; controllers (opnsense / proxmox / switch / ap / backup / identity) execute against live infrastructure and are driven by their manager.
referenceson a field definition (zones,environments,nodes,storage,organizations,users,groups,roles) — the value names a defined object of that kind; for an array, each item does.zone0,proxyAllowedZonesand a zone'saccess-toreference zones,nodeandHANodenodes,storagea pool of the module's node, an environment'sownerOrgan organization, a user'smemberOfgroups. It is declared in the module field definitions and in the JSON-Schema documents alike, so the console offers the defined objects to choose from and a validator can check the name against the same list. Seedocs/design/ADR-007-verb-alignment.mdfor the full verb/CRUD model and the reconcile cascade.
Attribution: contributor, author, maintainer
Three roles, one home each — nothing duplicated (see ADR-015 — Community Governance and Contribution Files for the repo/org-level contribution model):
| Role | Definition | Recorded in |
|---|---|---|
| Contributor | Anyone with an accepted change (the broadest set) | git history — never listed in files |
| Author | The copyright-bearing subset | optional per-module AUTHORS.md — additive lines of <year> @<handle> — <role> (template: src/misc/00-Template/AUTHORS.md) |
| Maintainer | The current responsible party (moves on handover) | maintainer in <module>.json — the one machine-readable governance field, kept there so issues can be reported/routed automatically |
Authorship does not go into <module>.json — it is not needed to run the
module. AUTHORS.md is optional. Per-file headers (.nix # Author: lines) are
not authoritative and may be dropped when touched; the module-level AUTHORS.md
covers every artifact in the module (DRY).
AI assistance: an AI tool is at most a contributor — AI-generated output
carries no copyright, so an AI is never an author (it never appears in
AUTHORS.md) and never holds maintainer. Per ADR-015 and Codeberg
etiquette, a contribution is attributed to the human contributor: do not
add an AI Co-Authored-By: trailer to commits or pull requests.