Launch GraphOS Studio

GraphQL file types in Apollo Kotlin

Apollo Kotlin supports the following file types for GraphQL definitions:

  • .json for introspection schemas
  • .graphqls for SDL schemas
  • .graphql for operations (queries, s, and s)

To learn more about s, see the blog post about support in Apollo Kotlin.


A GraphQL schema describes a graph's data types and the relationships between those types. Apollo Kotlin supports JSON s obtained via introspection, along with conventional SDL schemas.

Introspection schemas (.json)

You can obtain a GraphQL server's via a special introspection query (assuming the server enables ). Like any other GraphQL server response, the returned is provided as JSON similar to the following:

"data": {
"__schema": {
"queryType": {
"name": "Query"
"mutationType": {
"name": "Mutation"
"types": [...]

Some JSON s omit the top-level data . Apollo Kotlin supports this omission.

Tools like Apollo Sandbox introspect a GraphQL server automatically and enable you to download its in JSON (or ) format. Apollo Kotlin can also download an introspected schema with the downloadApolloSchema Gradle task:

./gradlew :app:downloadApolloSchema \
--endpoint "" \
--schema schema.json

JSON s are verbose and difficult to read or modify. For simplicity, you should consider JSON schemas read-only and convert them to SDL schemas if you need to make changes.

SDL schemas (.graphqls)

() is the canonical language for defining GraphQL schemas as defined in the GraphQL spec. It's much cleaner and more expressive than JSON for understanding a 's structure. It also supports s, unlike the JSON representation (see this issue):

type schema {
query: Query
mutation: Mutation
type Query {
field: String @deprecated

You can't use to download an directly from a GraphQL endpoint. However, Apollo Kotlin can convert an introspection schema to SDL automatically if you specify the .graphqls extension in the --schema option:

./gradlew :app:downloadApolloSchema \
--endpoint "" \
--schema schema.graphqls

Apollo Kotlin also supports the .sdl file extension for s, but very few other tools use .sdl. You should use .graphqls moving forward.

Operations (.graphql)

GraphQL operations are executed against a graph to fetch or modify data.

In Apollo Kotlin, files use the .graphql (without 's') extension. These files only contain executable definitions (queries, s, s, and/or s):

query MyQuery {

Apollo Kotlin compiles these s into type-safe models that you can use at runtime.

11. Write your first subscription
Client Awareness
Edit on GitHubEditForumsDiscord