Launch GraphOS Studio
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 )

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


A schema describes a 's data types and the relationships between those types. 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 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 . supports this omission.

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

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

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

() 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 to download an schema directly from a endpoint. However, 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

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

Operations (.graphql)

operations are executed against a to fetch or modify data.

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

query MyQuery {

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

11. Write your first subscription
Client Awareness
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy