From f06847bc3bb3bf751c1dacd11ef6c007459a56e0 Mon Sep 17 00:00:00 2001 From: Stephane Moore Date: Wed, 27 Aug 2025 00:05:25 -0700 Subject: [PATCH 1/4] =?UTF-8?q?Update=20guidance=20on=20URL/URI=20naming?= =?UTF-8?q?=20in=20AIP-140=20=E2=9C=8D=EF=B8=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This proposes to update the guidelines to advocate for clearer naming for fields that can only return URLs. It appears to be possible to misinterpret AIP-0140 guidelines to infer that fields that return URLs MUST be named as if they could be URIs. It seems more accurate to indicate that fields that COULD be URIs should use `uri` in the name and fields that MUST be URLs should use `url` in the name. --- aip/general/0140.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/aip/general/0140.md b/aip/general/0140.md index 759ea1f2b5..ecaf00994b 100644 --- a/aip/general/0140.md +++ b/aip/general/0140.md @@ -137,9 +137,14 @@ 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** always 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. + +### URLs + +If a field can only represent a URL, the field name should always use `url`. ### Reserved words From 740922bc597c25a5f2ce6ffce42a74e8c4452852 Mon Sep 17 00:00:00 2001 From: Stephane Moore Date: Fri, 12 Sep 2025 15:13:41 -0700 Subject: [PATCH 2/4] Apply suggestion to drop "always" Co-authored-by: Noah Dietz --- aip/general/0140.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/general/0140.md b/aip/general/0140.md index ecaf00994b..efdae1f4ba 100644 --- a/aip/general/0140.md +++ b/aip/general/0140.md @@ -144,7 +144,7 @@ Field names **may** use a prefix in front of `uri` as appropriate. ### URLs -If a field can only represent a URL, the field name should always use `url`. +If a field can only represent a URL, the field name should use `url`. ### Reserved words From db4af14f0e1828eacfd9ef8ed5a739d06126596b Mon Sep 17 00:00:00 2001 From: Stephane Moore Date: Sat, 13 Sep 2025 14:33:01 -0700 Subject: [PATCH 3/4] Apply various changes based on review feedback in PR #1551 Changes include: * Remove "always" from the prescription for URI fields for consistency. * Collapse proposed URLs section into URIs section. * Reformat prescription for URIs to be consistent with prescription for URLs. * Add an example proto for clarity. * Add a note indicating that the prescription for URLs should be balanced against local consistency and API stability. PR link: https://github.com/aip-dev/google.aip.dev/pull/1551 --- aip/general/0140.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/aip/general/0140.md b/aip/general/0140.md index efdae1f4ba..6affcbb7b4 100644 --- a/aip/general/0140.md +++ b/aip/general/0140.md @@ -137,14 +137,29 @@ this case, services **may** use a `string`. ### URIs -Field names representing arbitrary URIs **should** always use `uri`. In -particular, note that URLs are URIs but not all URIs are URLs. +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. -### URLs +Field names that can only represent a URL **should** use `url`. -If a field can only represent a URL, the field name 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 From 4fd666317806937e03f99ce0e2c44668189f62f8 Mon Sep 17 00:00:00 2001 From: Stephane Moore Date: Mon, 15 Sep 2025 14:59:50 -0700 Subject: [PATCH 4/4] Remove newline after `Note:` in URIs section --- aip/general/0140.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/aip/general/0140.md b/aip/general/0140.md index 6affcbb7b4..0354f03882 100644 --- a/aip/general/0140.md +++ b/aip/general/0140.md @@ -157,9 +157,8 @@ message Book { } ``` -**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. +**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