User:Kephir/gadgets/rater/data-format

The following description is incomplete.

The next version of Rater shall only recognise templates based on Module:WikiProjectBanner, parsing their source code directly, and therefore making data pages obsolete. Please do not become too attached to them.

The WikiProject template data for Rater is a JSON object. It is kept on pages with a name of the form Template:name/rater-data.js. JSON is an abstract data format based on JavaScript, supporting basic data types like strings, numbers, logical values, lists and key-value associations.

JSON

In brief:

Strings: Strings of Unicode characters may be enclosed within either apostrophes (') or plain double quotes ("). Double quotes are recommended, because apostrophes can be embedded in them without problems. (otherwise they need to be prefixed with \)
Objects: Objects represent key-value associations. An object starts with a { character, contains zero or more key: value pairs separated by commas (,) and ends with a }. A value can be of any JSON-supported type, but a key is always a string.
Arrays: An array is an ordered list of JSON values of any type. An array starts with [, contains zero or more values separated by commas, and ends with ].
Booleans: There are two Boolean values: true and false.
Null: JSON also has a unit type, whose only value is null.

JSON can also describe numbers, but they were omitted from above, as Rater does not use numbers as values in its data.

Whitespace characters (spaces, tabs and newlines) may be put anywhere and will be ignored (except inside a string or a token like true, false or null.)

Warning: Pay attention to punctuation. A comma or a colon in a wrong place may make Rater reject the data and fall back to defaults, which is probably undesired. Rater will show an alert box when this is the case.

Template data

Template data is an object in which the following keys may appear:

"name"

A string containing the WikiProject name. The default value is obtained by stripping "WikiProject " from the front of the template name, if present.

"params"

An object whose keys are template parameter names and values are described below. There is a predefined default parameter set, but it may not work, so putting it in is recommended. The default parameters are inherited from the default set even if this key is present; to explicitly mark a parameter as unavailable, set a value for its key to null.

"taskforces"

Specifies project task forces (also called work groups, sometimes they are independent WikiProjects).

Task forces can be specified either with an object or with an array. When specified with an array, the array consists of objects having the following keys:

"desc": A string containing the task force name.
"part" used: A string containing the name of a parameter, which when set to "yes" indicates that the page is covered by the task force. When omitted, it is assumed that the task force always covers the page covered by the WikiProject.
"prio": A string containing the name of a parameter, which may contain priority for the workgroup. When omitted, it is assumed that the task force does not rate priority.

When taskforces are specified with an object, the keys are as follows:

"items": An object mapping parameter name prefixes to task force names.
"partsuf": A suffix, which when combined with a prefix which is a key in an object inside "items" gives the name of a parameter indicating whether an article is covered by the task force. Typical values are "" (no suffix), "-task-force" and "-work-group".
"priosuf": A suffix, which when combined with a prefix which is a key in an object inside "items" gives the name of a parameter specifying priority within the task force. Usually this value is "-importance" or "-priority". If this key is omitted or null, it means there are no priority parameters.

Specifying task forces with an object is recommended when task force parameter names all follow the same pattern.

Parameter data

A parameter datum is an object whose keys may be the following:

"desc"

A string containing parameter description. It will be used as a label for the parameter-changing control.

"mandatory"

true if the parameter is mandatory. It will appear in the interface even if absent from the invocation.

"obsolete"

true if the parameter is obsolete. Currently it means it is greyed out when present and not offered to be added when absent.

"alias"

A string containing the parameter for which the currently defined one is an alias. If the key is absent, the parameter is not an alias.

"helplink"

Specifies a page within Wikipedia explaining how to fill this parameter.

"implies"

Has no effect.

"shell"

Has no effect.

"group"

A string defining that a parameter belongs to a particular group. Available groups are:

"req": Requests
"vis": Appearance
"misc": Miscellaneous

The default is the main group, appearing right after the WikiProject name in the interface.

"values"

May be a string or an object. String values can be one of the following:

"flag-perm" — either yes or no. The interface will be a checkbox.
"flag-temp" — parameter either contains yes or is absent. The interface will be a checkbox; when unchecked, the parameter will disappear.
"string" — the default; the interface will be a box allowing free-form input.
"importance-std" — standard importance scale: Top, High, Mid, Low, Bottom, NA. The interface will be a drop-down list (HTML select element).
"class-std" — standard quality scale: FL, List, FA, A, GA, B, C, Start, Stub, NA. The interface will be a drop-down list.
"class-ext" — extended quality scale: FL, List, FA, A, GA, B, C, Start, Stub, NA, Category, Disambig, File, Portal, Project, Template. The interface will be a drop-down list.

When an object, it shall have the following keys:

"normalise": When this equals "mlc", the value in the template is compared case-insensitively to the list of allowed values and considered equivalent to the first match. When it is "lc", the value is folded to lowercase.
"list": List of allowable values. Can be either an array or an object. When an object, the keys are the actual values used in the template, and the values are labels shown, which may be different and more explanatory.

Examples

Data for WikiProject Mathematics

{
	"name": "Mathematics",
	"params": {
		"importance": {
			"alias": "priority"
		},
		"priority": {
			"desc": "Priority",
			"mandatory": true,
			"values": "importance-std"
		},
		"historical": {
			"desc": "Historical",
			"values": "flag-temp"
		},
		"field": {
			"desc": "Field",
			"mandatory": true,
			"values": {
				"list": {
					"": "Unknown",
					"general": "General",
					"basics": "Basics",
					"analysis": "Analysis",
					"algebra": "Algebra",
					"geometry": "Geometry",
					"applied": "Applied mathematics",
					"probability": "Probability and statistics",
					"number theory": "Number theory",
					"discrete": "Discrete mathematics",
					"foundations": "Foundations, logic and set theory",
					"mathematical physics": "Mathematical physics",
					"topology": "Topology",
					"history": "History of mathematics",
					"mathematicians": "Mathematicians"
				},
				"aliases": {
					"mathematician": "mathematicians",
					"logic": "foundations",
					"set theory": "foundations",
					"foundations, logic and set theory": "foundations",
					"applied mathematics": "applied",
					"statistics": "probability",
					"probability and statistics": "probability"
				},
				"normalise": "lc"
			}
		},
		"frequentlyviewed": {
			"desc": "Frequently viewed",
			"values": "flag-temp",
			"group": "misc"
		}
	}
}

Data for WikiProject Biography

{
	"params": {
		"importance": null,
		"listas": {
			"mandatory": true,
			"helplink": "WP:NAMESORT"
		},
		"living": {
			"desc": "Living person",
			"values": "flag-perm",
			"mandatory": true,
			"shell": "blp"
		},
		"activepol": {
			"desc": "Active politician",
			"values": "flag-temp",
			"mandatory": false,
			"implies": "living",
			"shell": "activepol"
		},
		"blpo": {
			"desc": "Covers other people under BLP",
			"values": "flag-temp",
			"mandatory": false,
			"shell": "blpo"
		},
		"core": {
			"desc": "Core biography",
			"values": "flag-perm",
			"mandatory": false
		},
		"needs-image": null,
		"needs-photo": {
			"group": "req",
			"desc": "Photograph",
			"values": "flag-temp",
			"alias": null
		},
		"needs-discography": {
			"group": "req",
			"desc": "Discography",
			"values": "flag-temp",
			"implies": "musician-work-group"
		},
		"needs-filmography": {
			"group": "req",
			"desc": "Filmography",
			"values": "flag-temp",
			"implies": "filmbio-work-group"
		},
		"past-collaboration": {
			"group": "misc",
			"desc": "At Collaboration department",
			"values": "date"
		},
		"peer-review": {
			"group": "misc",
			"desc": "Current peer review",
			"values": "flag-temp"
		},
		"old-peer-review": {
			"group": "misc",
			"desc": "Had peer review",
			"values": "flag-perm"
		},
		"A-Class": {
			"group": "misc",
			"desc": "A-Class review",
			"values": {
				"list": {
					"pass": "Passed",
					"fail": "Failed"
				},
				"normalise": "mlc"
			}
		}
	},
	"taskforces": {
		"priosuf": "-priority",
		"partsuf": "-work-group",
		"items": {
			"a\u0026e": "Arts and entertainment",
			"filmbio": "Film",
			"military": "Military",
			"musician": "Musician",
			"peerage": "Peerage",
			"politician": "Politician",
			"royalty": "Royalty",
			"s\u0026a": "Science and academia",
			"sports": "Sports"
		}
	}
}

Default data

{
	"params": {
		"class": {
			"desc": "Quality",
			"values": "class-std",
			"mandatory": true
		},
		"importance": {
			"desc": "Priority",
			"values": "importance-std",
			"mandatory": true
		},
		"auto": {
			"desc": "Auto-rated",
			"values": "flag-temp"
		},
		"listas": {
			"desc": "List as",
			"values": "listas"
		},
		"vital": {
			"desc": "Vital",
			"values": "flag-temp"
		},
		"small": {
			"desc": "Small box",
			"group": "vis",
			"values": "flag-temp"
		},
		"nested": {
			"desc": "Nested template",
			"group": "vis",
			"values": "flag-temp",
			"obsolete": true
		},
		"attention": {
			"desc": "Immediate attention",
			"group": "req",
			"values": "flag-temp"
		},
		"needs-image": {
			"desc": "Image",
			"group": "req",
			"values": "flag-temp"
		},
		"needs-photo": {
			"alias": "needs-image"
		},
		"needs-infobox": {
			"desc": "Infobox",
			"group": "req",
			"values": "flag-temp"
		},
		"category": {
			"desc": "Decorative",
			"group": "vis",
			"values": "flag-inv"
		}
	}
}