<p dir="auto">It seems like a common problem I am seeing developers new to ES struggling with is how to fit the pieces of the query DSL together. Returning more structured feedback about what the query DSL is expecting feels like it would help.</p>
<p dir="auto">Some examples from helping someone recently:</p>
<div class="highlight highlight-source-js notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="'filter' : {
  'not' : {
    'post_id' : [ 1, 2 ]
  }
},"><pre class="notranslate"><span class="pl-s">'filter'</span> : <span class="pl-kos">{</span>
  <span class="pl-s">'not'</span> : <span class="pl-kos">{</span>
    <span class="pl-s">'post_id'</span> : <span class="pl-kos">[</span> <span class="pl-c1">1</span><span class="pl-kos">,</span> <span class="pl-c1">2</span> <span class="pl-kos">]</span>
  <span class="pl-kos">}</span>
<span class="pl-kos">}</span><span class="pl-kos">,</span></pre></div>
<p dir="auto">Problem here is the NOT filter should have a filter inside of it rather than a field name</p>
<p dir="auto">If the error response could return the type of expected data at each level that would aid debugging. For example this could return:<br>
"filter": { "not" : "error: expects a filter" } }</p>
<p dir="auto">Another case:</p>
<div class="highlight highlight-source-js notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="'filter' : {
  'and' : {
    'terms' : {
      'post_type' : ['post']
    },
    'not' : {
      'terms' : {
        'post_id' : [1, 2]
      }
    }
  }
},"><pre class="notranslate"><span class="pl-s">'filter'</span> : <span class="pl-kos">{</span>
  <span class="pl-s">'and'</span> : <span class="pl-kos">{</span>
    <span class="pl-s">'terms'</span> : <span class="pl-kos">{</span>
      <span class="pl-s">'post_type'</span> : <span class="pl-kos">[</span><span class="pl-s">'post'</span><span class="pl-kos">]</span>
    <span class="pl-kos">}</span><span class="pl-kos">,</span>
    <span class="pl-s">'not'</span> : <span class="pl-kos">{</span>
      <span class="pl-s">'terms'</span> : <span class="pl-kos">{</span>
        <span class="pl-s">'post_id'</span> : <span class="pl-kos">[</span><span class="pl-c1">1</span><span class="pl-kos">,</span> <span class="pl-c1">2</span><span class="pl-kos">]</span>
      <span class="pl-kos">}</span>
    <span class="pl-kos">}</span>
  <span class="pl-kos">}</span>
<span class="pl-kos">}</span><span class="pl-kos">,</span></pre></div>
<p dir="auto">Error:<br>
"filter": { "and": "error: expects an array of filter objects" } }</p>
<p dir="auto">With more complex nesting:</p>
<div class="highlight highlight-source-js notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="'filter' : {
  'and' : [
    {
      'terms' : {
       'post_type' : ['post']
      }
    },
    {
      'not' : {
        'post_id' : [1,2]
      }
    }
  ]
}"><pre class="notranslate"><span class="pl-s">'filter'</span> : <span class="pl-kos">{</span>
  <span class="pl-s">'and'</span> : <span class="pl-kos">[</span>
    <span class="pl-kos">{</span>
      <span class="pl-s">'terms'</span> : <span class="pl-kos">{</span>
       <span class="pl-s">'post_type'</span> : <span class="pl-kos">[</span><span class="pl-s">'post'</span><span class="pl-kos">]</span>
      <span class="pl-kos">}</span>
    <span class="pl-kos">}</span><span class="pl-kos">,</span>
    <span class="pl-kos">{</span>
      <span class="pl-s">'not'</span> : <span class="pl-kos">{</span>
        <span class="pl-s">'post_id'</span> : <span class="pl-kos">[</span><span class="pl-c1">1</span><span class="pl-kos">,</span><span class="pl-c1">2</span><span class="pl-kos">]</span>
      <span class="pl-kos">}</span>
    <span class="pl-kos">}</span>
  <span class="pl-kos">]</span>
<span class="pl-kos">}</span></pre></div>
<p dir="auto">Error:<br>
"filter": { "and": [{"terms" : "ok"}, {"not" : "error: expects a filter"} } }</p>
<p dir="auto">Not entirely sure how feasible this is, or if there is better syntax or a more standard method for reporting such structured errors.</p>
<p dir="auto">Errors returned by the REST API are not easily human readable due to the way the data is stored in the <code class="notranslate">error</code> property.<br>
Eg. <a href="https://gist.github.com/missinglink/e3cb9b127ae00e8c561c">https://gist.github.com/missinglink/e3cb9b127ae00e8c561c</a></p>
<p dir="auto">You can 'prettify' the results, but it is still un-readable.<br>
Eg. <a href="https://gist.github.com/pecke01/5956684">https://gist.github.com/pecke01/5956684</a></p>
<p dir="auto">Note: (this specific error was caused by invalid syntax, the outer curly brackets were missing)</p>
<p dir="auto">This issue makes it difficult for beginners to understand syntax errors and for advanced users to debug quickly when they make silly errors.</p>
<p dir="auto">Ideally usage of <code class="notranslate">?pretty=1</code> would return "developer friendly" messages.</p>
<p dir="auto">Any thoughts / suggestions? Maybe there is a tool which may help?</p>