mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
4586708c06
## 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 <[email protected]> Co-authored-by: Fabienne Bühler <[email protected]>
83 lines
8.3 KiB
Markdown
83 lines
8.3 KiB
Markdown
# ZITADEL Canonical Terminology
|
|
|
|
Authoritative naming reference derived from [issue #5888](https://github.com/zitadel/zitadel/issues/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](https://github.com/zitadel/zitadel/issues/5888)
|