1 ADR 0042 domain display terms
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0042: Per-Domain Household Display Terms

Status: proposed Date: 2026-06-03

Context

ADR 0020 introduced generic discovery domains with class-occurrence and class-instance lanes. Each domain carries displayMetadata (JSONB) and allowedClasses (JSONB array with classKey and displayName). However, the UI currently hardcodes household-facing terminology regardless of domain:

  • "identity" for class instances (People, future pets, vehicles)
  • "candidate" for suggestions
  • "evidence" for photos linked to suggestions
  • "person" / "thing" as generic labels

A full UI jargon audit (Spec 007 follow-up, ~146 findings) revealed that hardcoded terms like "identity", "candidate", "evidence", "owner-private", and "worker" appear throughout the household-facing UI. Many of these terms are appropriate for one domain but confusing or wrong for another:

  • "identity" makes sense for People but not for plants ("Plant identity" is confusing)
  • "evidence" sounds legal/forensic for family photo management
  • "candidate" is developer language
  • "owner-private" is internal governance terminology

The root cause is that the domain model carries no per-domain vocabulary. The UI has no way to ask "what do you call the things this domain recognizes?" and instead uses hardcoded English terms that work "well enough" for People but not for future domains.

This also means the three humanize() implementations in the UI (Review page, Instances page, Admin page) all do naive underscore-to-space conversion with no domain awareness.

Current domain metadata example

{
  "domainKey": "people",
  "displayName": "People",
  "allowedClasses": [{"classKey": "person", "displayName": "Person"}],
  "displayMetadata": {"displayName": "People", "uiPlacement": "media_detail"}
}

displayName on the domain is the section/page title. allowedClasses[].displayName is a class label. Neither provides plural forms, instance labels, unnamed-instance patterns, or UI copy templates.

Decision

Extend displayMetadata with a structured householdTerms object that each domain defines. The UI reads these terms instead of hardcoding vocabulary.

Schema

{
  "displayName": "People",
  "uiPlacement": "media_detail",
  "householdTerms": {
    "classSingular": "Person",
    "classPlural": "People",
    "unnamedClassInstance": "Unbekannte Person",
    "suggestionNoun": "suggestion",
    "suggestionVerb": "suggested",
    "photoNoun": "photo",
    "acceptVerb": "Accept",
    "rejectVerb": "Dismiss",
    "mergeVerb": "Merge into another",
    "moveVerb": "Move selected photos"
  }
}
Field Purpose Example (People) Example (Plants)
classSingular Singular label for a recognized class "Person" "Pflanze"
classPlural Plural label for a recognized class "People" "Pflanzen"
unnamedClassInstance How to refer to an unnamed instance "Unbekannte Person" "Unbekannte Pflanze"
suggestionNoun What to call a pending suggestion "suggestion" "suggestion"
suggestionVerb Verb for the suggestion action "suggested" "suggested"
photoNoun What to call linked media "photo" "photo"
acceptVerb Label for the accept action "Accept" "Accept"
rejectVerb Label for the reject action "Dismiss" "Dismiss"
mergeVerb Label for the merge action prefix "Merge into another" "Merge into another"
moveVerb Label for the move/split action "Move selected photos" "Move selected photos"

Rules

  1. Optional but authoritative: If householdTerms is present on a domain, the UI MUST use those terms for that domain's surfaces. If absent, the UI falls back to current hardcoded defaults.
  2. Manifest-defined: householdTerms lives in displayMetadata on the domain and its active manifest. The manifest producer defines the terms; Core stores and serves them.
  3. Core does not validate term content: Core validates manifest structure and domain registration, but does not validate the semantic correctness of household terms. The domain producer is responsible.
  4. Generic surfaces stay generic: Navigation labels ("People & things"), page titles, and cross-domain headings remain in the generic layer. Domain-specific terms apply within domain-specific surfaces (Review, Instances, Media Detail discovery sections).
  5. No i18n in v1: Terms are defined per-domain in the manifest, not per-locale. A single set of terms per domain is sufficient for v1. Localization is a future concern.
  6. Backward compatible: Existing domains without householdTerms continue to work with current hardcoded fallbacks. Adding householdTerms is an additive, non-breaking change.

Scope of change

This ADR defines the data model extension. The UI migration to consume householdTerms is a separate implementation step:

  • Phase 1 (this ADR): Add householdTerms to the domain manifest schema and seed it for existing domains (People, Plants).
  • Phase 2 (future spec): Update UI components (Review, Instances, Media Detail, PeopleBrowser, Admin) to read householdTerms from the domain and use them instead of hardcoded strings.
  • Phase 3 (future spec): Audit and fix remaining ~146 jargon findings from the Spec 007 follow-up audit, using domain-specific terms where applicable and household-friendly defaults elsewhere.

Consequences

  • Domains gain self-describing UI vocabulary — new domains (pets, vehicles, OCR) can define their own terminology without UI code changes.
  • The displayMetadata JSONB field gains a structured sub-object, but remains backward-compatible (existing consumers ignore unknown keys).
  • The UI migration is a significant but mechanical change: replace hardcoded strings with term lookups from the domain context.
  • ADR 0020 Rule 5 ("No per-domain Core services") is preserved — this is data, not behavior. Core serves the terms; the UI consumes them.