@@ -92,7 +92,7 @@ Definition paragraphs start with `::` and add the matching italicized term to
92
92
the [ specification index] ( https://spec.graphql.org/draft/#index ) , making it easy
93
93
to reference them.
94
94
95
- ## Tone of voice
95
+ ## Tone of Voice
96
96
97
97
The GraphQL specification is a reference document and should use neutral and
98
98
descriptive tone of voice.
@@ -104,3 +104,25 @@ The present tense is usually clearer and shorter:
104
104
✅ Present: The client then sends a request to the server.
105
105
106
106
❌ Future: The client will then send a request to the server.
107
+
108
+ ** Write in the third person**
109
+
110
+ The specification should avoid the first person (“we,” “our”) and instead use
111
+ the third person or passive constructions when necessary. For example:
112
+
113
+ ✅ “The server validates the request against the schema.”
114
+
115
+ ❌ “We validate the request against the schema.”
116
+
117
+ ** Use RFC 2119 keywords**
118
+
119
+ The specification should use the normative keywords defined in
120
+ [ RFC 2119] ( https://www.rfc-editor.org/rfc/rfc2119 ) (** MUST** , ** MUST NOT** ,
121
+ ** SHOULD** , ** SHOULD NOT** , ** MAY** ). However, in the context of a sentence
122
+ these words should be lower-cased (e.g., “must,” “should,” “may”) in context of
123
+ a sentence. This avoids unnecessary visual emphasis while preserving normative
124
+ meaning.
125
+
126
+ ✅ “A query must contain a single root operation type.”
127
+
128
+ ❌ “A query MUST contain a single root operation type.”
0 commit comments