@@ -115,6 +115,10 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=mappings]
115115
116116include::{docdir}/rest-api/common-parms.asciidoc[tag=settings]
117117
118+ `version`::
119+ (Optional, integer)
120+ Version number used to manage index templates externally.
121+ This number is not automatically generated by {es}.
118122
119123
120124[[put-index-template-api-example]]
@@ -197,3 +201,56 @@ order templates, with lower order templates providing the basis.
197201
198202NOTE: Multiple matching templates with the same order value will
199203result in a non-deterministic merging order.
204+
205+
206+ [[versioning-templates]]
207+ ===== Template versioning
208+
209+ You can use the `version` parameter
210+ to add an optional version number to an index template.
211+ External systems can use these version numbers
212+ to simplify template management.
213+
214+ The `version` parameter is completely optional
215+ and not automatically generated by {es}.
216+
217+ To unset a `version`,
218+ replace the template without specifying one.
219+
220+ [source,js]
221+ --------------------------------------------------
222+ PUT /_template/template_1
223+ {
224+ "index_patterns" : ["*"],
225+ "order" : 0,
226+ "settings" : {
227+ "number_of_shards" : 1
228+ },
229+ "version": 123
230+ }
231+ --------------------------------------------------
232+ // CONSOLE
233+
234+ To check the `version`,
235+ you can use the <<indices-get-template, get index template>> API
236+ with the <<common-options-response-filtering, `filter_path`>> query parameter
237+ to return only the version number:
238+
239+ [source,js]
240+ --------------------------------------------------
241+ GET /_template/template_1?filter_path=*.version
242+ --------------------------------------------------
243+ // CONSOLE
244+ // TEST[continued]
245+
246+ The API returns the following response:
247+
248+ [source,js]
249+ --------------------------------------------------
250+ {
251+ "template_1" : {
252+ "version" : 123
253+ }
254+ }
255+ --------------------------------------------------
256+ // TESTRESPONSE
0 commit comments