aep-dev
AEP-140 URI vs URL
Recently running the OAS linter on a project, it got flagged for fields containing url in the field names.
Current guidance field names is that they should be uri and not url.
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.
I asked this question in Slack around it:
Has someone been burned by this or why did this come up? If you know it's specifically a URL, why not say that in the field name? Can discuss tomorrow or any other time, it's not super urgent, just want to know if I should push people towards URI.
@kindermoumoute replied.
Looks like it’s from the original AIP, which recently changed https://github.com/aip-dev/google.aip.dev/pull/1551
If it got changed in AIP, maybe we should change it as well?
This would impact both AEP-140 and the linters which are enforcing this.
@thegagne Thanks! can you give more context on the specific situation?
My opinion here is that this guidance is doesn't seem like it really accepts the nuance of the design of such names: I think a _url is a valid prefix / suffix, as not one might want a field in which only a URL is valid, not a URI. It could be confusing to call something that only accepts a URL as a URI field.
The situation:
My team is developing an API that has a field named "downloadUrl". The OpenAPI Linter flags this:
warning aep-140-uri-property-naming Properties representing URLs or URIs should be named "uri" rather than…
I am advocating that we remove this rule from the linter and adopt the changes from AIP-140
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`.
This sounds good to me! @thegagne would you be up for writing the PR?
just to double check, adding @rambleraptor for a second opinion.
Yeah, I think this is a good idea. The original idea was too pedantic imo
