Skip to content

RFC: Adding a glossary to the GraphQL Specification #846

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 8, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 167 additions & 0 deletions rfcs/glossary/Appendix C -- Glossary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
# C. Appendix: Glossary

This appendix seeks to act as a quick reference for some of the technical terms
used throughout this specification document.

## Glossary is Non-Normative

Where a glossary definition and the usage within the specification do not
align, this likely indicates a mistake in the glossary - the glossary is
non-normative and the specification should be treated as the "source of truth."

## Parenthesized Terms

Some terms are defined with parenthesized parts (e.g. "(GraphQL) request").
These terms can be referenced without the parenthesized parts in general, but
the parenthesized parts may be included to help resolve potential ambiguity\*
(for example: the phrase "sending a request to a server" may refer to an HTTP
request, network request, or a GraphQL request).

## Definitions

### (GraphQL) operation type

**Definition**: a type of operation supported by GraphQL; currently the
following operation types are supported:

- {`query`} - for requests which purely seek to retrieve data
- {`mutation`} - for requests which seek to change data or state
- {`subscription`} - for requests that seek to be informed when certain events
occur

Do not confuse (GraphQL) operation type with (GraphQL) root operation type;
these concepts are distinct.

Example:

> GraphQL currently supports 3 **operation types**: `query`, `mutation` and
> `subscription`.

### (GraphQL) operation

**Definition**: an action (for example retrieving data, mutating data or state,
or subscribing to events) you wish to perform, defined via an
{OperationDefinition} (and any associated {FragmentDefinition}) within a
document.

Example:

> A query operation should not mutate data or state, for that a mutation
> operation should be used.

Example:

> Let {operation} be the result of {GetOperation(document, operationName)}.

### (GraphQL) query operation

An operation of type `query`.

Example:

> If {operation} is a query operation: ...

### (GraphQL) mutation operation

An operation of type `mutation`.

Example:

> Otherwise if {operation} is a mutation operation: ...

### (GraphQL) subscription operation

An operation of type `subscription`.

Example:

> Otherwise if {operation} is a subscription operation: ...

### (GraphQL) root operation type

The Object Type associated with a given operation type within the schema.

Example:

> A schema defines the initial root operation type for each kind of operation
> it supports: {`query`}, {`mutation`}, and {`subscription`}; this determines
> the place in the type system where those operations begin.

### (GraphQL) document

**Definition**: a textual representation using GraphQL query language of
operations, fragments, type definitions, directive definitions and/or type
extensions; defined by {Document}.

Example:

> Once a GraphQL document is written, it should always mean the same
> thing.

### Executable (GraphQL) document

**Definition**: the textual representation (using GraphQL query language) of an
operation (or operations) you wish to perform, including fragments as
appropriate; defined by {ExecutableDocument}.

Example:

> Clients use the GraphQL query language to make requests to a GraphQL service.
> We refer to these request sources as executable GraphQL documents. A document
> may contain operations (queries, mutations, and subscriptions) as well as
> fragments, a common unit of composition allowing for data requirement reuse.

Example:

> Documents are only executable by a GraphQL service if they are
> {ExecutableDocument} and contain at least one {OperationDefinition}.

### (GraphQL) variables

**Definition**: placeholder for a value within an operation that may be
supplied at runtime; defined via {VariableDefinitions}.

Example:

> Variables must be defined at the top of an operation and are in scope
> throughout the execution of that operation.

Example:

> `$devicePicSize` is an operation variable in the following operation:
>
> ```graphql example
> query getZuckProfile($devicePicSize: Int) {
> user(id: 4) {
> id
> name
> profilePic(size: $devicePicSize)
> }
> }
> ```

### (GraphQL) request

**Definition**: the full description of what you wish GraphQL to execute,
including the GraphQL schema, document, variables, operation name and initial
value. See {ExecuteRequest()}.

Note: The GraphQL schema and initial value are commonly implicit at the
transport level; for example when a GraphQL schema is exposed over HTTP,
accessing this HTTP endpoint _implicitly_ defines the GraphQL schema to use.

> When using GraphQL over HTTP, it's common to encode the GraphQL request as
> JSON.

### (GraphQL) request error

**Definition**: an error which occurs whilst preparing a GraphQL request for
execution (including parsing and validating the document, determining the
operation, and coercing the variables) resulting in the entire GraphQL request
being aborted before execution can begin. See [Errors](#sec-Errors).

Example:

> Request errors are raised before execution begins. This may occur due to a
> parse grammar or validation error in the requested document, an inability to
> determine which operation to execute, or invalid input values for variables.
24 changes: 24 additions & 0 deletions rfcs/glossary/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Glossary RFC

The GraphQL spec uses a lot of terminology, some of this terminology is
introduced implicitly, some is defined explicitly, but either way finding the
definition when you read a term in the spec can be challenging.

To address these challenges, we propose adding a glossary to the GraphQL spec.
This glossary will be in the form of an additional appendix at the end of the
GraphQL spec.

We may or may not enhance `spec-md` with glossary-specific features (for
example linking to definitions where terms are used, or displaying the
definition on hover in a tooltip). This is currently seen as a separate effort
since having a glossary is useful in itself, so we should concentrate for now
on the glossary definitions only.

This RFC is composed of this file (`rfcs/glossary/README.md`) which explains
the thought behind the glossary RFC, and the glossary file itself
([`rfcs/glossary/Appendix C -- Glossary.md`](./Appendix%20C%20--%20Glossary.md))
which should be suitable for moving directly into the `spec/` folder in order
to add the glossary to the spec.

The glossary is not yet complete, and PRs adding definitions to it (in
alphabetical order) are welcome.