This document specifies the structure that TemplateData blobs must follow.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119).
## 2 Terminology
### 2.1 Template
A page on a MediaWiki website that can be transcluded into other pages. Refer to [mediawiki.org](https://www.mediawiki.org/wiki/Help:Templates) for documentation about what templates are capable of and how to create or use them.
### 2.2 Parameter
A key–value pair associated with the transclusion of a template in order to alter the behaviour of a template (and by extend, the content it will return as part of the transclusion).
### 2.3 Author
A program that creates and modifies TemplateData blobs, and distributes them to TemplateData consumer programs.
### 2.4 Consumer
A program interpreting TemplateData blobs (supplied by a TemplateData author).
### 2.5 User
A person using a TemplateData consumer program.
## 3 Structures
Authors MUST ensure TemplateData blobs have exactly one top-most structure of key–value pairs (hereafter referred to as "objects" having "properties") that follow the specification for the "Root" structure, as specified in section 3.1 below.
All objects share the following requirements:
1. Authors MUST ensure they only have properties described in this specification. Properties not specified here MUST not be present. Authors MUST ensure that properties and structures marked as "Required" are present. Other properties MAY be omitted.
2. Authors MUST ensure objects do not have multiple properties with the same key.
Requirements for non-Required ("optional") properties only apply if the property is present.
### 3.1 Root
#### 3.1.1 `description`
* Value: `null` or `InterfaceText`
#### 3.1.2 `params`
* Required
* Value: `Object`
Describes each of the template's parameters to a User.
Authors MUST ensure that the `params` object maps parameter names to `Param` objects.
#### 3.1.3 `paramOrder`
* Value: `Array`
The logical order of the parameters.
Authors MUST ensure the `paramOrder` array contains all parameter names exactly once.
Consumers SHOULD display the parameters in this order.
#### 3.1.4 `sets`
* Required
* Value: `Array`
List of groups of parameters that can be used together.
Authors MUST ensure that the `sets` object contains only `Set` objects. Authors MAY include a parameter in multiple `Set` objects. Authors are NOT REQUIRED to reference each parameter in at least one `Set` object.
A Consumer MAY encourage users to interact with parameters in a `Set` together (e.g. add, edit, or remove those parameters at once).
An object describing which parameter(s) specific Consumers SHOULD use for some purpose.
The `maps` property contains key–value pairs where the key identifies a given Consumer, and the value a `Map` object.
Consumers are NOT REQUIRED to have a corresponding `Map` object.
Consumers that look for a `Map` SHOULD publicly document their identifier key.
Authors MUST ensure that the `maps` object contains only `Map` objects. Authors MAY include a parameter in multiple `Map` objects. Authors are NOT REQUIRED to reference each parameter in at least one `Map` object.
* Default: Key of this `Param` object as referenced from `Root.params`.
Label of this parameter.
Authors are RECOMMENDED to provide unique labels for each parameter.
Consumers SHOULD use this when referring to a parameter in the interface for users.
#### 3.2.2 `description`
* Value: `null` or `InterfaceText`
Explanatory text describing the purpose of this parameter to a User.
Authors are RECOMMENDED to give each parameter a description. Authors MAY use include hints as to how to the format the parameter value.
For example, a template parameter called `name` might have as its description _"The name of the author of the book, to positively identify and attribute the claim. The name should be given as it would appear in the author's native language, script and culture."_.
Consumers SHOULD provide this description to a the User when selecting and altering parameter values.
#### 3.2.3 `required`
* Value: `boolean`
* Default: `false`
Whether the template being described requires this parameter to be present in order to function properly. For example, a template used to render a hyperlink to a book viewer might mark its "ISBN" parameter as required, whereas it might consider a parameter "publication date" to be optional.
Authors SHOULD only set this flag if the template will not function correctly without this parameter being set.
Consumers SHOULD encourage the User to fill in these parameters, and MAY prevent users from transcluding a template when a required parameter has not been set.
#### 3.2.4 `suggested`
* Value: `boolean`
* Default: `false`
Whether the parameter is recommended to be set to an explicit value for the template transclusion to be useful. This status is less strong an indicator than `required`. For example, in a book template the author's name might be `suggested`, whereas the title might be `required`.
Authors MUST NOT use `suggested` for parameters without which the template will not function correctly.
Consumers MAY encourage users to fill in a suggested parameter, but SHOULD NOT prevent users from transcluding a template when a suggested parameter is not set.
#### 3.2.5 `deprecated`
* Value: `boolean` or `string`
* Default: `false`
Whether this parameter is discouraged from usage. Seting to `false` indicates the parameter is not deprecated.
Authors are RECOMMENDED to, when marking a parameter as deprecated, provide a `string` of explanatory text describing why the parameter is deprecated (and what parameter or parameters the user should use instead). Alternatively, Authors MAY use the value `true` in absence of explanatory text.
#### 3.2.6 `aliases`
* Value: `Array`
An array of alternative names for the parameter.
Authors MUST NOT provide a `Param` object in `Root.params` for any alias. To describe a discouraged parameter with additional information, authors SHOULD describe the parameter as deprecated instead of alias.
Consumers SHOULD display aliases where entered as secondary to the primary name.
#### 3.2.7 `type`
* Value: `Type`
The kind of value the template expects to be associated with this parameter.
Consumers MAY provide user interfaces that restrict or simplify entering values based on the parameter type.
#### 3.2.8 `inherits`
* Value: `string`
The key of another parameter from which this parameter will inherit properites. Local properties will override the inherited properties.
Authors MUST ensure that the value matches the key of a `Param` object in `Root.params`.
#### 3.2.9 `autovalue`
* Value: `string`
A dynamically-generated default value in wikitext, such as today's date or the editing user's name; this will often involve wikitext substitution, such as `{{subst:CURRENTYEAR}}`.
Consumers MUST insert a parameter's autovalue by default if this parameter is used in a transclusion, and SHOULD indicate this value to the user and give them the opportunity to change the value.
Each key in a `Map` object can be arbitrary. The value must match a parameter name, a list of parameter names, or list containing lists of parameter names.
The key corresponds to the name of a Consumer variable that relates to the specified parameter(s).
