TenantAtlas/specs/097-settings-foundation/data-model.md

Data Model — Settings Foundation (Workspace + Optional Tenant Override) (097)

Entities

SettingDefinition (code-defined)

Represents a known (domain, key) setting with validation, normalization, and a system default.

• Fields (conceptual):
  • domain (string)
  • key (string)
  • type (enum-like: int|string|bool|json)
  • system_default (mixed)
  • rules (validation rules; code-level)
  • normalize(value) -> value (optional)

WorkspaceSetting (DB: workspace-owned)

A workspace-wide override for a setting.

• Table: workspace_settings
• Fields:
  • id
  • workspace_id (FK → workspaces.id, NOT NULL)
  • domain (string, NOT NULL)
  • key (string, NOT NULL)
  • value (JSON/JSONB, NOT NULL)
  • updated_by_user_id (FK → users.id, nullable)
  • timestamps
• Indexes / constraints:
  • UNIQUE (workspace_id, domain, key)
  • Index (workspace_id, domain)

TenantSetting (DB: tenant-owned; backend-ready)

A tenant-specific override for a setting.

• Table: tenant_settings
• Fields:
  • id
  • workspace_id (FK → workspaces.id, NOT NULL)
  • tenant_id (FK → tenants.id, NOT NULL)
  • domain (string, NOT NULL)
  • key (string, NOT NULL)
  • value (JSON/JSONB, NOT NULL)
  • updated_by_user_id (FK → users.id, nullable)
  • timestamps
• Indexes / constraints:
  • UNIQUE (tenant_id, domain, key)
  • Index (workspace_id, tenant_id)

Relationships

• Workspace has many WorkspaceSettings.
• Workspace has many TenantSettings.
• Tenant has many TenantSettings.

Invariants / Rules enforced by this feature

• Resolution precedence is deterministic:
  • tenant override → workspace override → system default.
• Workspace isolation:
  • all reads/writes must be scoped to the active workspace context.
  • tenant overrides must be rejected if the tenant does not belong to the workspace.
• Unknown keys are rejected:
  • writes must only be allowed for keys in the SettingsRegistry.
• Validation is centralized:
  • values are validated against the SettingDefinition before persistence.
• Reset semantics:
  • reset removes the persisted override row (workspace or tenant) so resolution falls back.

Pilot Setting (v1)

• Domain: backup
• Key: retention_keep_last_default
• Type: int
• System default: 30
• Validation:
  • integer
  • minimum 1 (defensive)