fix: Clarify behavior of FIQL/RSQL operators with nulls (#104)

apitukh · web-flow · commit 7b340bc13b5f · 2025-05-07T14:48:00.000-04:00
diff --git a/standards/collections.md b/standards/collections.md
@@ -576,20 +576,24 @@ Getting Started: [REST Query Language with RSQL](https://www.baeldung.com/rest-a
 - [.NET: rsql4net](https://github.com/gwendallg/rsql4net)
 - [Example Lines of Code for a Custom Parser](https://gist.github.com/jirutka/42a0f9bfea280b3c5dca) for Java Persistence API (JPA)
 
+By default, all operators except `=isnull=` **MUST** exclude fields with NULL values from the results. This mirrors the behavior of SQL, where expressions involving NULL evaluate to unknown and are therefore not returned in comparison-based queries.
+
+To explicitly filter for NULL values, add the `=isnull=` operator with either true or false.
+
 It is not mandatory to support all operators listed in the table below as this document is about syntax and convention. Any API may support just a subset of given operators or provide additional operators if needed.
 
-| Filter | Operator | Standard | Example | Notes |
-| ------ | -------- | -------- | ------- | ----- |
+| Filter | Operator | Standard | Example                                                                                                                                                                                          | Notes |
+| ------ | -------- | -------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----- |
 | Equals | `==` | FIQL | someKey==value<br />someKey==*value<br />someKey==value*<br />someKey==*value*<br />someKey==*va*ue*<br />someKey=="Should be quoted if a value contains whitespaces or any reserved characters" | Allowed to use wildcard symbol '*' at the beginning, at the end, in the middle, or in multiple places of a string to represent 'ends with', 'starts with', 'contains', or 'like' functions. An endpoint should provide documentation about wildcard usage and the default case. |
-| Not Equals | `!=` | FIQL | someKey!=value<br />someKey!=*value<br />someKey!=value*<br />someKey!=*value*<br />someKey!=*va*ue* | Allowed to use wildcard symbol '*' at the beginning, at the end, in the middle, or in multiple places of a string to represent 'not ends with', 'not starts with', 'not contains', 'not like' functions. An endpoint should provide documentation about wildcard usage and the default case. |
-| Less Than | `=lt=` | FIQL | someKey=lt=42 | < |
-| Less Than or Equals | `=le=` | FIQL | someKey=le=42 | <= |
-| Greater Than | `=gt=` | FIQL | someKey=gt=42 | > |
-| Greater Than or Equals | `=ge=` | FIQL | someKey=ge=42 | >= |
-| In | `=in=` | RSQL | someKey=in=(1,2,3) | Can be added as a custom function to any FIQL library if you can't find any RSQL compatible library for your platform |
-| Not In | `=out=` | RSQL | someKey=out=(1,2,3) | Can be added as a custom function to any FIQL library if you can't find any RSQL compatible library for your platform |
-| Is NULL | `=isnull=` | Custom | someKey=isnull=true | If API requires NULL check then this operator should be used. |
-| String Operators | =contains=<br />=containsic=<br />=startswith=<br />=startswithic=<br />=endswith=<br />=endswithic=<br />=like=<br />=notlike=<br />=likeic=<br />=notlikeic=<br /> | Custom | someKey=contains=VALUE<br />case sensitive check as the given function doesn't have 'ic' suffix, where 'ic' means "ignoring case" | If API requires special handling for strings it is allowed to provide a custom operator with or without the 'ic' suffix to support advanced string filtering. It is the responsibility of the implementor to maintain consistency between wildcards used with 'Equals' and 'Not Equals' operators and custom functions. |
+| Not Equals | `!=` | FIQL | someKey!=value<br />someKey!=*value<br />someKey!=value*<br />someKey!=*value*<br />someKey!=*va*ue*                                                                                             | Allowed to use wildcard symbol '*' at the beginning, at the end, in the middle, or in multiple places of a string to represent 'not ends with', 'not starts with', 'not contains', 'not like' functions. An endpoint should provide documentation about wildcard usage and the default case. |
+| Less Than | `=lt=` | FIQL | someKey=lt=42                                                                                                                                                                                    | < |
+| Less Than or Equals | `=le=` | FIQL | someKey=le=42                                                                                                                                                                                    | <= |
+| Greater Than | `=gt=` | FIQL | someKey=gt=42                                                                                                                                                                                    | > |
+| Greater Than or Equals | `=ge=` | FIQL | someKey=ge=42                                                                                                                                                                                    | >= |
+| In | `=in=` | RSQL | someKey=in=(1,2,3)                                                                                                                                                                               | Can be added as a custom function to any FIQL library if you can't find any RSQL compatible library for your platform |
+| Not In | `=out=` | RSQL | someKey=out=(1,2,3)                                                                                                                                                                              | Can be added as a custom function to any FIQL library if you can't find any RSQL compatible library for your platform |
+| Is NULL | `=isnull=` | Custom | someKey=isnull=true<br/>someKey=isnull=false                                                                                                                                                     | If API requires NULL check then this operator should be used. |
+| String Operators | =contains=<br />=containsic=<br />=startswith=<br />=startswithic=<br />=endswith=<br />=endswithic=<br />=like=<br />=notlike=<br />=likeic=<br />=notlikeic=<br /> | Custom | someKey=contains=VALUE<br />case sensitive check as the given function doesn't have 'ic' suffix, where 'ic' means "ignoring case"                                                                | If API requires special handling for strings it is allowed to provide a custom operator with or without the 'ic' suffix to support advanced string filtering. It is the responsibility of the implementor to maintain consistency between wildcards used with 'Equals' and 'Not Equals' operators and custom functions. |
 
 ```warning
 The dynamic nature of filters means that all fields cannot be listed in Open API specifications because there could be dozens for a single endpoint depending on the level of nesting in the response. Instead, Open API specification may contain generic information about the supported filtering approach, the list of allowed operators, examples, and other information that may be helpful for a user.
@@ -676,4 +680,4 @@ ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
 }
 ```
 
-Processing of `ETag` and associated validation headers should be consistent with the [Request Response](request-response.md#etag) section, returning appropriate status codes as needed.
+Processing of `ETag` and associated validation headers should be consistent with the [Request Response](request-response.md#etag) section, returning appropriate status codes as needed.
