Terminology¶

A glossary of terms used throughout the django-tenant-options documentation.

Tenant¶

An entity (organization, team, company, department) that uses your multi-tenant application. Each tenant has its own set of options and selections. django-tenant-options has no requirement for a particular tenant architecture – the only requirement is that your project has a model representing tenants.

Option¶

A configurable choice that can appear in user-facing forms. Options are stored as model instances inheriting from AbstractOption.

Option Model¶

A concrete Django model that inherits from AbstractOption. Stores all available options for a particular category (e.g., TaskPriorityOption). Paired with a Selection model.

Selection Model¶

A concrete Django model that inherits from AbstractSelection. Acts as a through model between Tenant and Option, recording which options each tenant has enabled. Paired with an Option model.

Default Options¶

Options predefined by the application developer in the default_options dictionary on an Option model. These are synced to the database by running syncoptions. Default options are either Mandatory or Optional.

Custom Options¶

Options created by individual tenants at runtime. Only visible to the tenant that created them. Always have option_type = OptionType.CUSTOM.

OptionType¶

An enumeration defining the three kinds of options:

OptionType.MANDATORY (database value: "dm") – Always available to all tenants. Cannot be disabled.
OptionType.OPTIONAL (database value: "do") – Available to all tenants, but each tenant chooses whether to enable it.
OptionType.CUSTOM (database value: "cu") – Created by a specific tenant, only visible to that tenant.

Selections¶

The specific options that a tenant has chosen to enable. Mandatory options are always included automatically. Optional and custom options appear in a tenant’s selections only when explicitly enabled.

Soft Delete¶

A deletion strategy where records are not removed from the database. Instead, a deleted timestamp is set on the record. Soft-deleted options and selections are excluded from normal queries but remain in the database for data integrity (e.g., so existing ForeignKey references don’t break).

Use .delete() for soft delete and .delete(override=True) for hard (permanent) delete. Use .undelete() to restore.

Unscoped Manager¶

A secondary manager (unscoped) available on every Option and Selection model that returns all records, including soft-deleted ones. The default objects manager excludes soft-deleted records.

# Only active records
TaskPriorityOption.objects.all()

# All records, including deleted
TaskPriorityOption.unscoped.all()

Database Trigger¶

An optional database-level enforcement mechanism generated by maketriggers. Triggers ensure tenant-option consistency directly in the database, catching issues that could bypass Django’s ORM validation (e.g., direct SQL, race conditions).

`default_options`¶

A dictionary defined on an Option model class that specifies the developer-provided default options. Each key is the option name, and each value is a configuration dictionary:

default_options = {
    "High": {},                                      # Defaults to MANDATORY
    "Medium": {"option_type": OptionType.OPTIONAL},
}

`syncoptions`¶

A management command that synchronizes the default_options definitions from your model code into database records. Must be run after migrations and whenever default_options change.