@@ -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