Improving Template Documentation with TemplateData Extension in MediaWiki

TemplateData solves a specific MediaWiki problem: templates can be powerful, but their parameters are often hard to discover. A template may accept name, image, date, status and several legacy aliases, while the editor has to guess what each one means. The TemplateData extension stores that parameter documentation in a machine-readable block: VisualEditor can use it to render a form, the API can return it to bots and tools, and humans still get a readable parameter table on the template page.

Enabling TemplateData

TemplateData has been bundled with MediaWiki since version 1.35, but "bundled" does not always mean "loaded". Check Special:Version first. If TemplateData is not listed, load it from LocalSettings.php:

wfLoadExtension( 'TemplateData' );

For manual deployments, place the extension in extensions/TemplateData and match the extension version to your MediaWiki branch, the same as with other bundled extensions.

What the block looks like

TemplateData lives inside a <templatedata> tag, usually on the template page itself or in a documentation subpage that is transcluded into it. The content is strict JSON — trailing commas, unescaped quotes or malformed types are rejected at save time:

<templatedata>
{
    "description": "Displays a short profile box for a person.",
    "params": {
        "name": {
            "label": "Name",
            "description": "Full name shown in the heading.",
            "type": "line",
            "required": true,
            "example": "Ada Lovelace"
        },
        "birth_date": {
            "label": "Birth date",
            "description": "Date of birth, preferably in ISO format.",
            "type": "date",
            "suggested": true,
            "example": "1815-12-10"
        }
    },
    "paramOrder": [ "name", "birth_date" ]
}
</templatedata>

The top-level shape is simple: one description, a params object, and optional ordering or grouping metadata. Descriptions must be plain text — wikitext is not accepted inside the block. The real work is in writing parameter descriptions that are short, exact and useful to editors.

Parameter fields that matter

You do not need every field on every parameter. Start with these:

• label — short field name shown in editing tools
• description — plain-text explanation of what the value does
• type — expected value shape, such as line, string, date, url or wiki-page-name
• required — mark only parameters the template genuinely needs
• suggested — for common optional fields
• example — one realistic value
• aliases — old parameter names that should still be understood
• deprecated — warning text for parameters that should no longer be used

VisualEditor and the API

TemplateData is most visible in VisualEditor. When a documented template is inserted or edited, VisualEditor shows the fields with labels, descriptions, examples, required flags and suggested parameters — turning a raw wikitext call into a form-like experience. This does not replace normal template documentation; it gives editing tools reliable metadata. Keep human docs for usage examples and edge cases, and keep TemplateData focused on the parameter contract.

The same metadata is exposed through the MediaWiki API, which makes it useful for bots, linting tools and documentation generators:

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

API consumers should expect the response keyed by page, and must not assume every template has complete metadata, especially on older community wikis.

Writing good TemplateData

Good TemplateData is boring in the best way: it says what the parameter does, what value shape is expected, and whether editors should normally fill it in.

• Document real parameters only. Remove fields the template no longer reads
• Use stable names. If a parameter was renamed, keep the old name in aliases
• Do not overuse required. A field should be required only if the template breaks without it
• Use suggested for common optional fields. It guides editors without forcing bad data
• Add examples for ambiguous formats. Dates, page names, identifiers and URLs benefit most
• Keep paramOrder aligned with the template — put the fields editors need first

Maintenance

TemplateData goes stale when template code changes but the JSON block does not. Make it part of the template review process: if a template adds or removes a parameter, changes a default or renames a field, update the TemplateData block in the same edit. On larger wikis, a bot can check for templates with no block at all, invalid JSON, parameters documented but missing from the template code, and aliases pointing at removed behavior.

Common pitfalls

• Invalid JSON — trailing commas and unescaped quotes are the usual causes
• Descriptions that are too long — move long explanations to the documentation page
• Wrong types — use the documented type strings so editing tools pick the right controls
• Everything marked required — editors will fill fields with junk just to satisfy the dialog
• No examples — a one-line example often prevents repeated cleanup edits

TemplateData is unglamorous, but it pays off quickly: editors get clearer forms, bots get structured metadata, and template maintainers get fewer broken calls. The best time to add it is when a template is created; the second-best time is the next time somebody asks what half the parameters mean. The Help:TemplateData page documents the full schema.