Skip to content

OSAC-2921: Revise design — Metadata display_name + Markdown description #206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
udis wants to merge 3 commits into from
Closed

OSAC-2921: Revise design — Metadata display_name + Markdown description #206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fa5aa91
OSAC-2921: Revise Metadata design to title + required Markdown
udis Aug 12, 2026
4fa2896
OSAC-2921: Keep Metadata display_name; Markdown MUST for description
udis Aug 13, 2026
3d26927
OSAC-2921: Require Markdown sanitization for description in PRD
udis Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 19 additions & 11 deletions enhancements/OSAC-2921-metadata-display-name/design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: metadata-display-name
authors:
- ushkalim@redhat.com
creation-date: 2026-08-02
last-updated: 2026-08-04
last-updated: 2026-08-13
tracking-link:
- https://redhat.atlassian.net/browse/OSAC-2921
prd:
Expand All @@ -27,6 +27,12 @@ hardcoded to `id`), and removes per-resource `title`/`description` fields from
the twelve object types that currently define them — with a one-shot data
migration. See [PRD](prd.md) for detailed requirements.

### Revision (2026-08-13)

- Keep Metadata friendly label as **`display_name`** (not `title`).
- `description` is **Markdown** — clients that display it **must** render Markdown (with sanitization).
- i18n / localized maps are **out of scope**; do not reserve proto fields for them in this enhancement.

## Motivation

OSAC objects already expose `metadata.name`, but that field is constrained to
Expand Down Expand Up @@ -231,8 +237,9 @@ string display_name = 11 [(buf.validate.field).string = {
max_len: 63
}];

// Optional human-friendly description. Opaque string; clients may
// treat content as Markdown. Not unique, mutable.
// Human-friendly long description in Markdown. Optional, not unique,
// mutable. Clients that display this field MUST render it as Markdown
// (with safe sanitization — see Security Considerations).
string description = 12 [(buf.validate.field).string = {
max_len: 256
}];
Expand Down Expand Up @@ -376,14 +383,13 @@ user-controlled strings — same trust model as annotations and existing
per-type descriptions. The API validates length only and does not sanitize,
transform, or execute description content.

**Client safe rendering (required):** Treat `metadata.description` (and any
future Markdown presentation of it) as untrusted user input. UI and CLI
clients that render descriptions as Markdown or HTML **must** encode or
sanitize before display (for example HTML-escape plain text, or run a
Markdown renderer with a strict allowlist that strips scripts and unsafe
URLs). Do not pass raw description strings into `innerHTML`, shell
expansion, or other execution contexts. Broader UI hardening beyond this
policy is tracked as a follow-up outside the server cutover.
**Client Markdown rendering (required):** `metadata.description` **is**
Markdown. UI and CLI clients that display the field **must** render it as
Markdown and **must** treat the content as untrusted user input: sanitize
before display (strict allowlist Markdown renderer that strips scripts and
unsafe URLs; never pass raw strings into `innerHTML`, shell expansion, or
other execution contexts). Broader UI hardening beyond this policy is
tracked as a follow-up outside the server cutover.

### Failure Handling and Recovery

Expand Down Expand Up @@ -602,3 +608,5 @@ Authored: respond @ design 0.4.2 - 75ae801, workspace main @ 3cb3621
Phases: draft, respond

<!-- ai-workflow-provenance:{"schema_version":1,"provenance_kind":"session","workflow":"design","workflow_version":"0.4.2","ai_workflows":"75ae801","source_repo":"3cb3621","source_repo_branch":"main","commits_behind_main":0,"commits_ahead_main":0,"main_ref":"main","phases":["draft","respond"],"authoring_modes":["skill"],"context_changed":false} -->

Revised: 2026-08-13 — keep `display_name`, Markdown MUST for `description`, no localized-field reservations (osac#263)
15 changes: 9 additions & 6 deletions enhancements/OSAC-2921-metadata-display-name/prd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
| Author(s) | Udi Shkalim |
| Jira | https://redhat.atlassian.net/browse/OSAC-2921 |
| Date | 2026-07-21 |
| Last updated | 2026-08-14 |

## Problem Statement

Expand All @@ -13,7 +14,7 @@ OSAC resources use `metadata.name` as the primary human-visible identifier, but
## In Scope

- Consistent, user-friendly resource naming across all OSAC resource types, all personas, and all client interfaces (API, CLI, Web UI) `[PR review: mhrivnak]`
- Two new shared Metadata fields: `display_name` (optional, max 63 characters) and `description` (optional, max 256 characters) — both mutable, clearable, and not required to be unique `[Clarify: R2.Q1, R3.Q1, R4.Q4, PR review: sk-ilya]`
- Two new shared Metadata fields: `display_name` (optional, max 63 characters) and `description` (optional, max 256 characters, **Markdown**); clients that display it MUST render Markdown with sanitization — both mutable, clearable, and not required to be unique `[Clarify: R2.Q1, R3.Q1, R4.Q4, PR review: sk-ilya]`
- Reconciliation of existing per-resource `title`/`description` fields — removed from all 12 resource types that currently have them: Project, Role, IdentityProvider, InstanceType (description only), ClusterTemplate, ComputeInstanceTemplate, BareMetalInstanceTemplate, NetworkClass, HostType, ComputeInstanceCatalogItem, BareMetalInstanceCatalogItem, ClusterCatalogItem `[Clarify: R1.Q1, PR review: sk-ilya, ygalblum]`
- Filtering and sorting by `display_name` `[Clarify: R2.Q2]`

Expand All @@ -22,12 +23,13 @@ OSAC resources use `metadata.name` as the primary human-visible identifier, but
- Resource identity — `metadata.name` remains the unique identifier `[PR review: mhrivnak]`
- Display behavior (how clients present `display_name` vs `metadata.name`) — deferred to UX and design phase `[PR review: mhrivnak, ygalblum]`
- Template parameter `title`/`description` fields within ComputeInstanceTemplate, BareMetalInstanceTemplate, and ClusterTemplate — only resource-level fields are affected `[Clarify: R1.Q3]`
- Full multi-locale / i18n Metadata in this feature — single canonical `display_name` / `description` only; localized maps deferred `[osac#263]`

## User Stories

### Cloud Provider Admin

- As a Cloud Provider Admin, I want resources across all tenant organizations to show a consistent, human-readable `display_name` and `description` so that I can quickly identify and audit resources when reviewing or supporting tenants, regardless of resource type.
- As a Cloud Provider Admin, I want resources across all tenant organizations to show a consistent, human-readable `display_name` and Markdown `description` so that I can quickly identify and audit resources when reviewing or supporting tenants, regardless of resource type.
- As a Cloud Provider Admin, I want to filter and sort resource lists by `display_name` so that I can find resources across tenants using natural-language terms. `[Clarify: R2.Q2, PR review: mhrivnak]`

### Cloud Infrastructure Admin
Expand All @@ -36,12 +38,12 @@ OSAC resources use `metadata.name` as the primary human-visible identifier, but

### Tenant Admin

- As a Tenant Admin, I want all resource types I manage (VMs, virtual networks, public IPs, security groups, etc.) to support a friendly `display_name` and `description` so that I can give resources a natural-language name and description that are not constrained to DNS-label format. `[PR review: mhrivnak]`
- As a Tenant Admin, I want all resource types I manage (VMs, virtual networks, public IPs, security groups, etc.) to support a friendly `display_name` and Markdown `description` so that I can give resources a natural-language name and description that are not constrained to DNS-label format. `[PR review: mhrivnak]`
- As a Tenant Admin, I want to update or clear `display_name` and `description` on existing resources so that I can correct labels or remove outdated descriptions as resources evolve. `[Clarify: R3.Q1]`

### Tenant User

- As a Tenant User, I want to give my resources a friendly `display_name` (up to 63 characters) and `description` when creating them so that I can identify and organize them more easily than relying on the constrained `metadata.name` field. `[Clarify: R2.Q1]`
- As a Tenant User, I want to give my resources a friendly `display_name` (up to 63 characters) and Markdown `description` when creating them so that I can identify and organize them more easily than relying on the constrained `metadata.name` field. `[Clarify: R2.Q1]`

## Dependencies

Expand All @@ -52,8 +54,9 @@ OSAC resources use `metadata.name` as the primary human-visible identifier, but
## Provenance

Authored: draft @ prd 0.5.0 - 92734a2, workspace main @ aac0f8e
Final: respond @ prd 0.6.1 - 96de078, workspace main @ 7b4fff2
Final: respond @ prd 0.7.1 - b8b3f86 (dirty), workspace main @ b4cbc82 (dirty)
Revised: 2026-08-14 — clients MUST sanitize Markdown `description` when rendering

> Context changed between draft and respond.

<!-- ai-workflow-provenance:{"schema_version":1,"provenance_kind":"session","workflow":"prd","workflow_version":"0.6.1","ai_workflows":"96de078","source_repo":"7b4fff2","source_repo_branch":"main","commits_behind_main":0,"commits_ahead_main":0,"main_ref":"main","phases":["draft","revise","respond","respond","respond"],"authoring_modes":["skill"],"context_changed":true} -->
<!-- ai-workflow-provenance:{"schema_version":1,"provenance_kind":"session","workflow":"prd","workflow_version":"0.7.1","ai_workflows":"b8b3f86 (dirty)","source_repo":"b4cbc82 (dirty)","source_repo_branch":"main","commits_behind_main":0,"commits_ahead_main":0,"main_ref":"main","phases":["draft","revise","respond","respond","respond","respond"],"authoring_modes":["skill"],"context_changed":true,"origin_untracked":false} -->
Loading