TC 2024-06-26

docs/odata-url-conventions/odata-url-conventions.html

@@ -992,24 +992,26 @@ <h2 id="417-passing-query-options-in-the-request-body"><a name="PassingQueryOpti
 <p>An easier alternative for <code>GET</code> requests is to append <code>/$query</code> to the resource path of the URL, use the <code>POST</code> verb instead of <code>GET</code>, and pass the query options part of the URL in the request body.</p>
 <p>Requests to paths ending in <code>/$query</code> MUST use the <code>POST</code> verb. Query options specified in the request body and query options specified in the request URL are processed together.</p>
 <p>The request body MUST use <code>Content-Type: text/plain</code> or <code>Content-Type: application/x-www-form-urlencoded</code>.</p>
-<p>For <code>Content-Type: text/plain</code>, the individual query options MUST be separated by <code>&amp;</code> or newlines and MUST use the same percent-encoding as in URLs (especially: no spaces, tabs, or line breaks allowed) and MUST follow the syntax rules described in <a href="#QueryOptions">chapter 5</a>.</p>
+<p>For <code>Content-Type: text/plain</code>, the individual query options MUST be separated by <code>&amp;</code> and MUST use the same percent-encoding as in URLs (especially: no spaces, tabs, or line breaks allowed) and MUST follow the syntax rules described in <a href="#QueryOptions">chapter 5</a>.</p>
 <div class="example">
-<p>Example 50: passing a filter condition in the request body</p>
+<p>Example <a name="postquery" href="#postquery">50</a></p>
 <pre><code>POST http://host/service/People/$query
 Content-Type: text/plain
 
-$filter=[FirstName,LastName]%20in%20[[&quot;John&quot;,&quot;Doe&quot;],[&quot;Jane&quot;,&quot;Smith&quot;]]</code></pre>
+$filter=LastName%20eq%20&#39;P%26G&#39;&amp;$select=FirstName,LastName</code></pre>
 <p>This POST request would result from submitting the HTML form</p>
 <div class="sourceCode" id="cb71"><pre class="sourceCode html"><code class="sourceCode html"><span id="cb71-1"><a href="#cb71-1" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;</span><span class="kw">form</span><span class="ot"> method</span><span class="op">=</span><span class="st">&quot;post&quot;</span><span class="ot"> action</span><span class="op">=</span><span class="st">&quot;http://host/service/People/$query&quot;</span></span>
 <span id="cb71-2"><a href="#cb71-2" aria-hidden="true" tabindex="-1"></a><span class="ot">      enctype</span><span class="op">=</span><span class="st">&quot;text/plain&quot;</span><span class="dt">&gt;</span></span>
-<span id="cb71-3"><a href="#cb71-3" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&lt;</span><span class="kw">input</span><span class="ot"> name</span><span class="op">=</span><span class="st">&quot;$filter&quot;</span></span>
-<span id="cb71-4"><a href="#cb71-4" aria-hidden="true" tabindex="-1"></a><span class="ot">    value</span><span class="op">=</span><span class="st">&#39;[FirstName,LastName]%20in%20[[&quot;John&quot;,&quot;Doe&quot;],[&quot;Jane&quot;,&quot;Smith&quot;]]&#39;</span><span class="dt">&gt;</span></span>
-<span id="cb71-5"><a href="#cb71-5" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">form</span><span class="dt">&gt;</span></span></code></pre></div>
+<span id="cb71-3"><a href="#cb71-3" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&lt;</span><span class="kw">input</span><span class="ot"> name</span><span class="op">=</span><span class="st">&quot;$filter&quot;</span><span class="ot"> value</span><span class="op">=</span><span class="st">&quot;LastName%20eq%20&#39;P%26G&#39;&quot;</span><span class="dt">&gt;</span></span>
+<span id="cb71-4"><a href="#cb71-4" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&lt;</span><span class="kw">input</span><span class="ot"> name</span><span class="op">=</span><span class="st">&quot;$select&quot;</span><span class="ot"> value</span><span class="op">=</span><span class="st">&quot;FirstName,LastName&quot;</span><span class="dt">&gt;</span></span>
+<span id="cb71-5"><a href="#cb71-5" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">form</span><span class="dt">&gt;</span></span>
+<span id="cb71-6"><a href="#cb71-6" aria-hidden="true" tabindex="-1"></a>in which spaces and ampersands must be percent-encoded, because `text/plain`</span>
+<span id="cb71-7"><a href="#cb71-7" aria-hidden="true" tabindex="-1"></a>forms perform no such encoding.</span></code></pre></div>
 </div>
 <p>For <code>Content-Type: application/x-www-form-urlencoded</code>, the request body MUST be suitable <em>input</em> for the <a href="https://url.spec.whatwg.org/#urlencoded-parsing"><code>application/x-www-form-urlencoded</code> parser</a> in the <a href="#_url">URL Living Standard</a>, section 5.1 such that the <em>output</em> of the parsing steps is the list of name/value pairs for the individual query options.</p>
 <p>To guarantee this, clients are advised to make the request body the value of <em>output</em> after running the <a href="https://url.spec.whatwg.org/#concept-urlencoded-serializer"><code>application/x-www-form-urlencoded</code> serializer</a> in the <a href="#_url">URL Living Standard</a>, section 5.2 with <em>tuples</em> being the list of name/value pairs for the individual query options.</p>
 <div class="example">
-<p>Example 51: passing multiple system query options in the request body</p>
+<p>Example 51: The same request as in <a href="#postquery">example 50</a> with <code>application/x-www-form-urlencoded</code> encoding (note the differences in encoding):</p>
 <pre><code>POST http://host/service/People/$query
 Content-Type: application/x-www-form-urlencoded
 
@@ -1020,9 +1022,7 @@ <h2 id="417-passing-query-options-in-the-request-body"><a name="PassingQueryOpti
 <span id="cb73-3"><a href="#cb73-3" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&lt;</span><span class="kw">input</span><span class="ot"> name</span><span class="op">=</span><span class="st">&quot;$filter&quot;</span><span class="ot"> value</span><span class="op">=</span><span class="st">&quot;LastName eq &#39;P</span><span class="er">&amp;</span><span class="st">G&#39;&quot;</span><span class="dt">&gt;</span></span>
 <span id="cb73-4"><a href="#cb73-4" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&lt;</span><span class="kw">input</span><span class="ot"> name</span><span class="op">=</span><span class="st">&quot;$select&quot;</span><span class="ot"> value</span><span class="op">=</span><span class="st">&quot;FirstName,LastName&quot;</span><span class="dt">&gt;</span></span>
 <span id="cb73-5"><a href="#cb73-5" aria-hidden="true" tabindex="-1"></a><span class="dt">&lt;/</span><span class="kw">form</span><span class="dt">&gt;</span></span></code></pre></div>
-<p>and encodes more characters than absolutely necessary. The server must treat it like</p>
-<pre><code>GET http://host/service/People?
-  $filter=LastName%20eq%20&#39;P%26G&#39;&amp;$select=FirstName,LastName</code></pre>
+<p>which encodes spaces and ampersands (and more characters for which encoding is not necessary).</p>
 </div>
 </details>
 </details>

docs/odata-url-conventions/odata-url-conventions.md

@@ -1470,25 +1470,27 @@ request URL are processed together.
 
 The request body MUST use `Content-Type: text/plain` or `Content-Type: application/x-www-form-urlencoded`.
 
-For `Content-Type: text/plain`, the individual query options MUST be separated by `&` or newlines
+For `Content-Type: text/plain`, the individual query options MUST be separated by `&`
 and MUST use the same percent-encoding as in URLs (especially: no spaces, tabs, or line breaks allowed)
 and MUST follow the syntax rules described in [chapter 5](#QueryOptions).
 
 ::: example
-Example 50: passing a filter condition in the request body
+Example <a name="postquery" href="#postquery">50</a>
 ```
 POST http://host/service/People/$query
 Content-Type: text/plain
 
-$filter=[FirstName,LastName]%20in%20[["John","Doe"],["Jane","Smith"]]
+$filter=LastName%20eq%20'P%26G'&$select=FirstName,LastName
 ```
 This POST request would result from submitting the HTML form
 ```html
 <form method="post" action="http://host/service/People/$query"
       enctype="text/plain">
-  <input name="$filter"
-    value='[FirstName,LastName]%20in%20[["John","Doe"],["Jane","Smith"]]'>
+  <input name="$filter" value="LastName%20eq%20'P%26G'">
+  <input name="$select" value="FirstName,LastName">
 </form>
+in which spaces and ampersands must be percent-encoded, because `text/plain`
+forms perform no such encoding.
 ```
 :::
 
@@ -1504,7 +1506,8 @@ in the [URL Living Standard](#_url), section 5.2 with _tuples_ being the list
 of name/value pairs for the individual query options.
 
 ::: example
-Example 51: passing multiple system query options in the request body
+Example 51: The same request as in [example 50](#postquery) with `application/x-www-form-urlencoded`
+encoding (note the differences in encoding):
 ```
 POST http://host/service/People/$query
 Content-Type: application/x-www-form-urlencoded
@@ -1519,12 +1522,8 @@ This POST request would result from submitting the HTML form
   <input name="$select" value="FirstName,LastName">
 </form>
 ```
-and encodes more characters than absolutely necessary.
-The server must treat it like
-```
-GET http://host/service/People?
-  $filter=LastName%20eq%20'P%26G'&$select=FirstName,LastName
-```
+which encodes spaces and ampersands (and more characters for which encoding is
+not necessary).
 :::
 
 

odata-url-conventions/4 Resource Path.md

@@ -1015,25 +1015,27 @@ request URL are processed together.
 
 The request body MUST use `Content-Type: text/plain` or `Content-Type: application/x-www-form-urlencoded`.
 
-For `Content-Type: text/plain`, the individual query options MUST be separated by `&` or newlines
+For `Content-Type: text/plain`, the individual query options MUST be separated by `&`
 and MUST use the same percent-encoding as in URLs (especially: no spaces, tabs, or line breaks allowed)
 and MUST follow the syntax rules described in [chapter ##QueryOptions].
 
 ::: example
-Example ##ex: passing a filter condition in the request body
+Example ##ex_postquery
 ```
 POST http://host/service/People/$query
 Content-Type: text/plain
 
-$filter=[FirstName,LastName]%20in%20[["John","Doe"],["Jane","Smith"]]
+$filter=LastName%20eq%20'P%26G'&$select=FirstName,LastName
 ```
 This POST request would result from submitting the HTML form
 ```html
 <form method="post" action="http://host/service/People/$query"
       enctype="text/plain">
-  <input name="$filter"
-    value='[FirstName,LastName]%20in%20[["John","Doe"],["Jane","Smith"]]'>
+  <input name="$filter" value="LastName%20eq%20'P%26G'">
+  <input name="$select" value="FirstName,LastName">
 </form>
+in which spaces and ampersands must be percent-encoded, because `text/plain`
+forms perform no such encoding.
 ```
 :::
 
@@ -1049,7 +1051,8 @@ in the [URL Living Standard](#_url), section 5.2 with _tuples_ being the list
 of name/value pairs for the individual query options.
 
 ::: example
-Example ##ex: passing multiple system query options in the request body
+Example ##ex: The same request as in [example ##postquery] with `application/x-www-form-urlencoded`
+encoding (note the differences in encoding):
 ```
 POST http://host/service/People/$query
 Content-Type: application/x-www-form-urlencoded
@@ -1064,10 +1067,6 @@ This POST request would result from submitting the HTML form
   <input name="$select" value="FirstName,LastName">
 </form>
 ```
-and encodes more characters than absolutely necessary.
-The server must treat it like
-```
-GET http://host/service/People?
-  $filter=LastName%20eq%20'P%26G'&$select=FirstName,LastName
-```
+which encodes spaces and ampersands (and more characters for which encoding is
+not necessary).
 :::