diff --git a/aip/general/0140.md b/aip/general/0140.md index 759ea1f2b5..0354f03882 100644 --- a/aip/general/0140.md +++ b/aip/general/0140.md @@ -137,9 +137,28 @@ this case, services **may** use a `string`. ### URIs -Field names representing URLs or URIs **should** always use `uri` rather than -`url`. This is because while all URLs are URIs, not all URIs are URLs. Field -names **may** use a prefix in front of `uri` as appropriate. +Field names representing arbitrary URIs **should** use `uri`. In particular, +note that URLs are URIs but not all URIs are URLs. + +Field names **may** use a prefix in front of `uri` as appropriate. + +Field names that can only represent a URL **should** use `url`. + +```proto +message Book { + string name = 1 [(google.api.field_behavior) = IDENTIFIER]; + + // A URL pointing to an image of the book. + string image_url = 2; + + // A URI identifying the book. + // This could be an ISBN or a URL. + string uri = 3; +} +``` + +**Note:** APIs that have previously used `uri` for URL fields may continue to +do so to avoid unnecessary API changes and to preserve local consistency. ### Reserved words