feat(AIP-140): allow url field name in specific cases#1551
Merged
noahdietz merged 4 commits intoaip-dev:masterfrom Sep 15, 2025
Merged
feat(AIP-140): allow url field name in specific cases#1551noahdietz merged 4 commits intoaip-dev:masterfrom
noahdietz merged 4 commits intoaip-dev:masterfrom
Conversation
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.
noahdietz
reviewed
Aug 27, 2025
Collaborator
noahdietz
left a comment
noahdietz
left a comment
There was a problem hiding this comment.
Hey @stephanemoore this seems reasonable to do! Let me circle back with some others and get back to you.
noahdietz
reviewed
Aug 27, 2025
Co-authored-by: Noah Dietz <noahdietz@users.noreply.github.com>
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: aip-dev#1551
noahdietz
approved these changes
Sep 15, 2025
noahdietz
changed the title
stephanemoore
added a commit
to stephanemoore/api-linter
that referenced
this pull request
Sep 19, 2025
… comments AIP-140 was recently updated to clarify that field names may use `url` when the field can only represent a URL. The current URI lint rule for AIP-140 will unconditionally discourage using `url` in field names. This change updates the URI lint rule to be more conservative by only suggesting renaming the field to use `uri` when the field's comments use the term URI. Related update to AIP-140: aip-dev/google.aip.dev#1551
noahdietz
pushed a commit
to googleapis/api-linter
that referenced
this pull request
Sep 22, 2025
… comments (#1541) * fix(AIP-140): restrict `uri` naming suggestions to fields with URI in comments AIP-140 was recently updated to clarify that field names may use `url` when the field can only represent a URL. The current URI lint rule for AIP-140 will unconditionally discourage using `url` in field names. This change updates the URI lint rule to be more conservative by only suggesting renaming the field to use `uri` when the field's comments use the term URI. Related update to AIP-140: aip-dev/google.aip.dev#1551 * Add a test case for a `uri` field with a comment mentioning "URI". * Add a test case for a `url` field where comment has intra-word "uri" substring --------- Co-authored-by: Santiago Quiroga <22756465+quirogas@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
uriin the name and fields that MUST be URLs should useurlin the name.