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, mutations, and subscriptions)

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

Schemas

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

Introspection schemas (.json)

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

1{
2  "data": {
3    "__schema": {
4      "queryType": {
5        "name": "Query"
6      },
7      "mutationType": {
8        "name": "Mutation"
9      },
10      "types": [...]
11    }
12  }
13}

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

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

1./gradlew :app:downloadApolloSchema \
2  --endpoint "https://example.com/graphql" \
3  --schema schema.json

JSON introspection schemas 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)

SDL (Schema Definition Language) 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 schema's structure. It also supports directives, unlike the JSON representation (see this issue):

1type schema {
2  query: Query
3  mutation: Mutation
4}
5
6type Query {
7  field: String @deprecated
8  ...
9}

You can't use introspection to download an SDL schema 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:

1./gradlew :app:downloadApolloSchema \
2  --endpoint "https://example.com/graphql" \
3  --schema schema.graphqls

Apollo Kotlin also supports the .sdl file extension for SDL schemas, 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, operation files use the .graphql (without 's') extension. These files only contain executable definitions (queries, mutations, subscriptions, and/or fragments):

1query MyQuery {
2  field1
3  field2
4  ...
5}

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