Comment Elasticsearch Mapping

If you have worked with large Elasticsearch mappings you may also have encountered the problem, that there is no possibility to comment your mapping or indexing template. Unfortunately the Elasticsearch mappings as well as the indexing templates are defined in JSON, which does not allow to add comments.

I thought the same, until I stumbled over Elasticsearch issue 1394 and the linked commit from January 2013, where a single line was added to the the configuration of the JSON factory:

jsonFactory.configure(JsonParser.Feature.ALLOW_COMMENTS, true);

Could it really be true? Are there comments supported in Elasticsearch mappings?

Elasticsearch uses the JSON parser from FasterXML. The supported features of the FasterXML JSON parser are documented on a wiki page on GitHub. On this page, the feature ALLOW_COMMENTS is described as follows:

ALLOW_COMMENTS (default: false) (for textual formats with concept of comments)
For textual formats that do not have official comments, but for which “de facto” conventions exist (like JSON), determines whether use of such unofficial comments is allowed or not
Supported for: JSON
For JSON: enabling the feature allows recognition and handling of “C comments” (/* … */) and “C++ comments” (// ….)

YES! Exactly what we where looking for. The commenting of Elasticsearch mappings does work well with some exceptions. Until now I found the following limitations:

1. Comments at the head of the JSON document, before the first opening {-bracket are not working
2. Single line comments with // only work at the end of the JSON document (after the closing })

But these limitations are minor and easily worked a round.

To make it easier for others to find out about the possibility to comment Elasticsearch mappings, I filed an issue #20513 on Github.

Example with comments from Elasticsearch documentation:

{
  /* mapping, used for all indices prefixed with "te" */
  "template": "te*",
  "settings": {
    /* only 1 shard is needed */
    "number_of_shards": 1
  },
  "mappings": {
    "type1": {
      "_source": {
        /* source not needed */
        "enabled": false
      },
      "properties": {
        "host_name": {
          "type": "string",
          /* host_name is used as filter, do not analyze */
          "index": "not_analyzed"
        },
        "created_at": {
          "type": "date",
          "format": "EEE MMM dd HH:mm:ss Z YYYY"
        }
      }
    }
  }
}