Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions aip/general/0122.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,8 +137,6 @@ ID for the publisher, and `les-miserables` is the resource ID for the book.
- Characters outside of ASCII **should not** be permitted; however, if
Unicode characters are necessary, APIs **must** follow guidance in
[AIP-210][].
- User-specified IDs **should not** be permitted to be a UUID (or any value
that syntactically appears to be a UUID).
- If resource IDs are not user-settable, the API **should** document the
basic format, and any upper boundaries (for example, "at most 63
characters").
Expand Down Expand Up @@ -400,8 +398,24 @@ preventing resource data duplication, and forcing the owning service to be
involved in the resolution of the reference (via Standard Methods), guaranteeing
isolation of logical concerns per-resource.

## History

### Disallowing UUIDs in user-specified IDs

As part of an effort to make APIs more declarative-friendly, APIs were required
to allow user-specified resource ID on creation. As part of this, a supporting
field `string uid` containing a UUID was also encouraged. Guidance was then
added to discourage the _user-specified resource ID_ from being a UUID or
even resembling one.

Ostensibly, the fact that `uid` contained a service-generated UUID motivated
this restriction on the user-specified resource ID, forcing the user-specified
resource ID to be a more "meaningful" value. However, we no longer saw value in
this requirement, hence its removal.

## Changelog

- **2025-03-10**: Drop guidance disallowing UUID in user-specified ID.
- **2024-10-15**: Add some rationale we found for use of `name` as a field and
instead of IDs as an identifier.
- **2024-06-14**: Clarify resource annotation shortening rules for nested
Expand Down