v3.2: Clarify template variable uniqueness #4791
Merged
+5
−1
Conversation
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
This clarifies that variables in both path and server URL templates MUST be unique. This is justified as compatible with our minor release policy on the following grounds: * Due to Parameter Object `name` + `in` constraints and the Server Object's `variables` field being a map, each variable can only map to one paramater or server variable (although the "one" paramater might be defined separately yet uniquely for each Operation). * The Path Templating section uses the phrase "Each template expression in the path MUST correspond to ***a*** path parameter" (emphasis added). * The Parameter Object uses similar language in the other direction: "If in is "path", the name field MUST correspond to ***a*** template expression". * The word "a" is interpreted to mean an unknown but unique thing in both directions. * The Server Object's `url` template has always been assumed to function in an analogous way to path templating.
handrews
added
clarification
ralfhandl
approved these changes
Jul 18, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
NOTE: This takes the opposite view as the thread in #4763 (comment) based on continued slack conversations where we dug deeper into the spec wording. Please see the note after the list as well:
This clarifies that variables in both path and server URL templates MUST be unique. This is justified as compatible with our minor release policy on the following grounds:
name+inconstraints and the Server Object'svariablesfield being a map, each variable can only map to one paramater or server variable (although the "one" paramater might be defined separately yet uniquely for each Operation).urltemplate has always been assumed to function in an analogous way to path templating.Note: I think this is reasonably solid, and no one has actually presented a use case or known use of duplicate fields, but it does rely on interpreting language in a very specific way. I am very much interested in whether people see this as a clarification or change, as my intent is for it to be a clarification.