Canonical app.yaml metadata schema (census-driven) (2026-07-17)

Status: DESIGN. Part of the platform-compat program — faithful capture of docs/handoff/2026-07-16-hel1-reprovision-and-platform-compat.md (§C, §D, §E), no new design. A native SHC add (powers a future catalog UI), not compat-only. Siblings: 2026-07-17-origin-ingest-gate.md (the adapt stage targets these fields), 2026-07-17-manifest-adapters.md (the adapters that do the remapping), 2026-07-17-notes-templating.md (the notes field’s own design), 2026-07-17-origin-repos-and-migrations.md (catalog registration + migration).

app.yaml today carries name, version, description, category, icon, homepage, tags. Foreign origins carry much richer store metadata — Umbrel’s tagline/developer/gallery/releaseNotes, Cloudron’s mediaLinks/changelog, CasaOS’s x-casaos fields — and a catalog UI (native OR adapted) wants that information.

The earlier draft resolved this by adopting Umbrel’s exact field names into app.yaml verbatim (“share their vocab”, so ingest is a verbatim copy). The evaluation reversed that as schema pollution: the adapter’s job IS renaming. Keep SHC vocabulary in the core; give everything foreign that has no canonical home a compat: passthrough bag.

Census-driven (field census across the origins, 2026-07-16). One merit-chosen name per concept, NO aliases; adapters remap; snake_case per the existing SHC yaml convention.

Existing fields keep: name, version, description, category, icon, homepage, tags.

New canonical fields — the full remap table (the adapter does the renaming):

SHC canonical	Concept	Remaps from (adapter does the renaming)
tagline	one-line store copy	umbrel/casaos/cloudron tagline, tipi short_desc, coolify slogan
developer	upstream software developer/org	umbrel developer, casaos/tipi/cloudron author
maintainer	package maintainer (Debian term; name/url)	umbrel submitter+submission, cloudron packagerName+packagerUrl
source	upstream source-repo URL (NOT repo — that’s the catalog-repo term in shc_deployment)	umbrel/casaos repo, tipi source
support	support / issues URL	umbrel/casaos support, cloudron forumUrl
docs	documentation URL	casaos docs, cloudron documentationUrl, caprover documentation
gallery	screenshot URLs	umbrel gallery, casaos screenshot_link, cloudron mediaLinks
changelog	release notes shown on update (the established dev term)	umbrel releaseNotes, casaos release_notes, cloudron changelog
notes	TEMPLATED post-deploy message (Helm NOTES.txt style; renders minted secrets sensitively — 2026-07-17-notes-templating.md)	cloudron postInstallMessage, caprover instructions.end, umbrel defaultUsername/defaultPassword display
deprecated	catalog-lifecycle bool	tipi deprecated, umbrel disabled
architectures	supported arch list	casaos architectures, tipi supported_architectures
min_shc_version	platform floor for the package	umbrel manifestVersion, cloudron minBoxVersion, tipi min_tipi_version
compat:	opaque passthrough bag — everything foreign with no canonical home (umbrel widgets/permissions/torOnly, cloudron checklist/capabilities, …)	all platforms

An opaque passthrough: foreign metadata with no canonical home rides along unmodified (umbrel widgets/permissions/torOnly, cloudron checklist/capabilities, …). Foreign catalog metadata registered as an origin repo rides this bag too (2026-07-17-origin-repos-and-migrations.md). Nothing in the enrichment core reads it.

• Umbrel’s implements (drop-in provider contract — an app declaring it satisfies another’s dependency interface) is conceptually adjacent to SHC’s integration providers and worth a future look.
• Umbrel’s backupIgnore maps to backup.yaml excludes (not app.yaml).
• Umbrel’s deterministicPassword tells the adapter whether APP_PASSWORD is actually consumed (drives the notes-vs-literal fork — 2026-07-17-notes-templating.md).
• Cloudron’s checklist is a second post-install surface (tickable todos) — deferred.
• User-config schemas (tipi form_fields w/ regex validation, caprover variables w/ validRegex, portainer env.select) all lower into the existing typed vars DSL (@string/@secret/@boolean/@port…) — they are install-time config, not metadata, so they do NOT get canonical metadata fields.

• SHC vocabulary in the core; no aliases; adapters remap. (Reverses the earlier “share their vocab” decision — that was schema pollution.)
• compat: opaque passthrough bag for everything without a canonical home.
• snake_case, per the existing SHC yaml convention.
• source, not repo, for the upstream source URL (repo is the catalog-repo term in shc_deployment).
• maintainer uses the Debian term (package maintainer, distinct from developer).
• notes is templated, not static text (2026-07-17-notes-templating.md).
• backupIgnore-class fields land in backup.yaml excludes, not here.
• Native add: the schema serves first-party packages and the future catalog UI, not just adapted apps.

• Umbrel’s implements — whether/when it gets a canonical home next to SHC’s integration providers (future look, not v1).
• CasaOS post-install “tips” field name needs census verification.
• Cloudron checklist — deferred (rides compat: until then).