Skip to content

Convention — description fields (D9)

What it is

"D9" is the locked pattern (MIQ-133 decision 52) for any optional, long-text, bilingual description field on a lookup-admin CRUD: a paired English/Arabic textarea, 1000-char cap, optional, with Arabic right-to-left. It exists so every "Description" field across admin screens looks and behaves identically.

When to use it

When a lookup entity carries a nullable Description_1_English / Description_2_Arabic pair (or any nullable long-text admin field). First adopter: Skill (SkillAdminDtos — Description1English / Description2Arabic, both nullable).

The pattern

Data / DTO. Two nullable fields, Description_1_English and Description_2_Arabic, varchar capped at 1000. The service runs NormalizeNullableText so empty/whitespace input is stored as NULL, never "".

UI. A 4-row <textarea> pair, English above Arabic, both maxLength={1000}, both optional, the Arabic one carrying dir="rtl". Below each, localized helper text: "Optional. Max 1000 characters."

Validation. Optional (no NotEmpty); a max-length rule at 1000. Localized via the BE i18n key <Entity>.Validation.* scheme if a message is needed.

Gotchas / constraints

  • Empty normalizes to NULL. Don't persist "" — the service's NormalizeNullableText collapses blank/whitespace to NULL so "no description" is represented one way only.
  • Both languages optional and independent — a row may have an English description and no Arabic one, or neither.
  • The shape is locked. A new description field reuses this exact pattern (1000 / optional / RTL-on-Arabic / 4-row pair). If a field needs different rules (required, longer, single-language), it is not a D9 field — don't bend D9 to fit it.
  • Distinct from the required bilingual name columns. Name_1_English / Name_2_Arabic follow the entity's (often required) name rules; D9 governs the description long-text fields specifically.

Build status

Available — locked in MIQ-133 (decision 52) and implemented on Skill admin (MIQ-133 Phase 2); the reference pattern for future description fields.