mirror of
https://github.com/zitadel/zitadel.git
synced 2026-11-02 09:49:11 -06:00
Florian Forster
5100f2fc3f
## Problem
ZITADEL has inconsistent naming across docs, UI, and API
([#5888](https://github.com/zitadel/zitadel/issues/5888)). We want
contributors and Copilot code-review agents to flag discouraged terms
and suggest canonical replacements automatically.
## Solution
Add a **Markdown terminology catalog** that Copilot agents read
natively.
### What's added
- **`TERMINOLOGY.md`** (repo root) — full ~35-term canonical table from
issue #5888 with:
- Action legend: `keep` / `replace` / `remove` / `internal` / `proposed`
- Scope legend: `UI` / `Docs` / `API` / `Everywhere`
- "Search for (discouraged)" and "Replace with / enforce" columns
- Governance section (how to add new terms, ownership)
- **`.github/instructions/terminology.instructions.md`** — Copilot
`applyTo`-scoped instruction that activates on every PR touching
docs/i18n/proto files and tells the agent:
- Which files map to which scope
- Not to flag identifiers/field names in proto files (only
comments/descriptions)
- To request catalog updates when new terms are introduced
### What's updated
- `.github/copilot-instructions.md` — points to `TERMINOLOGY.md`
- `apps/docs/AGENTS.md` — updated reference, removed dead
`check-terminology` Nx target entry
- `.github/pull_request_template.md` — checklist item updated
- `.github/workflows/ready_for_review.yml` — checklist item updated
### Why Markdown over JSON
| | Markdown | JSON |
|---|---|---|
| Copilot reads natively | yes | no (needs parsing context) |
| Mirrors AGENTS.md table style | yes | no |
| Human-readable without tooling | yes | no |
| Mirrors the #5888 issue format | yes | no |
| Requires schema / parser | no | yes |
### Why root over `.github/`
`.github/` is for GitHub-specific automation files. `TERMINOLOGY.md` is
a project-wide convention document — it belongs alongside
`CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `AGENTS.md` at the repo
root.
## How it works in practice
When a PR touches `apps/docs/content/**`, `console/src/assets/i18n/**`,
`apps/login/locales/**`, or `proto/**/*.proto`, Copilot code review
automatically loads `.github/instructions/terminology.instructions.md`
and cross-references `TERMINOLOGY.md` to flag discouraged terms.
Human reviewers see the terminology checklist in the auto-comment on PR
open.
## Checklist
- [x] `TERMINOLOGY.md` at repo root with all ~35 terms from #5888
- [x] Plain text action/scope values (no emojis)
- [x] Copilot instruction file scoped to correct file patterns
- [x] All stale `terminology-rules.json` references removed
- [x] No linter/CI step added (guidelines-only approach)
Relates to: #5888
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Fabienne Bühler <fabienne@zitadel.com>
(cherry picked from commit 4586708c06)
8.3 KiB
8.3 KiB
ZITADEL Canonical Terminology
Authoritative naming reference derived from issue #5888. All user-facing wording in docs, UI, and API descriptions must follow this table.
Action values
| Action | Meaning |
|---|---|
| keep | Already correct — no change needed |
| replace | Discouraged term found — use the canonical term instead |
| remove | Term must be removed entirely |
| internal | Internal use only — must not appear in user-facing text |
| proposed | Under discussion — agents should flag but not block |
Scope values
| Scope | Files |
|---|---|
| UI | Console (console/src/assets/i18n/) and Login UI (apps/login/locales/) |
| UI + Docs | UI files plus documentation content (apps/docs/content/) |
| UI dialogs | Subset of UI: modal and confirmation dialog strings |
| UI section | Subset of UI: labels tied to a specific page section |
| UI indicator | Subset of UI: inline status or indicator labels |
| UI notifications | Subset of UI: toast, banner, and notification strings |
| Docs | Documentation content (apps/docs/content/) |
| API | Proto files and API description/comment text (proto/**) |
| Everywhere | UI + Docs + API |
| — | Internal only — no user-facing file scope |
Canonical Terminology Table
| Canonical term | Meaning / explanation | Search for (discouraged) | Replace with / enforce | Action | Scope |
|---|---|---|---|---|---|
| Customer Portal | Central hub for all customer interactions for cloud and self-hosting customers | (none — already canonical) | Customer Portal | keep | Everywhere |
| Management Console | Web interface where customers configure and manage ZITADEL resources. Must be visible as the UI app name. | Console, ZITADEL Console, Admin Console, Administration Console | Management Console | replace | UI |
| Instance | Private, isolated top-level ZITADEL environment | IAM, System, Type IAM | Instance / Type Instance | replace | Everywhere |
| Policies | Enforcement rules governing checks and constraints. Use only in enforcement contexts, always scoped (Instance / Organization). | Instance Policies, IAM Policies, Org Policies, Policies (unscoped), Instance Settings (when enforcing), Org Settings (when enforcing) | Instance Policies / Organization Policies | replace | Everywhere |
| Settings | Resource-specific configuration values (not rules). Use only in configuration contexts, always scoped (Instance / Organization). | Instance Settings, Org Settings, Instance Policies (when config), Org Policies (when config), IAM Policies (when config) | Instance Settings / Organization Settings | replace | Everywhere |
| Organization | Group of users within an instance | Organisation | Organization | replace | Everywhere |
| Organization Domain | Domain giving context where a user belongs | Primary Domain, Verified Domains, Org domains, verify your domain | Organization Domain | replace | UI + Docs |
| User (Human) | User with interactive authentication flows | Human, Human User, User: Type Human | User (Human) | replace | UI + Docs |
| Service Account | User with non-interactive authentication flows | Machine User, machine user, Service User, Machine Account, Technical Account, User: Type Machine | Service Account | replace | UI + Docs |
| User | UI display label for user identity | Display Name | User | replace | UI |
| Project | Container for applications sharing a role context | (none — already canonical) | Project | keep | Everywhere |
| Project Grant | Delegation of project access to another organization | Grant, Grants, Organization Grant, Delegated Access | Project Grant / Project Grants | replace | UI + Docs |
| Application | Software or service secured using ZITADEL | (none — already canonical) | Application | keep | Everywhere |
| Role Assignment | What a user is allowed to do (roles + org + user) | Authorization, external authorization, User Grant, Roles and Authorizations | Role Assignment | replace | Everywhere |
| Administrator | Role granting administrative privileges (role context only, not as a person label) | Manager, Add Manager, Add a Manager, Membership, Member, Member grants | Administrator / Add Administrator / Add an Administrator | replace | UI + Docs |
| Organization Administrators | Org-level admin role holders | ZITADEL Organization Managers | Organization Administrators | replace | UI + Docs |
| Project Administrators | Project-level admin role holders | Project A Managers | Project Administrators | replace | UI + Docs |
| Administrator Roles | Set of admin roles | Manager Roles, Membership Roles | Administrator Roles | replace | UI + Docs |
| ZITADEL Administrator Roles | ZITADEL-specific admin role set | ZITADEL Manager Roles, Zitadel Manager Roles, Zitadel Membership Roles, ZITADEL Membership Roles | ZITADEL Administrator Roles | replace | UI + Docs |
| Permission | Internal permission backing admin roles | (internal term) | (do not surface in user-facing text) | internal | — |
| Metadata | Key-value custom data attached to resources | Meta Data | Metadata | replace | Everywhere |
| Custom Domain | Domain identifying a ZITADEL instance (globally unique) | Custom domain, Installed domains, Instance Domains, Zitadel Domain, your_domain, your-domain | Custom Domain | replace | UI + Docs |
| Trusted Domain | Domain used for API/email contexts | (none — already canonical) | Trusted Domain | keep | Everywhere |
| Passkey | Passwordless auth using device-bound credentials | passwordless, passwordless login, passwordless auth, Multifactor (fingerprint/security keys), Fingerprint, Security Keys, WebAuthn, Webauthn | Passkey | replace | UI + Docs |
| TOTP | Time-based one-time password via authenticator app | OTP (authenticator), Authenticator App | TOTP | replace | UI + Docs |
| U2F | Legacy hardware authentication (deprecated) | U2F | (remove) | remove | Everywhere |
| OTP Email | One-time password delivered via email | Email OTP | OTP Email | replace | UI + Docs |
| OTP SMS | One-time password delivered via SMS | SMS OTP | OTP SMS | replace | UI + Docs |
| Organization ID | Explicit organization identifier | Resource Owner, OrgID, OrganizationID | organization_id |
replace | API |
| Explicit object IDs | Explicit identifier per resource type | Resource ID, ResourceID | user_id / project_id / application_id / instance_id / organization_id |
replace | API |
| Instance ID | Instance identifier label in UI | Resource Id (Instance) | Instance ID | replace | UI + Docs |
| ID | Generic identifier label in UI | Resource Id | ID | replace | UI |
| First Name | Personal given name field | Given Name | First Name | replace | Everywhere |
| Last Name | Personal family name field | Family Name | Last Name | replace | Everywhere |
| Add Administrator (dialog) | Consistent wording for admin-add dialog | Add Manager, Add a Manager | Add Administrator / Add an Administrator | replace | UI dialogs |
| Administrator (memberships section) | UI section on the user detail page showing admin memberships — should be labeled "Administrator", not "Memberships" | Memberships | Administrator | replace | UI section |
| Project Grants (section) | Project grant listing section | Grants | Project Grants | replace | UI section |
| Internal / External indicator | Shows if a user belongs to the same or a different org | (missing indicator) | internal / external | replace | UI indicator |
| Password changed | Past-tense wording for password change notification | Password change | Password changed | replace | UI notifications |
| Object descriptions | All resource descriptions must use end-user language | internal / technical wording | clear end-user language | replace | UI + Docs |
| Complement Token | Flow type for actions executed during token creation. In UI use "Complement Token"; in API use flowType = 2 (CustomiseToken). Docs must not show PreUserinfoCreation=3 for this type. |
Compliment Token, CustomiseToken, CustomizeToken | Complement Token | replace | Everywhere |
Governance
- To add a new term: open a PR that updates this table and references the decision thread.
- Terms under discussion may be added with action
proposed— agents will flag but not block. - Ownership: Docs + Product/UX + API maintainers approve changes to this file.
- Source of truth for this table: GitHub issue #5888