Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free
You're viewing documentation for an upcoming version of this software. Switch to the latest stable version.

GraphQL file types in Apollo Kotlin

supports the following file types for definitions:

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


A GraphQL schema describes a '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 's schema via a special introspection query (assuming the server enables ). Like any other GraphQL server response, the returned schema is provided as JSON similar to the following:

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

Some JSON schemas 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 schema in JSON (or SDL) format. Apollo Kotlin can also download an introspected schema with the downloadApolloSchema Gradle task:

./gradlew :app:downloadApolloSchema \
--endpoint "" \
--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 () is the canonical language for defining as defined in the GraphQL spec. It's much cleaner and more expressive than JSON for understanding a schema's structure. It also supports , unlike the JSON representation (see this issue):

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

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:

./gradlew :app:downloadApolloSchema \
--endpoint "" \
--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, files use the .graphql (without 's') extension. These files only contain executable definitions (queries, mutations, subscriptions, and/or ):

query MyQuery {

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

11. Write your first subscription
Client Awareness
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy