diff --git a/Specification.md b/Specification.md
new file mode 100644
index 00000000..e785ad2f
--- /dev/null
+++ b/Specification.md
@@ -0,0 +1,288 @@
+# TemplateData Specification
+
+## Living Standard
+
+<dl>
+  <dt>This version</dt>
+  <dd><a href="https://git.wikimedia.org/blob/mediawiki%2Fextensions%2FTemplateData/master/Specification.md">https://git.wikimedia.org/blob/mediawiki%2Fextensions%2FTemplateData/master/Specification.md</a></dd>
+  <dt>Editors</dt>
+  <dd>Timo Tijhof, Trevor Parscal, James D. Forrester</dd>
+</dl>
+
+***
+
+## 1 Introduction
+
+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).
+
+### 3.2 Param
+* Value: `Object`
+
+#### 3.2.1 `label`
+* Value: `null` or `InterfaceText`
+* 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.
+
+#### 3.2.10 `default`
+* Value: `string`
+
+The default value in wikitext (or description thereof) of a parameter as assumed by the template when the parameter is not present in a transclusion.
+
+Consumers SHOULD indicate this default value to the user when inserting or editing a template.
+
+### 3.3 Set
+* Value: `Object`
+
+#### 3.3.1 label
+* Required
+* Value: `InterfaceText`
+
+A label for this set.
+
+Authors are RECOMMENDED to ensure these are unique and distinguishable from other labels.
+
+#### 3.3.2 params
+* Required
+* Value: `Array`
+
+A list of one or more `Root.params` keys.
+
+### 3.4 Type
+* Value: `string`
+* Default: `"unknown"`
+
+One of the following:
+
+- `unknown`<br>
+  When no type is specified.
+- `string`<br>
+  Any textual value.
+- `number`<br>
+  Any numerical value (without decimal points or thousand separators).
+- `boolean`<br>
+  A boolean value ('1' for true, '0' for false, '' for unknown).
+- `date`<br>
+  A date in ISO 8601 format, e.g. "2014-05-09" or "2014-05-09T16:01:12Z".
+- `wiki-page-name`<br>
+  A valid MediaWiki page name for the current wiki. Doesn't have to exist,
+  but if not, should be a valid page name to create.
+- `wiki-user-name`<br>
+  A valid MediaWiki user name for the current wiki. Doesn't have to exist,
+  but if not, should be a valid user name to create. Should not include any
+  localised or standard namespace prefix ("Foo" not "User:Foo").
+- `wiki-file-name`<br>
+  A valid MediaWiki file name for the current wiki. Doesn't have to exist,
+  but if not, should be a valid file name to upload. Should not include any
+  localised or standard namespace prefix ("Foo" not "File:Foo").
+- `content`<br>
+  Page content (such as text style, links and images etc.).
+- `unbalanced-wikitext`<br>
+  Raw wikitext that should not be treated as standalone content because it
+  is unbalanced (eg. templates concatenating incomplete wikitext as a bigger
+  whole such as `{{echo|before=<u>|after=</u>}}`)
+- `line`<br>
+  Short text field - use for names, labels, and other short-form fields.
+
+### 3.5 InterfaceText
+* Value: `string` or `Object`
+
+A free-form string (no wikitext) in the content-language of the wiki, or,
+an object containing those strings keyed by language code.
+
+## 4 Examples
+
+### 4.1 The "Unsigned" template
+
+<pre lang="json">
+{
+	"description": "Label unsigned comments in a conversation.",
+	"params": {
+		"user": {
+			"label": "User's name",
+			"type": "wiki-user-name",
+			"required": true,
+			"description": "User name of person who forgot to sign their comment.",
+			"aliases": ["1"]
+		},
+		"date": {
+			"label": "Date",
+			"suggested": true,
+			"description": {
+				"en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
+			},
+			"aliases": ["2"],
+			"autovalue": "{{subst:#time:Y-m-d}}"
+		},
+		"year": {
+			"label": "Year",
+			"type": "number"
+		},
+		"month": {
+			"label": "Month",
+			"inherits": "year"
+		},
+		"day": {
+			"label": "Day",
+			"inherits": "year"
+		},
+		"comment": {
+			"required": false
+		}
+	},
+	"sets": [
+		{
+			"label": "Date",
+			"params": ["year", "month", "day"]
+		}
+	]
+}
+</pre>
+
+Example transclusions
+<pre>
+{{unsigned|JohnDoe|2012-10-18}}
+
+{{unsigned|user=JohnDoe|year=2012|month=10|day=18|comment=blabla}}
+</pre>
diff --git a/spec.templatedata.txt b/spec.templatedata.txt
deleted file mode 100644
index 6d46f703..00000000
--- a/spec.templatedata.txt
+++ /dev/null
@@ -1,161 +0,0 @@
-/*
-	Specification for the JSON descriptor as used in the
-	TemplateData extension for MediaWiki.
-
-	Author: Timo Tijhof
-	Author: Trevor Parscal
-	Author: James D. Forrester
-
-	Property names listed in brackets (e.g. [foo]) are optional. This means
-	they may be omitted from the object. If a null value is allowed, this will
-	be explicitly specified.
-
-@structure {Object} Root
-	@property {null|InterfaceText} [description]
-	@property {Object} params Contains all parameters.
-	 Keyed by parameter name, contains #Param objects.
-	@property {Array} [paramOrder] The logical order in which parameters should be
-	 displayed. The array contains each parameter key exactly once.
-	@property {Array} sets List of groups of parameters that should be used
-	 together. A parameter can be in multiple sets. Not every parameter has to be
-	 in a set. The array contains #Set objects.
-
-@structure {Object} Param
-	@property {null|InterfaceText} [label] Label of this parameter.
-	 To be shown as a clear identifier for human users of the template; should
-	 generally be unique amongst the parameters (e.g. "First author's name" and
-	 "Second author's name", not just "Name" and "Name"). Defaults to the key of
-	 the object in `Root.params`.
-	@property {boolean} [required=false] Required status of this parameter.
-	 Whether the parameter is required to have an explicit value for the template
-	 to function properly. For example, the ISBN parameter in a template about a
-	 book's ISBN might be required, whereas other parameters such as issue date
-	 might not be. Client tools SHOULD automatically prompt users to fill in these
-	 paramters, and MAY prevent them from adding a template invocation with a
-	 required parameter unset.
-	@property {boolean} [suggested=false] Suggested status of this parameter.
-	 Whether the parameter is suggested to be set to an explicit value for the
-	 template to be valuable. This status is a less strong indicator of inclusion
-	 than `required`, and the template should function correctly without a
-	 `suggested` parameter being set. For example, in a book template the author's
-	 name might be suggested, whereas the title might be required. Client tools
-	 MAY automatically prompt users to fill in these paramters, but SHOULD NOT
-	 prevent users from adding a template invocation with a suggested parameter
-	 unset.
-	@property {null|InterfaceText} [description] Description of this parameter.
-	 To be shown as an explanatory text for what the purpose of the parameter is
-	 and some minor hints as to how to the format the contents. For example, a
-	 template parameter about the author of a book might be "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." or similar.
-	@property {boolean|string} [deprecated=false] Deprecated status of this parameter.
-	 Description for why a parameter is deprecated, and what tasks instead should
-	 be set, or "true" if no description is wanted to be set.
-	@property {Array} [aliases] List of aliases.
-	 An alias is an alternative name for the parameter that may be used instead of
-	 (not in addition to) the primary name. Aliases are not documented in a
-	 separate Param object. If they need more information, they should be in their
-	 own property marked "deprecated".
-	@property {string} [default] The default value or description thereof.
-	@property {Type} [type] The type of the expected parameter value.
-	@property {string} [inherits] Key to another object in `Root.params`.
-	 The current Param object will inherit from that one, with local properties
-	 overriding the inherited ones.
-	@property {Type} [autovalue] A dynamically generated default value such as today's
-	 date or the editing user's name. Should generally involve substitution,
-	 such as {{subst:CURRENTMONTHNAME}}.
-
-@structure {Object} Set
-	@property {InterfaceText} label Label of this set.
-	@property {Array} params One or more parameter keys.
-
-@structure {string} Type
-	One of the following:
-	- unknown
-	  When no type is specified.
-	- string
-	  Any textual value.
-	- number
-	  Any numerical value (without decimal points or thousand separators).
-	- boolean
-	  A boolean value ('1' for true, '0' for false, '' for unknown).
-	- date
-	  A date in ISO 8601 format, e.g. "2014-05-09" or "2014-05-09T16:01:12Z".
-	- wiki-page-name
-	  A valid MediaWiki page name for the current wiki. Doesn't have to exist,
-	  but if not, should be a valid page name to create.
-	- wiki-user-name
-	  A valid MediaWiki user name for the current wiki. Doesn't have to exist,
-	  but if not, should be a valid user name to create. Should not include any
-	  localised or standard namespace prefix ("Foo" not "User:Foo").
-	- wiki-file-name
-	  A valid MediaWiki file name for the current wiki. Doesn't have to exist,
-	  but if not, should be a valid file name to upload. Should not include any
-	  localised or standard namespace prefix ("Foo" not "File:Foo").
-	- content
-	  Page content (such as text style, links and images etc.).
-	- unbalanced-wikitext
-	  Raw wikitext that should not be treated as standalone content because it
-	  is unbalanced (eg. templates concatenating incomplete wikitext as a bigger
-	  whole such as {{echo|before=<u>|after=</u>}})
-	- line
-	  Short text field - use for names, labels, and other short-form fields.
-
-@structure {string|Object} InterfaceText
-	A free-form string (no wikitext) in the content-language of the wiki, or,
-	an object containing those strings keyed by language code.
-
-
-	Examples:
- */
-
-/**
- * [[Template:Unsigned]]
- *
- * Example usage:
- *     {{unsigned|JohnDoe|2012-10-18}}
- *     {{unsigned|user=JohnDoe|year=2012|month=10|day=18|comment=blabla}}
- */
-{
-	"description": "Label unsigned comments in a conversation.",
-	"params": {
-		"user": {
-			"label": "User's name",
-			"type": "wiki-user-name",
-			"required": true,
-			"description": "User name of person who forgot to sign their comment.",
-			"aliases": ["1"]
-		},
-		"date": {
-			"label": "Date",
-			"suggested": true,
-			"description": {
-				"en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
-			},
-			"aliases": ["2"],
-			"autovalue": '{{subst:#time:Y-m-d}}'
-		},
-		"year": {
-			"label": "Year",
-			"type": "number"
-		},
-		"month": {
-			"label": "Month",
-			"inherits": "year"
-		},
-		"day": {
-			"label": "Day",
-			"inherits": "year"
-		},
-		"comment": {
-			"required": false
-		}
-	},
-	"sets": [
-		{
-			"label": "Date",
-			"params": ["year", "month", "day"]
-		}
-	]
-}