Clarifications

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

@@ -1045,7 +1045,7 @@ <h2 id="417-passing-resource-path-and-query-options-in-the-request-body"><a id="
 </summary>
 <p>The resource path and the query options part of an OData URL can be quite long, potentially exceeding the maximum length of URLs supported by components involved in transmitting or processing the request. One way to avoid this is wrapping the request in a batch request, which has the penalty of needing to construct a well-formed batch request body.</p>
 <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 resource path or 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. When the resource path is specified in the request body, <code>$query</code> MUST be appended to the <a href="#ServiceRootURL">service root URL</a>.</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. If the resource path is specified in the request body, it MUST be given as a URL relative to the <a href="#ServiceRootURL">service root URL</a>, and the request URL MUST consist of the service root URL followed by <code>$query</code>. Dividing the resource path between request URL and request body is not allowed.</p>
 <p>The request body MUST use a <code>Content-Type</code> of <code>text/plain</code>, <code>application/x-www-form-urlencoded</code>, or <code>application/json</code>.</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">
@@ -1055,7 +1055,7 @@ <h2 id="417-passing-resource-path-and-query-options-in-the-request-body"><a id="
 
 $filter=LastName%20eq%20&#39;P%26G&#39;&amp;$select=FirstName,LastName</code></pre>
 </div>
-<p>If the resource path is passed in the request body, it MUST be percent-encoded, come before any query options and be separated from them by a <code>?</code>.</p>
+<p>If the resource path is passed in the request body, it MUST be percent-encoded, come before any query options, and be separated from them by a <code>?</code>. In other words, the request body is then a URL relative to the service root URL.</p>
 <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 a list of name/value pairs. This list contains pairs for the individual query options and an optional pair with name <code>$resource</code> for the resource path without percent-encoding.</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.</p>
 <div class="example">

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

@@ -1468,8 +1468,10 @@ the resource path or the query options part of the URL in the request body.
 
 Requests to paths ending in `/$query` MUST use the `POST` verb. Query
 options specified in the request body and query options specified in the
-request URL are processed together. When the resource path is specified in the
-request body, `$query` MUST be appended to the [service root URL](#ServiceRootURL).
+request URL are processed together. If the resource path is specified in the
+request body, it MUST be given as a URL relative to the [service root URL](#ServiceRootURL),
+and the request URL MUST consist of the service root URL followed by `$query`.
+Dividing the resource path between request URL and request body is not allowed.
 
 The request body MUST use a `Content-Type` of `text/plain`, `application/x-www-form-urlencoded`,
 or `application/json`.
@@ -1489,7 +1491,8 @@ $filter=LastName%20eq%20'P%26G'&$select=FirstName,LastName
 :::
 
 If the resource path is passed in the request body, it MUST be percent-encoded,
-come before any query options and be separated from them by a `?`.
+come before any query options, and be separated from them by a `?`. In other words,
+the request body is then a URL relative to the service root URL.
 
 For `Content-Type: application/x-www-form-urlencoded`, the request body MUST be
 suitable _input_ for the [`application/x-www-form-urlencoded` parser](https://url.spec.whatwg.org/#urlencoded-parsing)

odata-url-conventions/4 Resource Path.md

@@ -1011,8 +1011,10 @@ the resource path or the query options part of the URL in the request body.
 
 Requests to paths ending in `/$query` MUST use the `POST` verb. Query
 options specified in the request body and query options specified in the
-request URL are processed together. When the resource path is specified in the
-request body, `$query` MUST be appended to the [service root URL](#ServiceRootURL).
+request URL are processed together. If the resource path is specified in the
+request body, it MUST be given as a URL relative to the [service root URL](#ServiceRootURL),
+and the request URL MUST consist of the service root URL followed by `$query`.
+Dividing the resource path between request URL and request body is not allowed.
 
 The request body MUST use a `Content-Type` of `text/plain`, `application/x-www-form-urlencoded`,
 or `application/json`.
@@ -1032,7 +1034,8 @@ $filter=LastName%20eq%20'P%26G'&$select=FirstName,LastName
 :::
 
 If the resource path is passed in the request body, it MUST be percent-encoded,
-come before any query options and be separated from them by a `?`.
+come before any query options, and be separated from them by a `?`. In other words,
+the request body is then a URL relative to the service root URL.
 
 For `Content-Type: application/x-www-form-urlencoded`, the request body MUST be
 suitable _input_ for the [`application/x-www-form-urlencoded` parser](https://url.spec.whatwg.org/#urlencoded-parsing)