<p dir="auto">Contrast: <a href="https://github.com/elastic/elasticsearch/blob/master/rest-api-spec/api/search.json#L160-L162">https://github.com/elastic/elasticsearch/blob/master/rest-api-spec/api/search.json#L160-L162</a></p>
<p dir="auto">with (admittedly incomplete but not more so than your spec)</p>
<p dir="auto"><a href="https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L536-L544">https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L536-L544</a></p>
<p dir="auto"><a href="https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L601-L629">https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L601-L629</a></p>
<p dir="auto"><a href="https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L823-L832">https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L823-L832</a></p>
<p dir="auto"><a href="https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L1729-L1742">https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L1729-L1742</a></p>
<p dir="auto">People are using Bloodhound in production.</p>
<p dir="auto">I would suggest that a more complete spec is needed to assist client library authors, but I know how annoying maintaining documentation is. Given that, consider that Bloodhound (which has tests) can be tested against Elasticsearch to ensure spec correctness. Have you considered making an explicit spec via a client library in a language with explicit datatypes that was high enough level to make it usable for a casual reader?</p>
<p dir="auto">Part of what exacerbates the situation with the spec is that your docs do <em>not</em> show complete or working examples, they show fragments of the complete JSON document that would be required to work, the reader is expected to</p>
<ol dir="auto">
<li>Know this</li>
<li>Manually inject the fragment you're showing them into the rest of the structure which is not well explained or connected to the individual doc page they're on</li>
</ol>
<p dir="auto">The problems with 1 and 2 are compounded by the fact that it's <em>extremely</em> easy to get the JSON structure wrong, then you are now faced with the prospect of making fiddly little changes to the JSON over and over until works.</p>
<p dir="auto">Thus, <a href="https://github.com/bitemyapp/bloodhound/blob/master/src/Database/Bloodhound/Types.hs#L1745-L1758">datatypes that take care of the JSON for you</a>.</p>
<p dir="auto">The <em>primary</em> complaints I hear from people about Elasticsearch are the docs &amp; API. It makes what is otherwise a very useful product considerably more frustrating to use than it needs to be.</p>
<p dir="auto">Requests/queries/etc currently have custom parsers, which make it more difficult to be certain that they are error free.  We should replace all this hand parsing with some form of grammar, which defines exactly what syntax is allowed. This will also benefit those implementing clients, as they will have a grammar that can be interrogated programmatically.</p>
<p dir="auto">Any unknown parameters should throw a parsing exception.</p>
<p dir="auto">We can add custom rules where needed (eg to disallow certain combinations of parameters like using <code class="notranslate">fuzzy</code> in the <code class="notranslate">multi_match</code> query with type <code class="notranslate">cross_fields</code>).</p>