From 501fdb97b69bdf74ece1b01fdc5f7b96e83d5d83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Thu, 27 Jun 2024 08:59:35 +0200 Subject: [PATCH] TC 2024-06-26 --- .../odata-url-conventions.html | 20 ++++++++-------- .../odata-url-conventions.md | 23 +++++++++---------- odata-url-conventions/4 Resource Path.md | 23 +++++++++---------- 3 files changed, 32 insertions(+), 34 deletions(-) diff --git a/docs/odata-url-conventions/odata-url-conventions.html b/docs/odata-url-conventions/odata-url-conventions.html index df27f718..7c760f55 100644 --- a/docs/odata-url-conventions/odata-url-conventions.html +++ b/docs/odata-url-conventions/odata-url-conventions.html @@ -992,24 +992,26 @@

chapter 5.

+

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.

-

Example 50: passing a filter condition in the request body

+

Example 50

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

<form method="post" action="http://host/service/People/$query"
       enctype="text/plain">
-  <input name="$filter"
-    value='[FirstName,LastName]%20in%20[["John","Doe"],["Jane","Smith"]]'>
-</form>
+ <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.

For Content-Type: application/x-www-form-urlencoded, the request body MUST be suitable input for the application/x-www-form-urlencoded parser in the URL Living Standard, section 5.1 such that the output of the parsing steps is the list of name/value pairs for the individual query options.

To guarantee this, clients are advised to make the request body the value of output after running the application/x-www-form-urlencoded serializer in the URL Living Standard, section 5.2 with tuples being the list of name/value pairs for the individual query options.

-

Example 51: passing multiple system query options in the request body

+

Example 51: The same request as in example 50 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
 
@@ -1020,9 +1022,7 @@ 
  <input name="$filter" value="LastName eq 'P&G'">
   <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).

diff --git a/docs/odata-url-conventions/odata-url-conventions.md b/docs/odata-url-conventions/odata-url-conventions.md index 316d2594..7313f835 100644 --- a/docs/odata-url-conventions/odata-url-conventions.md +++ b/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 50 ``` 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
- + +
+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 ``` -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). ::: diff --git a/odata-url-conventions/4 Resource Path.md b/odata-url-conventions/4 Resource Path.md index 3122347d..d4f1cc65 100644 --- a/odata-url-conventions/4 Resource Path.md +++ b/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
- + +
+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 ``` -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). :::