Skip to content

Commit ac580e9

Browse files
authored
fix(AIP-132): Require documentation for ordering not matching field type (#1484)
1 parent aa10763 commit ac580e9

1 file changed

Lines changed: 10 additions & 0 deletions

File tree

aip/general/0132.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,13 @@ request message **should** contain a `string order_by` field.
156156
equivalent.
157157
- Subfields are specified with a `.` character, such as `foo.bar` or
158158
`address.street`.
159+
- The resulting list order **should** be based on the field type's natural
160+
comparator e.g. numerics ordered numerically, strings ordered
161+
lexicographically, etc. However, APIs **may** choose to use a different
162+
ordering; if so, it **must** be documented in the `order_by` definition.
163+
- Furthermore, [well-known][] types, like `Timestamp` and `Duration` are
164+
compared as their representative type; `Timestamp` is compared as time e.g.
165+
before or after, `Duration` is compared as a quantity e.g. more or less.
159166

160167
<!-- TODO(#220): Add a reference to AIP-161 once it is written. -->
161168

@@ -202,9 +209,12 @@ NOT_FOUND errors][permission-denied].
202209
[reading across collections]: ./0159.md
203210
[singleton]: ./0156.md
204211
[soft delete]: ./0135.md#soft-delete
212+
[well-known]: https://protobuf.dev/reference/protobuf/google.protobuf
205213

206214
## Changelog
207215

216+
- **2025-02-25**: Require documentation for ordering not matching field type
217+
with clarification on ordering of well-known types.
208218
- **2023-03-22**: Fix guidance wording to mention AIP-159.
209219
- **2023-03-17**: Align with AIP-122 and make Get a must.
210220
- **2022-11-04**: Aggregated error guidance to AIP-193.

0 commit comments

Comments
 (0)