How complicated is it to create dependent parameters?

Adding new features to the param object specification is rather trivial. What's hard is to decide how exactly we want to model this. The syntax should be trivial, but flexible, and possibly even allow later enhancements (e.g. dependencies on more than one parameter).

"params": {
    "month": {
        "dependsOn": [
            {
                "params": [ "year" ],
                "dependency": "required"
            }
        ]
    },
    "date": {
        "dependsOn": [
            {
                "params": [ "year" ],
                "dependency": "exclusive"
            }
        ]
    }
}

This is a maximum proposal that is open for all kinds of enhancements (multiple dependencies, multiple parameters per dependency, other types of dependencies). We can simplify this when we are fine with limiting future enhancements.

"params": {
    "month": {
        "requires": "year"
    },
    "date": {
        "isExclusiveTo": "year"
    }
}

This allows a single dependency only, either requiring the other parameter, or being exclusive to each other.

How will this affect existing templates which have unmarked dependent parameters? How could this new feature be applied to existing templates?

I don't think there is a way to automate this, probably not even a way to point users at potential candidates. This needs to be done manually by the community.

Nothing bad should happen in the meantime. When the TemplateData blob for a template does not say anything about dependencies, all tools will continue to work as before.

How would this work for those editing TemplateData without the editor (ie. by writing JSON)?

Most probably by copy-pasting the relevant JSON snippet from documentation pages where the new feature is already mentioned.

[…] look for and collect any potential conflicts as they are discovered.

Potential conflicts with existing features:

• sets can conflict in several ways:
  • When a parameter outside of a set depends on one in a set, this works just fine. We can even ignore the fact that there is a set in this case.
  • A single parameter in a set depends on another parameter not in the same set. No matter if the dependency is inverted or not, we run into a conflict. When we hide the one direct dependency only, we leave an incomplete set, violating the sets specifications. When we hide the entire set, we assume all parameters in the set have the same dependency, even if this is not specified. Note that sets don't have a name. So this would be the only way to specify dependencies between sets.
  • Two parameters in a set depend on each other. No matter which one we hide, this leaves an incomplete set. Is this ok? The only other solution is to mark this as an error, and ignore it.
• required simply can not be used together with a dependency. No matter if the dependency is inverted or not, we can never hide a required parameter. This needs to be marked as an error.
• suggested is fine, I think. It's just a hint that doesn't do much. We would hide this parameter when the dependency is not met (assuming the dependency is stronger than the suggestion flag), but it would still show up in the wikitext (as an empty parameter).
• default will behave a little odd when there is a dependency. We will hide the parameter, but it will still show up with the default value. I think this is fine.
• The same applies to autovalue, I believe.
• inherits behaves like a pre-compiler statement and doesn't affect us in any way.
• paramOrder and maps should not cause conflicts, as far as I can see.
• Do we want to allow aliases to be used to specify dependencies? We should look up if paramOrder, sets, or maps accept aliases, and do the same.

My most relevant finding is, I believe, that it's fine to have both the existing sets feature and what we plan to add. It's even possible to combine the two in useful ways.

[…] how this would affect adding/deleting parameters in VE.

Since dependencies are kind of a secondary thing (templates and wizards still work fine without them, it's just inconvenient) I suggest to silently drop all dependencies that mention a deleted parameter name.

This is a great overview! I have a couple questions, particularly about the sets feature. I was not aware that this already existed and was in use. It seems like improving that would be the first starting point, and then figuring out how to add dependent parameters. I agree that they could work well together but we would have to consider the best way.

I looked into it and I've noticed that it's mentioned on the Extension page (where it also says "Note that the sets functionality is still in development.") but not on the help page, and it's definitely not included in the TemplateData editor. I'm not sure of the benefits of using it at the moment or how anyone would find out about it. I'm also not sure what in development means and if anyone is actively working on it already. Anything additional that we could learn about it would be helpful.

@awight Can we look the through the TemplateData here T258924 to see if anyone is using the sets feature?

In T258193#6367994, @ECohen_WMDE wrote:

@awight Can we look the through the TemplateData here T258924 to see if anyone is using the sets feature?

Done, results are pushed to gitlab: There are a handful on each wiki. It's possible to list the templates, if that's helpful?

Great! Thanks @awight. I see it in the code but not in the results? Maybe I'm just missing it. I'd be curious to see the list so that I can see how it's currently being used, like what types of parameters are being included in a set.

In T258193#6368208, @ECohen_WMDE wrote:

I see it in the code but not in the results?

Failure to click the "save" button, sorry! Pushed now.

I've also dumped the templates using "sets", slightly cleaned up from the raw output:
https://de.wikipedia.org/wiki/Vorlage:Tagesdifferenz
https://de.wikipedia.org/wiki/Vorlage:Analoguhr

https://en.wikipedia.org/wiki/Template:Infobox_U.S._legislation/doc
https://en.wikipedia.org/wiki/Template:WikiProject_Christianity
https://en.wikipedia.org/wiki/Template:Infobox_song_contest_entry
https://en.wikipedia.org/wiki/Template:Cite_patent
https://en.wikipedia.org/wiki/Template:WikiProject_Christianity/sandbox
https://en.wikipedia.org/wiki/Template:Cite_patent/sandbox
https://en.wikipedia.org/wiki/Template:Infobox_ESC_entry/sandbox
https://en.wikipedia.org/wiki/Template:Infobox_U.S._legislation/sandbox
https://en.wikipedia.org/wiki/Template:Makyen/sandbox/TemplateData/Example
https://en.wikipedia.org/wiki/Template:Krenair/ESCEntry-TD
https://en.wikipedia.org/wiki/Template:Infobox_song_contest_entry/sandbox

https://fa.wikipedia.org/wiki/%D8%A7%D9%84%DA%AF%D9%88:Infobox_U.S._legislation/%D8%AA%D9%85%D8%B1%DB%8C%D9%86
https://fa.wikipedia.org/wiki/%D8%A7%D9%84%DA%AF%D9%88:Citeref_patent/%D8%AA%D9%88%D8%B6%DB%8C%D8%AD%D8%A7%D8%AA

https://tr.wikipedia.org/wiki/%C5%9Eablon:Patent_kayna%C4%9F%C4%B1/belge

Thanks!

Note: Originally, my plan for today was to look into the sets feature, what it's state is, and if it's even implemented anywhere. Due to sickness I plan to do this on Monday.

State of sets

TemplateData (this includes the interactive TemplateData editor):

• sets are implemented. For example, using the templatedata API will always export a sets element. Defaults to an empty array when missing.
• sets are fully validated. It must be an array of objects. Each object must contain a label and a non-empty array of params. Both labels and params are validated further.
• sets are not rendered as part of the human-readable table. Same for maps, by the way.
• sets don't appear anywhere in the TemplateData editor.
• The specification we have now was rewritten in 2014. It's rather vague, unfortunately. For example, what if paramOrder and sets conflict?
• Here is the patch that implemented sets in 2013. Unfortunately not linked to anything.
• sets are already part of the extension in the very first commit in 2013.
• The mediawiki.org page mentions sets since 2013 as well.
• The "in development" note was added in 2014.

By the way:

• I noticed there is a specific precedence for the three deprecated (highest) → required → suggested (lowest) flags. E.g. deprecated overrides anything else. However, this is not enforced. You can totally have all three flags set. Consumers aren't told what to do then.
• There is validation for unknown elements in place. This means it's not possible to add new features without adding explicit support to the TemplateData code first.

MediaWiki-extensions-TemplateWizard:

• sets don't appear anywhere.

VisualEditor:

• sets are briefly mentioned in the model, but never used anywhere. Same for maps, by the way.
• All code mentioning sets was introduced in 2013 when template support was originally added to VisualEditor.

Conclusion

Considering all this, my assumption is that the sets feature was something that was drafted as "we think we are going to need this" by the VisualEditor team back then, but that simply never happened. Maybe @Krinkle or @Jdforrester-WMF are able to confirm this?

I believe we are free to pretty much ignore the sets feature. Well, we should not make a mess, e.g. not add new stuff that obviously conflicts or is redundant.

Just to make sure I understand correctly, sets are implemented in the data model but never used in the three official UIs, so are effectively meaningless? Do they show up in the "Manage TemplateData" editor?

Exactly. The editor is part of the TemplateData extension, so it was included in what I did above. I updated my comment to reflect this.

If I understand correctly, the primary motivation for this task is for VisualEditor to present, or "suggest", parameters that are related to each other all at once whenever any one of them come up. Presumably with the intention to make those parameters easier to discover for users and quicker to fill in.

I think dependent parameters, strictly speaking, would be a confusing and perhaps limiting way to accomplish that.

• End-user editors: Might be confusing since it seems the "dependent" concept likely results in either surprising/unpredictable behaviour, or in needing to confront and explain to the user what this means. There is in my opinion not enough information in such model to confidentally present these as a group in an intuitive way without making assumptions that may be false, and without our creative users using them for things outside the above motivation.
• Template maintainers: I believe that this basically requires that we limit sets to two params with only one being the entry point, or the template maintainer will have the repeat and duplicate information, which then also makes it difficult to expand in the future with none of the individual links in the dependency graph being a good place to add additional information.
• Software and UI design (for us): Would we have enough information to present this in an intuitive manner? I fear it might be too powerful, and thus leave us with very little signal in terms of what we can do with the information in the UI.

I think "Sets" covers this in a better way. For all three audiences. It's straight forward to express in TemplateData and allows for future expansion (e.g. labelling the sets and offering additional contextual guideance). It's easy to present to users. And gives us strong signals in the model to build on in the UI.

The most minimal and silent implemention could be to mostly remain as today, but to implicitly treat unused parameters in a used set as "suggested". In other words, if you'd open a template call in VE with parameter A set and there is a set (A,B,C) then we'd also add B and C in the sidebar, as if they were suggested. And likewise, if you go to add parameter X from the list of unused params and its in a set of (X,Y) then X and Y both get added to the form. This would be the most minimal, and explain nothing to the user.

Some future directions I can imagine:

• The Template editor dialog, could present these together when a user is going to add a parameter to a template call. E.g. the list of available parameters could also include these Sets. Whether to also list params separately is a UI decision. Perhaps omit them by default, unless there's an autocomplete match, with the Set sorting higher. Or perhaps omit them always.
• The sidebar and/or scrollable parameter form could visually group these together in their own section. (In case of overlapping sets, they would not grouped while ediing, and only used for suggesting/addding parameters together.) This visual grouping would take precedence over "paramOrder", but paramOrder would still apply to Parsoid's wikitext serialisation.

In any event, I agree there is potential to conflict between these, and that it would make sense not to add (yet) addditional things in this area.

While I think Sets or dependent params would be nice to have, I do think they're a relatively uncommo nneed.need. If there's resourcing available for improving template editing, there are other pending issues that are simpler and perhaps more impactful:

• T53375: TemplateData: Add parameter type for selecting one of predefined values (like "<select>" or ENUM)
• T55613: Create dedicated input methods for transclusion parameters (using "Param#type" from TemplateData)
  • T144155: Create dedicated input methods for "boolean" transclusion parameters
  • T52355: VisualEditor: Add support for editing templates' parameters as DOM elements ("visually"), including supporting nested templates

The idea is to specify inclusive as well as exclusive dependencies:

• We can say that parameter B is exclusive to parameter A. The moment A does have a value, you can't pick B any more, even if it was shown as a suggested parameter before. It will disappear. This raises indeed a lot of questions:
  • What if both have a value? How can the user access both when one is hidden? And if we display it, doesn't the dependency become pointless? We would need a new error state. One that says "there can't be a value" in contrast to the existing "there must be a value" a.k.a. "required".
  • When B is not suggested, it won't show up anyway, and can't disappear. The dependency would not have much of an effect, unless the user manually picked A and B. Does this mean a dependency needs to imply being suggested?
• We can say that B requires A. B is not shown as long as A doesn't have a value. Again:
  • What to do when an existing template does have a value for B, but not A, violating the dependency? Show this in red, as if A is required, even if it isn't?
  • What if the user wants to start with B, even if A is missing? Do we allow the user to manually pick B?
  • Should B automatically show up the moment A has a value? When B is suggested, sure. But what if not? What's the point of the dependency then? Does this mean such a dependency implies being suggested?

In both cases we can indeed ask if it's helpful to invest time on a feature that doesn't do much more than blocking users from doing something?

Coming from this direction I can absolutely follow the arguments from @Krinkle. Super helpful additional analysis, thanks! However, we would need work a lot on the sets specification. For example: Should a set act as if all parameters in a set are suggested? Or only if at least 1 is suggested? Should a set override the order? How is the position calculated if there are many possibilities? Based on the 1st parameter in the set? Based on whichever parameter from the set appears 1st in the order? What if a parameter appears in 2 sets? What if a deprecated parameter is in a set?

Thanks for the links to the additional tickets. I think we have them in mind as part of our ongoing WMDE-Templates-FocusArea.