Skip to content

Commit aaceb3c

Browse files
authored
fix(AIP-160): move validation guidance to new section (#1460)
1 parent 7cf198a commit aaceb3c

1 file changed

Lines changed: 24 additions & 3 deletions

File tree

aip/general/0160.md

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -190,9 +190,26 @@ above what is defined here. For example, a service may support the logical
190190
operators but only permit a certain number of them (to avoid "queries of death"
191191
or other performance concerns).
192192

193-
Further structure or limitations **must** be clearly documented, **must not**
194-
violate requirements set forth in this document, and a non-compliant filter
195-
query **must** error with `INVALID_ARGUMENT`.
193+
Further structure or limitations **must** be clearly documented, and
194+
**must not** violate requirements set forth in this document.
195+
196+
### Validation
197+
198+
If a non-compliant or schematically invalid `filter` string is specified,
199+
the API **should** error with `INVALID_ARGUMENT`. Wherever validation is relaxed
200+
for `filter`, the API **must** document the difference.
201+
202+
Schematic validation refers, but is not limited to, the following:
203+
204+
- Fields referenced in the `filter` **must** exist on the filtered schema
205+
- Field values provided in the `filter` **must** align to the type of the field
206+
- For example, for a field `int32 age` a `filter` like `"age=hello"` is
207+
invalid
208+
- Field values for bounded data types e.g. `enum` provided in the `filter`
209+
**must** be a valid value in the set
210+
- Field values for standardized types e.g. `Timestamp` **must** conform to the
211+
documented standard (see [Comparison Operators](#comparison-operators) for a
212+
list of such types)
196213

197214
<!-- prettier-ignore-start -->
198215
[aip-132]: ./0132.md
@@ -204,3 +221,7 @@ query **must** error with `INVALID_ARGUMENT`.
204221
[rfc-3339]: https://tools.ietf.org/html/rfc3339
205222
[timestamps]: https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/timestamp.proto
206223
<!-- prettier-ignore-end -->
224+
225+
## Changelog
226+
227+
- **2024-12-11**: Move non-compliant filter guidance to Validation section.

0 commit comments

Comments
 (0)