@@ -92,7 +92,7 @@ Definition paragraphs start with `::` and add the matching italicized term to
9292the [ specification index] ( https://spec.graphql.org/draft/#index ) , making it easy
9393to reference them.
9494
95- ## Tone of voice
95+ ## Tone of Voice
9696
9797The GraphQL specification is a reference document and should use neutral and
9898descriptive tone of voice.
@@ -104,3 +104,25 @@ The present tense is usually clearer and shorter:
104104✅ Present: The client then sends a request to the server.
105105
106106❌ 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