Page MenuHomePhabricator

Move TemplateData to its own JSON-content namespace and associate with Template-namespace, or to its own TemplateData content model and revision slot
Open, HighPublicFeature

Description

e.g. Template:Information could be documented at TemplateData:Information instead of inside the source code of Template:Information.

Pros:

1. More standard use of ContentHandler for JSON across projects
2. Document templates without needing to make edits to templates that are potentially transcluded across large swaths of pages
3. Easier to implement custom editors for ContentHandler pages than for portions of wikitext pages.

Cons:

1. Would need to have two separate systems - one for the JSON storage, then another to transclude the generated documentation onto template doc pages, e.g. with <templatedata /> or {{#templatedata}} or so (no params needed, because the TemplateData namespace page can be of the same name, like a talk page)
2. Would need to rework the existing editor (sorry, mooeypoo) to work with the new system


See Also: T52512: TemplateData: Page properties should not be stored twice (both Template and Template/doc)

Related Objects

View Standalone Graph
This task is connected to more than 200 other tasks. Only direct parents and subtasks are shown here. Use View Standalone Graph to show more of the graph.

Event Timeline

bzimport raised the priority of this task from to High.Nov 22 2014, 1:48 AM
bzimport added a project: TemplateData.
bzimport set Reference to bz54140.

I talked about that briefly on IRC, we decided that since this is specifically about the namespace proposal, until we decided what to do about it, we'd leave both open. And closing that bug may not necessarily close this bug.

Krinkle renamed this task from TemplateData: Store TemplateData in its own namespace ("Template data:") with a JSON content type and associated to the Template: namespace to Move TemplateData to its own JSON-content namespace and associate with Template-namespace.May 8 2015, 3:55 AM
Jdforrester-WMF renamed this task from Move TemplateData to its own JSON-content namespace and associate with Template-namespace to Move TemplateData to its own JSON-content namespace and associate with Template-namespace, or to its own TemplateData content model and revision stream..Jan 15 2016, 9:27 PM

I've fiddled with this because either T487: RfC: Associated namespaces or T107595: [RFC] Multi-Content Revisions would both meet this need. I think the latter is both more likely to occur and a better outcome, but…

I do raise two issues against the proposal, at least for mandatory evaluation of JSON pages only.

  • Pro #2 reads as: “Document templates without needing to make edits to templates that are potentially transcluded across large swaths of pages”
    • This goes for any kind of lengthy documentation, and is usually solved by transclusion of a separated /doc into main template page.
    • German Wikipedia is using that technique for any longer template documentation since 2008, and enforces TemplateData on separated docpage for all productive templates.
  • There are JSON objects built by template-like transclusion via {{#tag:}} syntax.
    • See Kategorie:Vorlage:Metadokumentation on German Wikipedia – a dozen of so-called “meta documentation” pattern pages is generating nearly thousand TemplateData objects on particular template pages, controlled by template name and sometimes parameters.

Optional separated .json subpages may be introduced, but classic <templatedata> approach needs to be supported, too.

This could be held like doc subpages or currently deployed css subpages instead

Jdforrester-WMF renamed this task from Move TemplateData to its own JSON-content namespace and associate with Template-namespace, or to its own TemplateData content model and revision stream. to Move TemplateData to its own JSON-content namespace and associate with Template-namespace, or to its own TemplateData content model and revision slot.Oct 31 2018, 3:16 PM
  • There are JSON objects built by template-like transclusion via {{#tag:}} syntax.
    • See Kategorie:Vorlage:Metadokumentation on German Wikipedia – a dozen of so-called “meta documentation” pattern pages is generating nearly thousand TemplateData objects on particular template pages, controlled by template name and sometimes parameters.

Interesting. json-schema allows referencing/embedding other schemas by using a special "$ref": "[URI to another schema]" key. Maybe something like that could be implemented in TemplateData instead of requiring the use of parser functions.

Please note that these are not static pages.

  • The URI comment looks like assigning a static page which is simply transcluded.
  • Entire JSON TemplateData descriptions are generated individually by template or Lua programming; depending on parameters and existence of other pages.
  • You may have a look e.g. at use of lang/Latn/Doku and the derived page.

See related approach by Module:TNT -- it stores templatedata as a table (example). In this case <templatedata> will be dynamically generated during the parse time, and is available to every language/every wiki.

Aklapper changed the subtype of this task from "Task" to "Feature Request".Feb 4 2022, 12:23 PM
Aklapper removed a subscriber: TrevorParscal.

Tagging Wikimedia-Hackathon-2023 to showcase a basic PoC created during this event.

Would the current JSON structure continue to be supported? c:Template:TemplateBox relies on being able to generate JSON to avoid unnecessarily duplicating content between the TemplateData and the wikitext description (the latter supports wiki markup, so TemplateData can’t entirely supersede it, unless TemplateData will also start to support wiki markup).

Change 921693 had a related patch set uploaded (by TK-999; author: TK-999):

[mediawiki/extensions/TemplateData@master] [PoC] MCR slot for TemplateData content

https://gerrit.wikimedia.org/r/921693

Would the current JSON structure continue to be supported?

For the transition, certainly. Long-term, probably not, and hacks to generate the transclusion data would have to make way for proper documentation.

c:Template:TemplateBox relies on being able to generate JSON to avoid unnecessarily duplicating content between the TemplateData and the wikitext description (the latter supports wiki markup, so TemplateData can’t entirely supersede it, unless TemplateData will also start to support wiki markup).

Ack, the very-intentional lack of support for wikitext (and all the horrors that entails) means some forms of documentation are hard to do. We should probably add additional fields including link targets and good- and bad-example samples to augment the structured data so that it works better for secondary use cases. That's outside the scope of this task, however.

Many many templates are not documented by an individual JSON for each single template, but derived from series of JSON data generated by documentation template or Lua module, creating TemplateData for many productive templates.

German Wikipedia is documenting latin based language templates by Template:lang/Latn/Doku which provides one unique pattern for all of them (196 single templates). The TemplateData and the entire documentation page is produced by very short transclusions like {{lang/Latn/Doku|CODE=lv|SPRACHE=lettischer Sprache|EXAMPLE=Rīga}} in Template:lvS.
Category:Vorlage:Metadokumentation lists a pile (53) of such meta documentation patterns. Currently we are planning schemes which are generating full documentation pages for several 10,000 single productive templates, with heading TemplateData of course.

The concept of independent namespace for TemplateData is based on the assumption that every productive template has one static individual JSON code without any JSON code injection.

Long-term, probably not, and hacks to generate the transclusion data would have to make way for proper documentation.

These are not hacks, these are proper solutions using the public API of TemplateData (a JSON blob), making template editors’ lives easier. How can this “proper documentation” be created without duplicating everything between the TemplateData-compatible documentation and the actually useful documentation (i.e. one that contains e.g. inline links)? Looking at the PoC patch, keeping support for JSON blobs in wikitext would probably need 5-10 lines of extra code, which doesn’t sound like a horrible tech debt even long-term.

MediaWiki developers seem to sometimes forget how much the community relies on templates. Parsoid doesn’t support templates emitting unbalanced wikitext. The result? Large blocks of text, sometimes even whole pages, that have to be edited in wikitext in VisualEditor, or can’t be edited at all. Structured Data on Commons doesn’t support templates at all. The result? Instead of either using or replacing wikitext, all machine-readable metadata is still present in wikitext in one form, and bots duplicate it to another form, making actual edits to pages. Please don’t do the same mistake again and again.

For the record, TemplateData is also read to create automatic template examples, see https://ru.wikipedia.org/wiki/Module:TemplateDataDoc
This is not a use case that will be supported by Lua if TemplateData data gets moved to another slot, without implementing T107119: Provide a Lua method mw.templatedata.load()

For the transition, certainly. Long-term, probably not, and hacks to generate the transclusion data would have to make way for proper documentation.

Having shared TemplateData between pages or generating TemplateData programmatically, which those cases cover, are legitimate uses of TemplateData and not hacks. If anything, more templates with the same parameter configurations (like, for example, navigation templates) would benefit from it if it was more widely adopted. Currently, TemplateData adoption is too low, and if anything, we should look for ways to encourage TemplateData adoption, not to discourage it.