RECOMMENDED to SHOULD - #416
Open
benjie wants to merge 1 commit into
Open
Conversation
benjie
commented
Aug 3, 2026
| execution. Using `405` (Method Not Allowed) is RECOMMENDED. This restriction is | ||
| necessary to conform with the long-established semantics of safe methods within | ||
| HTTP. | ||
| execution; status code `405` (Method Not Allowed) is RECOMMENDED. This |
Member
Author
There was a problem hiding this comment.
I've left this RECOMMENDED in place, it's the only one, but writing the sentence to use both MUST and SHOULD read really awkwardly and I believe RFC2119 gives us a choice of words to allow us to avoid these kinds of linguistic shenanigans.
benjie
commented
Aug 3, 2026
Comment on lines
-356
to
+357
| to add additional information to a request they MUST do so via other means; the | ||
| RECOMMENDED approach is to add an implementer-scoped entry to the {extensions} | ||
| object. | ||
| to add additional information to a request they MUST do so via other means, for | ||
| example by adding an implementer-scoped entry to the {extensions} object. |
Member
Author
There was a problem hiding this comment.
Adding to extensions is the "recommended" approach; but if you choose to set it via headers I wouldn't say you "should not" have done that. So I've lowered this to an example.
benjie
force-pushed
the
recommended2should
branch
from
August 3, 2026 09:17
b337df2 to
d4094f1
Compare
benjie
force-pushed
the
recommended2should
branch
from
August 3, 2026 09:21
d4094f1 to
d38c825
Compare
benjie
force-pushed
the
recommended2should
branch
from
August 3, 2026 09:40
d38c825 to
89f6e06
Compare
phryneas
approved these changes
Aug 3, 2026
martinbonnin
reviewed
Aug 3, 2026
martinbonnin
left a comment
martinbonnin
left a comment
Contributor
There was a problem hiding this comment.
The RECOMMENDED wording grew on me. I've spent a couple of years with this spec using RECOMMENDED and it worked fine by me. All in all no strong opposition but also no strong drive to change this. I'll abstain.
BoD
approved these changes
Aug 3, 2026
benjie
force-pushed
the
recommended2should
branch
from
August 3, 2026 21:01
89f6e06 to
36f8f38
Compare
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
4 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.
Before merging this, merge:
I am not particularly in favor of this change; but if we're going to do it we should do it right... I have put some normative changes in this, for example previously we RECOMMENDED that URLs end with
/graphqlbut I'm not willing to say that they SHOULD end with/graphql(even though they have the same weight in RFC2119) so I've noted that it's a common convention instead.I would recommend that people create their GraphQL APIs at
/graphqlor similar. Doing so is recommended.For someone who has deployed their GraphQL API at
https://example.com/apiorhttps://graphql.example.comI would not say that they "SHOULD NOT" have done that. It's fine.