Skip to content

Commit dbabf1e

Browse files
benjiebenjie
authored
RFC: glossary (#846)
1 parent 0062610 commit dbabf1e

File tree

2 files changed

+191
-0
lines changed

2 files changed

+191
-0
lines changed

‎rfcs/glossary/Appendix C -- Glossary.md

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# C. Appendix: Glossary
2+
3+
This appendix seeks to act as a quick reference for some of the technical terms
4+
used throughout this specification document.
5+
6+
## Glossary is Non-Normative
7+
8+
Where a glossary definition and the usage within the specification do not
9+
align, this likely indicates a mistake in the glossary - the glossary is
10+
non-normative and the specification should be treated as the "source of truth."
11+
12+
## Parenthesized Terms
13+
14+
Some terms are defined with parenthesized parts (e.g. "(GraphQL) request").
15+
These terms can be referenced without the parenthesized parts in general, but
16+
the parenthesized parts may be included to help resolve potential ambiguity\*
17+
(for example: the phrase "sending a request to a server" may refer to an HTTP
18+
request, network request, or a GraphQL request).
19+
20+
## Definitions
21+
22+
### (GraphQL) operation type
23+
24+
**Definition**: a type of operation supported by GraphQL; currently the
25+
following operation types are supported:
26+
27+
- {`query`} - for requests which purely seek to retrieve data
28+
- {`mutation`} - for requests which seek to change data or state
29+
- {`subscription`} - for requests that seek to be informed when certain events
30+
occur
31+
32+
Do not confuse (GraphQL) operation type with (GraphQL) root operation type;
33+
these concepts are distinct.
34+
35+
Example:
36+
37+
> GraphQL currently supports 3 **operation types**: `query`, `mutation` and
38+
> `subscription`.
39+
40+
### (GraphQL) operation
41+
42+
**Definition**: an action (for example retrieving data, mutating data or state,
43+
or subscribing to events) you wish to perform, defined via an
44+
{OperationDefinition} (and any associated {FragmentDefinition}) within a
45+
document.
46+
47+
Example:
48+
49+
> A query operation should not mutate data or state, for that a mutation
50+
> operation should be used.
51+
52+
Example:
53+
54+
> Let {operation} be the result of {GetOperation(document, operationName)}.
55+
56+
### (GraphQL) query operation
57+
58+
An operation of type `query`.
59+
60+
Example:
61+
62+
> If {operation} is a query operation: ...
63+
64+
### (GraphQL) mutation operation
65+
66+
An operation of type `mutation`.
67+
68+
Example:
69+
70+
> Otherwise if {operation} is a mutation operation: ...
71+
72+
### (GraphQL) subscription operation
73+
74+
An operation of type `subscription`.
75+
76+
Example:
77+
78+
> Otherwise if {operation} is a subscription operation: ...
79+
80+
### (GraphQL) root operation type
81+
82+
The Object Type associated with a given operation type within the schema.
83+
84+
Example:
85+
86+
> A schema defines the initial root operation type for each kind of operation
87+
> it supports: {`query`}, {`mutation`}, and {`subscription`}; this determines
88+
> the place in the type system where those operations begin.
89+
90+
### (GraphQL) document
91+
92+
**Definition**: a textual representation using GraphQL query language of
93+
operations, fragments, type definitions, directive definitions and/or type
94+
extensions; defined by {Document}.
95+
96+
Example:
97+
98+
> Once a GraphQL document is written, it should always mean the same
99+
> thing.
100+
101+
### Executable (GraphQL) document
102+
103+
**Definition**: the textual representation (using GraphQL query language) of an
104+
operation (or operations) you wish to perform, including fragments as
105+
appropriate; defined by {ExecutableDocument}.
106+
107+
Example:
108+
109+
> Clients use the GraphQL query language to make requests to a GraphQL service.
110+
> We refer to these request sources as executable GraphQL documents. A document
111+
> may contain operations (queries, mutations, and subscriptions) as well as
112+
> fragments, a common unit of composition allowing for data requirement reuse.
113+
114+
Example:
115+
116+
> Documents are only executable by a GraphQL service if they are
117+
> {ExecutableDocument} and contain at least one {OperationDefinition}.
118+
119+
### (GraphQL) variables
120+
121+
**Definition**: placeholder for a value within an operation that may be
122+
supplied at runtime; defined via {VariableDefinitions}.
123+
124+
Example:
125+
126+
> Variables must be defined at the top of an operation and are in scope
127+
> throughout the execution of that operation.
128+
129+
Example:
130+
131+
> `$devicePicSize` is an operation variable in the following operation:
132+
>
133+
> ```graphql example
134+
> query getZuckProfile($devicePicSize: Int) {
135+
> user(id: 4) {
136+
> id
137+
> name
138+
> profilePic(size: $devicePicSize)
139+
> }
140+
> }
141+
> ```
142+
143+
### (GraphQL) request
144+
145+
**Definition**: the full description of what you wish GraphQL to execute,
146+
including the GraphQL schema, document, variables, operation name and initial
147+
value. See {ExecuteRequest()}.
148+
149+
Note: The GraphQL schema and initial value are commonly implicit at the
150+
transport level; for example when a GraphQL schema is exposed over HTTP,
151+
accessing this HTTP endpoint _implicitly_ defines the GraphQL schema to use.
152+
153+
> When using GraphQL over HTTP, it's common to encode the GraphQL request as
154+
> JSON.
155+
156+
### (GraphQL) request error
157+
158+
**Definition**: an error which occurs whilst preparing a GraphQL request for
159+
execution (including parsing and validating the document, determining the
160+
operation, and coercing the variables) resulting in the entire GraphQL request
161+
being aborted before execution can begin. See [Errors](#sec-Errors).
162+
163+
Example:
164+
165+
> Request errors are raised before execution begins. This may occur due to a
166+
> parse grammar or validation error in the requested document, an inability to
167+
> determine which operation to execute, or invalid input values for variables.

‎rfcs/glossary/README.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Glossary RFC
2+
3+
The GraphQL spec uses a lot of terminology, some of this terminology is
4+
introduced implicitly, some is defined explicitly, but either way finding the
5+
definition when you read a term in the spec can be challenging.
6+
7+
To address these challenges, we propose adding a glossary to the GraphQL spec.
8+
This glossary will be in the form of an additional appendix at the end of the
9+
GraphQL spec.
10+
11+
We may or may not enhance `spec-md` with glossary-specific features (for
12+
example linking to definitions where terms are used, or displaying the
13+
definition on hover in a tooltip). This is currently seen as a separate effort
14+
since having a glossary is useful in itself, so we should concentrate for now
15+
on the glossary definitions only.
16+
17+
This RFC is composed of this file (`rfcs/glossary/README.md`) which explains
18+
the thought behind the glossary RFC, and the glossary file itself
19+
([`rfcs/glossary/Appendix C -- Glossary.md`](./Appendix%20C%20--%20Glossary.md))
20+
which should be suitable for moving directly into the `spec/` folder in order
21+
to add the glossary to the spec.
22+
23+
The glossary is not yet complete, and PRs adding definitions to it (in
24+
alphabetical order) are welcome.

0 commit comments

Comments
 (0)