Improving Template Documentation with TemplateData Extension in MediaWiki

Ever stumbled on a mysterious template that looks like {{Infobox|…}} but offers no clue what each parameter does? You’re not alone. In the wild‑west of community wikis, templates are the building blocks, yet without clear documentation they become a nightmare for newcomers and even seasoned editors. The TemplateData extension was created to tame that chaos: it stores a machine‑readable description of a template’s parameters, then hands that data over to tools like VisualEditor, API consumers, and the occasional curious human.

Think of TemplateData as a cheat sheet baked right into the template page. It lives in a tiny <templatedata>…</templatedata> tag, written in JSON, and MediaWiki magically turns it into a nice table on the front‑end while also exposing it via action=templatedata. The result? Less guesswork, fewer broken transclusions, and a smoother editing experience.

Getting the extension onto your wiki – a quick‑and‑dirty guide

From MediaWiki 1.35 onward TemplateData is bundled, so you might already have it. Still, you need to enable it in LocalSettings.php and, if you like, tweak a few configuration variables.

• Or download the tarball from the extension page and extract it into extensions/TemplateData.
• Visit Special:Version – you should see “TemplateData (stable)” listed.

Finally, add this line at the very bottom of LocalSettings.php:

wfLoadExtension( 'TemplateData' );

Clone from Gerrit (recommended for developers):

cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateData

That’s it. The rest of the article assumes the extension is up and running.

Inside the <templatedata> tag – the format that matters

If you open a template page that already uses TemplateData, you’ll see something like this:

<templatedata>
{
    "description": "Shows a simple infobox for a person.",
    "params": {
        "name": {
            "label": "Person’s name",
            "type": "line",
            "required": true,
            "description": "Full name, as you’d write it in prose."
        },
        "birthdate": {
            "label": "Birth date",
            "type": "date",
            "autovalue": "{{subst:#time:Y-m-d}}"
        }
    },
    "paramOrder": ["name", "birthdate"]
}
</templatedata>

That JSON object is the “TemplateData object”. Its top‑level keys are:

• description – a one‑sentence plain‑text summary.
• params – an object where each property is a parameter name, mapping to a Param object.
• paramOrder – an array that tells the UI in which order to present the fields.
• sets (optional) – groups of parameters that belong together, useful for complex templates.
• maps (optional) – a bridge to external consumers like Citoid or other services.

Param object – the nitty‑gritty

Each parameter can have a handful of properties. Below is a quick cheat sheet you can paste into your own templates:

Property	Type	Default	What it does
label	InterfaceText	null	A short, human‑readable name (e.g. “Birth date”).
description	InterfaceText	null	A longer blurb that explains the purpose.
type	string	"unknown"	One of “line”, “string”, “date”, “url”, etc. (helps editors pick the right UI widget).
required	boolean	false	If true, the template will refuse to save without this parameter.
suggested	boolean	false	Marks the param as a good‑to‑have (VisualEditor shows it highlighted).
default	InterfaceText	null	A static fallback value when the user leaves the field empty.
autovalue	string	null	Dynamic defaults such as {{subst:#time:Y-m-d}}.
aliases	array of strings	[]	Alternative names that still map to this param (useful for legacy templates).
deprecated	boolean|string	false	Shows a warning and optionally suggests a replacement.
example	InterfaceText	null	Shows a sample value in the UI.
suggestedvalues	array of strings	[]	A drop‑down list for the user to pick from.

Notice the InterfaceText type – it can be a plain string or an object keyed by language code. If you write a plain string, MediaWiki automatically wraps it into an object for the current wiki language. That’s a handy shortcut, but if you want multilingual documentation, go ahead and write the object yourself:

"label": {
    "en": "Birth date",
    "de": "Geburtsdatum",
    "fr": "Date de naissance"
}

Inheritance – a neat trick you might not need

TemplateData lets a parameter inherit from another one, copying all its properties unless you override them. It’s useful when you have a family of similar templates. The inherits key disappears from the API output – the server flattens the inheritance, so downstream tools only see the final, resolved data.

Putting it to work in VisualEditor

When you enable the experimental GUI ($wgTemplateDataUseGUI = true;), editors get a nice pop‑up dialog that shows each parameter’s label, description, and any suggested values. The experience feels like filling out a form, not rewriting wikitext by hand. In practice, you’ll see this when you click the “Edit source” button on a page that uses a documented template – the dialog pops up automatically if the template has TemplateData.

Here’s a short walk‑through:

1. Open a page with a documented template, e.g. {{Infobox person}}.
2. Hit the “Edit” button. VisualEditor detects the TemplateData and shows a modal titled “Infobox person”.
3. Each field is pre‑filled with the autovalue if present (the date field will already contain today’s date).
4. When you’re done, click “Save”. MediaWiki validates the JSON (it must be well‑formed, required fields present, etc.) before accepting the change.

If the validation fails, you’ll see a friendly error – “Missing required parameter ‘name’”. That’s far better than a cryptic wikitext error later on.

Fetching TemplateData via the API – for bots and external tools

Developers love the action=templatedata API. A simple GET request returns the JSON payload for any template, wrapped in a “pages” object. Example:

https://en.wikipedia.org/w/api.php?action=templatedata&titles=Template:Cite_web&format=json

The response looks like this (trimmed for brevity):

{
    "pages": {
        "12345": {
            "title": "Template:Cite_web",
            "description": {"en":"Cite a web page."},
            "params": { … },
            "paramOrder": ["url","title","accessdate"]
        }
    }
}

Notice the extra title and pages wrappers – the API adds them for consistency across different query types. If you need just the raw TemplateData object, strip those layers in your code.

Typical use‑cases:

• Generating a documentation site that lists every template on a wiki.
• Building a custom “template picker” widget for a mobile app.
• Synchronising template definitions between wikis (e.g. copying a template from English Wikipedia to a regional language).

Configuration knobs you might want to turn

TemplateData ships with a few $wg globals that affect its behaviour. All have sensible defaults, but you can override them in LocalSettings.php:

Variable	Default	What it controls
$wgTemplateDataUseGUI	true	Whether the experimental JSON editor dialog is available.
$wgTemplateDataEditorNamespaces	[NS_TEMPLATE] (usually 10)	Namespaces where the TemplateData editor appears when creating a page.
$wgTemplateDataMaxFavorites	50	Maximum number of favourite templates a user can store in the UI.

Changing the namespace list is handy if you keep documentation pages in a custom namespace (e.g. NS_TEMPLATE_DOC) – just add its numeric ID to the array.

Best practices for writing robust TemplateData

1. Keep descriptions plain text. No wikitext, no links – the UI strips them out anyway.
2. Prefer short labels. Under 20 characters works nicely in the VisualEditor dialog.
3. Use type wisely. Setting "date" or "url" triggers the correct input widget (date picker, URL validation).
4. Leverage autovalue for frequently‑used defaults. Example: "{{subst:#time:Y-m-d}}" for a date param.
5. Document optional parameters. Mark them as suggested: true so editors know they’re useful but not required.
6. Provide example values. A sample helps users understand the expected format without reading the full description.
7. Use aliases for legacy names. If a parameter was renamed, keep the old name as an alias – older pages won’t break.
8. Deprecate responsibly. Set deprecated to a string with guidance, e.g. "Use ‘newParam’ instead.".

A real‑world story: how a community saved hours

On a mid‑size wiki dedicated to historic ship models, the “ShipInfobox” template had ten parameters, but only three were documented in a separate doc page. New editors kept typing [[{{{shipname|}}}}] and wondering why the infobox broke. After a quick sprint, the maintainers added a full TemplateData block, filled out labels, added suggested values for “year built” (a list of common years), and set required: true on “shipname”. Within a week, the number of broken infoboxes dropped from dozens to zero, and the community reported a 30 % reduction in support tickets related to that template.

Keeping TemplateData up to date – automation tips

Because TemplateData lives in wikitext, it’s easy to forget updating it when the template changes. Here are a few ways to stay on top of it:

• Linting bots. Write a simple bot that scans all templates for a missing <templatedata> tag and posts a reminder on the talk page.
• CI pipelines. If you maintain the wiki’s code in a Git repository (as many large wikis do), add a step that runs php maintenance/checkTemplateData.php – a hypothetical script that validates JSON syntax and required fields.
• Make it part of the review process. When a template edit is reviewed in Gerrit, reviewers can check the diff for changes to the templatedata block and approve only if it’s consistent.

Common pitfalls and how to avoid them

Problem	What happened	Fix
Using wikitext inside description	The UI displayed raw markup, breaking the table layout.	Strip out any [[Link]] or '''bold''' – keep it plain.
Missing commas in JSON	Saving the template threw a generic “Invalid JSON” error.	Run the JSON through a linter or paste it into jsonlint.com before saving.
Wrong type value	VisualEditor showed a text field for a URL, missing the clickable preview.	Use the exact strings listed in the docs – “url”, “date”, “wiki-page-name”, etc.
Too many parameters in paramOrder	The UI ignored the order and displayed them alphabetically.	Match the array exactly to the keys in params; extra entries are ignored.

Future‑looking: where TemplateData might go next

The extension is already stable, but the community keeps adding features. A few ideas that have been floated on Phabricator:

• Support for richer InterfaceText objects, allowing markdown‑style formatting that still renders as plain text in the UI.
• “Conditional parameters” – hide a field unless another field has a certain value.
• Better integration with Wikidata, letting a template automatically pull property definitions from a linked item.
• Server‑side validation hooks that could enforce custom business rules (e.g., “if type=“date” then autovalue must be a date format).

Keep an eye on the Phabricator tag for the latest tickets.

Final thoughts

TemplateData isn’t just a fancy JSON blob – it’s a bridge between human editors, visual tools, and programmatic consumers. By investing a bit of time to write clear labels, concise descriptions, and sensible defaults, you make your wiki more approachable, reduce errors, and give downstream projects (like VisualEditor or external bots) a reliable source of truth.

So the next time you create a template, ask yourself: “If a brand‑new editor landed on this page, would they know what each parameter does?” If the answer is “no”, crack open a <templatedata> tag and start filling in the blanks. The community will thank you – and your future self will thank you even more.