Page MenuHomePhabricator

Rename Description column to Caption + enforce SDC caption rules (!25)
Closed, ResolvedPublic

Description

Summary

Rename the table's "Description" column to "Caption" — the term Commons / SDC actually uses for the short-label field — and enforce Commons' caption rules (length limit, character restrictions, language tagging). Surface clear error messages on violations and a tooltip that explains what makes a good caption.

Research first

Look up Commons / Wikidata documentation for SDC captions (a.k.a. labels in Wikibase / mw.cs.label / Special:MediaSearch). Confirm and document in the task:

  • Length limit — believed to be ~250 characters; verify the exact limit and whether it's enforced server-side, client-side, or both.
  • Character restrictions — line breaks, HTML, wikitext, links: which are stripped / disallowed?
  • Language tag — captions are per-language; what's the storage format the API expects?
  • Multilingual captions — note the relationship to T425864's "Add language" placeholder for the Description column. Coordinate with that work if relevant.

Implementation

  • Rename the Description column header to Caption everywhere in the UI (header, columns modal, settings dropdown, etc.).
  • Add a client-side validator on the cell editor that:
    • Blocks / warns on length-limit violations (live character count visible to the user, like a short-form textarea pattern).
    • Strips or warns on disallowed characters.
  • Inline error message immediately below the cell when validation fails; clear actionable wording (e.g. "Captions must be ≤ 250 characters — you have 312.").
  • Tooltip on the column header (and/or an info icon) summarising "what makes a good caption" — short, plain-language guidance with a link to Commons' caption help page.

Out of scope

  • The longer-form file Description (the one stored in the wikitext description= field) — captions and descriptions are different fields on Commons; this task is about the SDC caption.
  • Multilingual caption editing (T425864 placeholder).

Acceptance

  • Column header reads "Caption" everywhere.
  • Typing past the length limit shows a clear error and prevents publish.
  • Hover / info icon shows the caption-writing guidance.
  • The validator's behaviour matches what the documented Commons / SDC limits actually are.

Source

User feedback session, 2026-05-10.

Event Timeline

Daanvr moved this task from To do to Doing on the Tool-upload-workbench board.

Research findings

Length limit: 250 characters per caption per language.

  • Source: Commons:File_captions — limited to 250 characters in length and cannot contain markup.
  • Enforced server-side by Wikibase (the underlying repository for SDC).

Character restrictions:

  • No newlines / vertical whitespace — Wikibase string validator disallows leading/trailing whitespace and vertical whitespace such as newlines/tabs.
  • No wikitext markup — captions render as plain text; no links, no templates, no formatting.
  • No HTML — same reason.
  • At least one character — empty captions are not allowed.

Storage format (per-language, confirmed via Special:EntityData/M<page-id>.json):

labels: { en: { language: 'en', value: '<caption text>' }, nl: { language: 'nl', value: '...' } }

Naming clash: Commons has both an SDC caption (Wikibase label) and a wikitext description= field. The current workbench column called Description is in fact the SDC caption — this rename eliminates the confusion. The longer-form wikitext description remains untouched.

Coordination with T425864: that task adds an Add-language placeholder for the column. Renaming to Caption first and validating the canonical (English) value is independent — multilingual editing remains future work and reuses the same validator.

Implementation plan

  • Internal column key stays description for now (avoids touching every persistence path). Only the display label changes to Caption.
  • New validateCaption(text) helper returning { valid, errors[], length }. Errors: too-long, contains-newline, contains-html, contains-wikitext-link.
  • TextEditor cell shows live N/250 counter; turns red past 250.
  • Inline error message under the cell while editing.
  • Tooltip + info icon in the column header summarising the rules + linking to https://commons.wikimedia.org/wiki/Commons:File_captions.

Some feedback. Uh it now's every time you hit space it makes the text red saying there's a trailing uh white space. Um this is fine that this is not allowed, however, let's never mention the trailing white space and let's just remove the trailing white space whenever The field is deselected. or saved or something like this. What trailing white spaces should never be saved or kept however they should be able while writing they should be possible while writing without seeing a warning.

Let's not worry the user with the maximum of 250 characters before the user gets close to it. So only above 200 characters the user will be warned with an indication that The maximum is two hundred and fifty characters.

When having more than the limit of characters? There is a indication by saying 300 characters of the 300 slash 250 characters so indicating you have more than one uh more than the maximum And then there is a warning message underneath it saying it should be less than 250. That's good, that's okay. However it should doesn't need to repeat the number of characters and it could be on the same line
Now that I think of it. The indication that you're close to the maximum should only be there whenever you're close, so above 200 characters. And the message that you're above it uh can be part of the same error message. Or the same line, the same label basically. So it first shows a grey or black normal neutral. um 210 characters of 250 and then when you go above it becomes red or it just becomes red no message needed just becomes red And the placeholder text before you start typing Does not need to indicate the mac maximum number of characters. Only the short text caption, plain text caption. Um I think there are indications of uh what the goal of the caption is. Maybe that should be the placeholder text and not the requirements Please research it and see how you can fit it in a few words as the placeholder text.

Also, if it's above the maximum and you deselect the field, it shows no problems whatsoever and ready to upload, even though That is not allowed. So the warning should persist even when the f uh thing is deselected, when the cell is deselected

Daanvr renamed this task from description should be caption. to Rename Description column to Caption + enforce SDC caption rules (!25).May 11 2026, 2:12 PM

Iterated per feedback (2026-05-11):

  • Counter is now hidden below 200 chars (no nag for short captions). 200–250 it sits in neutral grey ("210 / 250"); over 250 it turns red ("300 / 250") with a single short error message beside it on the same line — no count repetition.
  • Trailing/leading whitespace silently trimmed on commit; no "trailing whitespace" warning while typing.
  • Placeholder now describes the goal of a caption ("Brief description of the file"), not the 250-char limit. (Researched Commons:File_captions: it calls them "short, multilingual descriptions about files" — the placeholder reflects that goal.)
  • Persistent in-cell error indicator: an over-limit (or otherwise invalid) saved caption now renders the cell with a red background and a warn icon next to the text, mirroring the visual language of the --missing class. Blurring out of an invalid value no longer hides the warning.

Preview updated: https://upload-workbench.toolforge.org/mr-25/

Released as v0.11.0 (MR !25 merged into main).