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 show a form, the API can return it to bots and tools, and humans still get a readable parameter table on the template page.

Enable TemplateData

TemplateData is bundled with many MediaWiki installs, but bundled does not always mean enabled. Check Special:Version. If TemplateData is not listed, load it from LocalSettings.php:

wfLoadExtension( 'TemplateData' );

If your deployment installs extensions manually, place the extension under extensions/TemplateData first. 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 or its documentation subpage. The content is JSON:

<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. The work is in writing parameter descriptions that are short, exact, and useful to editors.

Parameter fields that matter

You do not need every possible 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: useful for common optional fields
• example: one realistic value
• aliases: old parameter names that should still be understood
• deprecated: warning text for a parameter that should no longer be used

Keep descriptions plain. Do not put wikitext formatting, long policy explanations, or links inside every field. Editors need to know what to enter, not read a second documentation page inside a dialog.

VisualEditor

TemplateData is most visible in VisualEditor. When a documented template is inserted or edited, VisualEditor can show fields with labels, descriptions, examples, required flags, and suggested parameters. That turns a template from a raw wikitext call into a form-like editing experience.

This does not remove the need for normal template documentation. It gives editing tools reliable metadata. Keep the human docs for examples, usage notes, edge cases, and screenshots. Keep TemplateData focused on the parameter contract.

API use

TemplateData is also available through the MediaWiki API. That is useful for bots, linting tools, documentation generators, and custom editing interfaces.

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

The response wraps TemplateData by page. API consumers should expect page IDs, titles, and then the TemplateData object. Do 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.

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

Maintenance

TemplateData becomes stale when template code changes but the JSON block does not. Make updates part of the template review process. If a template adds a parameter, removes one, changes a default, or renames a field, update TemplateData in the same edit.

For larger wikis, a bot or maintenance script can check for obvious problems:

• templates with no <templatedata> block
• invalid JSON
• parameters documented in TemplateData but missing from the template
• parameters used by the template but missing from TemplateData
• aliases that point to removed behavior

Common pitfalls

• Invalid JSON. Trailing commas and unescaped quotes are common causes.
• Descriptions that are too long. Move long explanations to the documentation page.
• Wrong types. Use the documented type strings so editing tools can choose useful 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 not glamorous, 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.