[PROPOSAL] Published (documentation) sample templates should be in both YAML and JSON

[dbwiddis]

What/Why

What are you proposing?

In our testing, demos, and documentation, we should ensure both YAML and JSON formats are equally supported.

What problems are you trying to solve?

JSON is designed for efficient machine data interchange and intentionally does not permit comments. The best workaround is creating a data field named comment (or similar). These may still not be obvious to readers and do not benefit from spacing, paragraphs, punctuation, etc. In addition, the "pretty" format wastes a lot of vertical space with closing brackets.

YAML is much more human-readable. Most importantly, it permits very verbose and flexibly-formatted comments. It makes more use of vertical space, using indentation for grouping rather than an endless stream of closing curly braces.

What is the developer experience going to be?

Templates are part of the REST API, the only difference will be the content-type specification will be application/x-yaml or text/yaml. Since both JSON and YAML (as well as CBOR and SMILE) are supported by OpenSearch, no additional work is required in the plugin implementation; this is primarily a documentation thing.

Are there any breaking changes to the API

I don't think so, but we should make sure our integration testing framework thoroughly tests both formats.

What is the user experience going to be?

Users can choose YAML or JSON at their preference. YAML will have a lot more comments in the template.

Why should it be built? Any reason not to?

Because comments are good.

What will it take to execute?

It's already supported in the code. It will take a bit of extra effort in testing and documentation to make sure the options are known.

[dbwiddis]

Marking this complete with #296 and #311