You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/pages/learn/schema.mdx
+17-17Lines changed: 17 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,9 @@ import { Callout } from "nextra/components"
4
4
5
5
<pclassName="learn-subtitle">Learn about the different elements of the GraphQL type system</p>
6
6
7
-
The GraphQL [type system](https://spec.graphql.org/October2021/#sec-Type-System) describes what data can be queried from the API. The collection of those capabilities is referred to as the service's _schema_ and clients can use that schema to send queries to the API that return predictable results.
7
+
The GraphQL [type system](https://spec.graphql.org/draft/#sec-Type-System) describes what data can be queried from the API. The collection of those capabilities is referred to as the service's _schema_ and clients can use that schema to send queries to the API that return predictable results.
8
8
9
-
On this page, we'll explore GraphQL's [six kinds of named type definitions](https://spec.graphql.org/October2021/#sec-Types) as well as other features of the type system to learn how they may be used to describe your data and the relationships between them. Since GraphQL can be used with any backend framework or programming language, we'll avoid implementation-specific details and talk only about the concepts.
9
+
On this page, we'll explore GraphQL's [six kinds of named type definitions](https://spec.graphql.org/draft/#sec-Types) as well as other features of the type system to learn how they may be used to describe your data and the relationships between them. Since GraphQL can be used with any backend framework or programming language, we'll avoid implementation-specific details and talk only about the concepts.
10
10
11
11
## Type system
12
12
@@ -38,7 +38,7 @@ Since we can't rely on a specific programming language to discuss GraphQL schema
38
38
39
39
## Object types and fields
40
40
41
-
The most basic components of a GraphQL schema are [Object types](https://spec.graphql.org/October2021/#sec-Objects), which just represent a kind of object you can fetch from your service, and what fields it has. In SDL, we represent it like this:
41
+
The most basic components of a GraphQL schema are [Object types](https://spec.graphql.org/draft/#sec-Objects), which just represent a kind of object you can fetch from your service, and what fields it has. In SDL, we represent it like this:
42
42
43
43
```graphql
44
44
typeCharacter {
@@ -59,7 +59,7 @@ Now you know what a GraphQL Object type looks like and how to read the basics of
59
59
60
60
### Arguments
61
61
62
-
Every field on a GraphQL Object type can have zero or more [arguments](https://spec.graphql.org/October2021/#sec-Field-Arguments), for example, the `length` field below:
62
+
Every field on a GraphQL Object type can have zero or more [arguments](https://spec.graphql.org/draft/#sec-Field-Arguments), for example, the `length` field below:
63
63
64
64
```graphql
65
65
type Starship {
@@ -75,7 +75,7 @@ Arguments can be either required or optional. When an argument is optional, we c
75
75
76
76
### The Query, Mutation, and Subscription types
77
77
78
-
Every GraphQL schema must support `query` operations. The _entry point_ for this [root operation type](https://spec.graphql.org/October2021/#sec-Root-Operation-Types) is a regular Object type called `Query` by default. So if you see a query that looks like this:
78
+
Every GraphQL schema must support `query` operations. The _entry point_ for this [root operation type](https://spec.graphql.org/draft/#sec-Root-Operation-Types) is a regular Object type called `Query` by default. So if you see a query that looks like this:
79
79
80
80
```graphql
81
81
# { "graphiql": true }
@@ -110,7 +110,7 @@ schema {
110
110
111
111
## Scalar types
112
112
113
-
A GraphQL Object type has a name and fields, but at some point, those fields must resolve to some concrete data. That's where the [Scalar types](https://spec.graphql.org/October2021/#sec-Scalars) come in: they represent the leaf values of the query.
113
+
A GraphQL Object type has a name and fields, but at some point, those fields must resolve to some concrete data. That's where the [Scalar types](https://spec.graphql.org/draft/#sec-Scalars) come in: they represent the leaf values of the query.
114
114
115
115
In the following query, the `name` and `appearsIn` fields will resolve to Scalar types:
116
116
@@ -126,7 +126,7 @@ In the following query, the `name` and `appearsIn` fields will resolve to Scalar
126
126
127
127
We know this because those fields don't have any sub-fields—they are the leaves of the query.
128
128
129
-
GraphQL comes with a set of [default Scalar types](https://spec.graphql.org/October2021/#sec-Scalars.Built-in-Scalars) out of the box:
129
+
GraphQL comes with a set of [default Scalar types](https://spec.graphql.org/draft/#sec-Scalars.Built-in-Scalars) out of the box:
130
130
131
131
-`Int`: A signed 32‐bit integer.
132
132
-`Float`: A signed double-precision floating-point value.
@@ -144,7 +144,7 @@ Then it's up to our implementation to define how that type should be serialized,
144
144
145
145
## Enum types
146
146
147
-
[Enum types](https://spec.graphql.org/October2021/#sec-Enums), also known as enumeration types, are a special kind of scalar that is restricted to a particular set of allowed values. This allows you to:
147
+
[Enum types](https://spec.graphql.org/draft/#sec-Enums), also known as enumeration types, are a special kind of scalar that is restricted to a particular set of allowed values. This allows you to:
148
148
149
149
1. Validate that any arguments of this type are one of the allowed values
150
150
2. Communicate through the type system that a field will always be one of a finite set of values
@@ -167,7 +167,7 @@ This means that wherever we use the type `Episode` in our schema, we expect it t
167
167
168
168
Types are assumed to be nullable and singular by default in GraphQL. However, when you use these named types in a schema (or in [query variable declarations](/learn/queries/#variables)) you can apply additional _type modifiers_ that will affect the meaning of those values.
169
169
170
-
As we saw with the Object type example above, GraphQL supports two type modifiers—the [List](https://spec.graphql.org/October2021/#sec-List) and [Non-Null](https://spec.graphql.org/October2021/#sec-List) types—and they can be used individually or in combination with each other.
170
+
As we saw with the Object type example above, GraphQL supports two type modifiers—the [List](https://spec.graphql.org/draft/#sec-List) and [Non-Null](https://spec.graphql.org/draft/#sec-Non-Null) types—and they can be used individually or in combination with each other.
171
171
172
172
### Non-Null
173
173
@@ -254,7 +254,7 @@ You can arbitrarily nest any number of Non-Null and List modifiers, according to
254
254
255
255
## Interface types
256
256
257
-
Like many type systems, GraphQL supports _abstract types_. The first of these types that we'll explore is an [Interface type](https://spec.graphql.org/October2021/#sec-Interfaces), which defines a certain set of fields that a concrete Object type or other Interface type must also include to implement it.
257
+
Like many type systems, GraphQL supports _abstract types_. The first of these types that we'll explore is an [Interface type](https://spec.graphql.org/draft/#sec-Interfaces), which defines a certain set of fields that a concrete Object type or other Interface type must also include to implement it.
258
258
259
259
For example, you could have an `Character` Interface type that represents any character in the Star Wars trilogy:
260
260
@@ -341,7 +341,7 @@ Note that Interface types may not implement themselves or contain any cyclic ref
341
341
342
342
## Union types
343
343
344
-
GraphQLsupportsasecondabstracttypecalleda [Uniontype](https://spec.graphql.org/October2021/#sec-Unions). They share similarities with Interface types, but they cannot define any shared fields among the constituent types.
344
+
GraphQLsupportsasecondabstracttypecalleda [Uniontype](https://spec.graphql.org/draft/#sec-Unions). They share similarities with Interface types, but they cannot define any shared fields among the constituent types.
@@ -406,9 +406,9 @@ Note that `name` is still specified on `Starship` because otherwise it wouldn't
406
406
407
407
Most of the examples we've covered on this page demonstrate how Object, Scalar, Enum, Interface, and Union types may be used as _output types_ for the fields in a schema. But we have also seen that field arguments must specify their _input types_.
408
408
409
-
So far, we've only talked about using scalar values (like Enums or String types) as an input type for a field argument. However, you can also easily pass complex objects as arguments using an [Input Object type](https://spec.graphql.org/October2021/#sec-Interfaces), which is the last of named types in GraphQL that we'll explore.
409
+
So far, we've only talked about using scalar values (like Enums or String types) as an input type for a field argument. However, you can also easily pass complex objects as arguments using an [Input Object type](https://spec.graphql.org/draft/#sec-Input-Objects), which is the last of named types in GraphQL that we'll explore.
410
410
411
-
This is particularly valuable in the case of [mutations](https://graphql.org/learn/mutations/), where you might want to pass in a whole object to be created. In SDL, Input Object types look the same as regular Object types, but with the keyword `input` instead of `type`:
411
+
This is particularly valuable in the case of [mutations](/learn/queries/#mutations), where you might want to pass in a whole object to be created. In SDL, Input Object types look the same as regular Object types, but with the keyword `input` instead of `type`:
412
412
413
413
```graphql
414
414
inputReviewInput {
@@ -443,15 +443,15 @@ The fields on an Input Object type can refer to other Input Object types, but yo
443
443
444
444
## Directives
445
445
446
-
In certain instances where field arguments are insufficient or certain common behaviors must be replicated in multiple locations, [directives](https://spec.graphql.org/October2021/#sec-Type-System.Directives) allow us to modify parts of a GraphQL schema or operation by using an `@` character followed by the directive's name.
446
+
In certain instances where field arguments are insufficient or certain common behaviors must be replicated in multiple locations, [directives](https://spec.graphql.org/draft/#sec-Type-System.Directives) allow us to modify parts of a GraphQL schema or operation by using an `@` character followed by the directive's name.
447
447
448
448
_Type system directives_ allow us to annotate the types, fields, and arguments in a schema so that they may be validated or executed differently.
449
449
450
450
<Callouttype="info">
451
451
Directives may also be defined for use in GraphQL operations as _executable directives_. [Read more about executable directives on the Queries page.](/learn/queries/#directives)
452
452
</Callout>
453
453
454
-
The GraphQL specification defines several [built-in directives](https://spec.graphql.org/October2021/#sec-Type-System.Directives.Built-in-Directives). For example, for implementations that support SDL, the `@deprecated` directive will be available to annotate deprecated parts of the schema:
454
+
The GraphQL specification defines several [built-in directives](https://spec.graphql.org/draft/#sec-Type-System.Directives.Built-in-Directives). For example, for implementations that support SDL, the `@deprecated` directive will be available to annotate deprecated parts of the schema:
455
455
456
456
```graphql
457
457
typeUser {
@@ -515,7 +515,7 @@ type Query {
515
515
}
516
516
```
517
517
518
-
InadditiontomakingaGraphQLAPIschema more expressive, descriptions are helpful to client developers because they are available in [introspection queries](https://graphql.org/learn/introspection/) and visible in developer tools such as [GraphiQL](https://github.com/graphql/graphiql).
518
+
InadditiontomakingaGraphQLAPIschema more expressive, descriptions are helpful to client developers because they are available in [introspection queries](/learn/introspection/) and visible in developer tools such as [GraphiQL](https://github.com/graphql/graphiql).
519
519
### Comments
520
520
521
521
Occasionally, you may need to add comments in a schema that do not describe types, fields, or arguments, and are not meant to be seen by clients. In those cases, you can add a single-line comment to SDL by preceding the text with a `#` character:
@@ -556,4 +556,4 @@ To recap what we've learned about schemas and types:
556
556
- Type system directives can be applied to the types, fields, and arguments in a schema to alter how they are validated and executed during a query
557
557
- GraphQL supports schema documentation using type, field, and argument descriptions, and it also supports comments that are ignored by the parser
558
558
559
-
Now that you understand the key features of the type system, you're ready to learn more about how to [query data from a GraphQL API](https://graphql.org/learn/queries/).
559
+
Now that you understand the key features of the type system, you're ready to learn more about how to [query data from a GraphQL API](/learn/queries/).
0 commit comments