GraphQL Descriptions
Last updated on 03 April, 2024
Our schema (if merged) is more than 20 000 lines and we have many teams depending on our GraphQL platform. I’ll tell you how GraphQL descriptions are helping us scale our schema.
If you prefer video version, I've made YouTube video covering the topic.
GraphQL does self-documentation out of the box. In GraphiQL, which is an integrated IDE for GraphQL available in browsers, users of your GraphQL API can read on how fields are named and what types they have.
When your schema grows, the naming of fields and their use case become unclear. As a person who doesn’t understand much in domain, can you differentiate product from productView ? Or a product from simpleProduct ? It happens that one set of fields is optimized more for one fetching path. What if your users don’t have that tribal knowledge? What can help them onboard faster?
You can leverage GraphQL's descriptions to help you.
GraphQL descriptions are like doc strings for your fields. When you’d do introspection to your GraphQL server, you’d see that those doc strings become description values for your fields in introspection JSON.
Result Demo where we can see descriptions in JSON response and GraphiQL
curl --location 'http://localhost:4000/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"{\n __schema {\n types {\n name\n description\n fields {\n name\n description\n }\n }\n \n }\n}","variables":{}}' | jq .
Introspection Request for our GraphQL Schema
{
"data": {
"__schema": {
"types": [
{
"name": "Query",
"description": "Query Root doesn't require description.",
"fields": [
{
"name": "complexTypeField",
"description": "complexTypeField is generic type and used by both web and mobile. Dangerous to change. Consult with team \"A\" before making any changes."
}
]
},
{
"name": "ComplexType",
"description": "ComplexType is a generic type and used by both web and mobile. Dangerous to change. Consult with team \"A\" before making any changes.",
"fields": [
{
"name": "id",
"description": "id is unique identifier for ComplexType. Example: `id-123:web`"
},
{
"name": "name",
"description": "name is name of the ComplexType. Example: `ComplexObject`"
},
{
"name": "description",
"description": "description is description of the ComplexType. Example: `This is a complex type`"
},
{
"name": "nestedTypeField",
"description": "Dangerous to change. Consult with team \"B\" before making any changes."
}
]
},
{
"name": "ID",
"description": "The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"4\"`) or integer (such as `4`) input value will be accepted as an ID.",
"fields": null
},
{
"name": "String",
"description": "The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.",
"fields": null
},
{
"name": "NestedType",
"description": "NestedType is a generic type and used by both web and mobile. Dangerous to change. Consult with team \"B\" before making any changes.",
"fields": [
{
"name": "id",
"description": "id is unique identifier for NestedType. Example: `id-123:web`"
},
{
"name": "name",
"description": "name is name of the NestedType. Example: `NestedObject`"
},
{
"name": "description",
"description": "description is description of the NestedType. Example: `This is a nested type`"
}
]
},
{
"name": "Boolean",
"description": "The `Boolean` scalar type represents `true` or `false`.",
"fields": null
},
{
"name": "__Schema",
"description": "A GraphQL Schema defines the capabilities of a GraphQL server. It exposes all available types and directives on the server, as well as the entry points for query, mutation, and subscription operations.",
"fields": [
{
"name": "description",
"description": null
},
{
"name": "types",
"description": "A list of all types supported by this server."
},
{
"name": "queryType",
"description": "The type that query operations will be rooted at."
},
{
"name": "mutationType",
"description": "If this server supports mutation, the type that mutation operations will be rooted at."
},
{
"name": "subscriptionType",
"description": "If this server support subscription, the type that subscription operations will be rooted at."
},
{
"name": "directives",
"description": "A list of all directives supported by this server."
}
]
},
{
"name": "__Type",
"description": "The fundamental unit of any GraphQL Schema is the type. There are many kinds of types in GraphQL as represented by the `__TypeKind` enum.\n\nDepending on the kind of a type, certain fields describe information about that type. Scalar types provide no information beyond a name, description and optional `specifiedByURL`, while Enum types provide their values. Object and Interface types provide the fields they describe. Abstract types, Union and Interface, provide the Object types possible at runtime. List and NonNull types compose other types.",
"fields": [
{
"name": "kind",
"description": null
},
{
"name": "name",
"description": null
},
{
"name": "description",
"description": null
},
{
"name": "specifiedByURL",
"description": null
},
{
"name": "fields",
"description": null
},
{
"name": "interfaces",
"description": null
},
{
"name": "possibleTypes",
"description": null
},
{
"name": "enumValues",
"description": null
},
{
"name": "inputFields",
"description": null
},
{
"name": "ofType",
"description": null
}
]
},
{
"name": "__TypeKind",
"description": "An enum describing what kind of type a given `__Type` is.",
"fields": null
},
{
"name": "__Field",
"description": "Object and Interface types are described by a list of Fields, each of which has a name, potentially a list of arguments, and a return type.",
"fields": [
{
"name": "name",
"description": null
},
{
"name": "description",
"description": null
},
{
"name": "args",
"description": null
},
{
"name": "type",
"description": null
},
{
"name": "isDeprecated",
"description": null
},
{
"name": "deprecationReason",
"description": null
}
]
},
{
"name": "__InputValue",
"description": "Arguments provided to Fields or Directives and the input fields of an InputObject are represented as Input Values which describe their type and optionally a default value.",
"fields": [
{
"name": "name",
"description": null
},
{
"name": "description",
"description": null
},
{
"name": "type",
"description": null
},
{
"name": "defaultValue",
"description": "A GraphQL-formatted string representing the default value for this input value."
},
{
"name": "isDeprecated",
"description": null
},
{
"name": "deprecationReason",
"description": null
}
]
},
{
"name": "__EnumValue",
"description": "One possible value for a given Enum. Enum values are unique values, not a placeholder for a string or numeric value. However an Enum value is returned in a JSON response as a string.",
"fields": [
{
"name": "name",
"description": null
},
{
"name": "description",
"description": null
},
{
"name": "isDeprecated",
"description": null
},
{
"name": "deprecationReason",
"description": null
}
]
},
{
"name": "__Directive",
"description": "A Directive provides a way to describe alternate runtime execution and type validation behavior in a GraphQL document.\n\nIn some cases, you need to provide options to alter GraphQL's execution behavior in ways field arguments will not suffice, such as conditionally including or skipping a field. Directives provide this by describing additional information to the executor.",
"fields": [
{
"name": "name",
"description": null
},
{
"name": "description",
"description": null
},
{
"name": "isRepeatable",
"description": null
},
{
"name": "locations",
"description": null
},
{
"name": "args",
"description": null
}
]
},
{
"name": "__DirectiveLocation",
"description": "A Directive can be adjacent to many parts of the GraphQL language, a __DirectiveLocation describes one such possible adjacencies.",
"fields": null
}
]
}
}
}Types we define have 'description' attribute
Our reference GraphQL server set up
Base, minimalistic set up for GraphQL API server.
import express from "express";
import fs from "fs";
import { graphqlHTTP } from "express-graphql";
import {
buildSchema,
} from "graphql";
function loadSchemaFile(): string {
const content = fs.readFileSync("./schema.gql", "utf8");
return content;
}
const schemaString = loadSchemaFile();
const schema = buildSchema(schemaString);
// The root provides a resolver function for each API endpoint
const root = {};
const getAppServer = () => {
const app = express();
app.use(
"/graphql",
graphqlHTTP({
schema: schema,
graphiql: true,
rootValue: root,
validationRules: [],
})
);
return app;
};
if (require.main === module) {
const app = getAppServer();
app.listen(4000);
console.log("Running a GraphQL API server at http://localhost:4000/graphql");
}index.ts
type Query schema.gql
How to add GraphQL descriptions
type Query {
"""
complexTypeField is generic type and used by both web and mobile. Dangerous to change. Consult with team "A" before making any changes.
"""
complexTypeField: ComplexType
}
type ComplexType {
"""
id is unique identifier for ComplexType. Example: `id-123:web`
"""
id: ID!
"""
name is name of the ComplexType. Example: `ComplexObject`
"""
name: String!
"""
description is description of the ComplexType. Example: `This is a complex type`
"""
description: String
"""
Dangerous to change. Consult with team "B" before making any changes.
"""
nestedTypeField: NestedType
}
type NestedType {
"""
id is unique identifier for NestedType. Example: `id-123:web`
"""
id: ID!
"""
name is name of the NestedType. Example: `NestedObject`
"""
name: String!
"""
description is description of the NestedType. Example: `This is a nested type`
"""
description: String
}
fields with descriptions in your schema.gql
You can also add documentation for your types if you need that.
"""
Query Root doesn't require description.
"""
type Query {
"""
complexTypeField is generic type and used by both web and mobile. Dangerous to change. Consult with team "A" before making any changes.
"""
complexTypeField: ComplexType
}
"""
ComplexType is a generic type and used by both web and mobile. Dangerous to change. Consult with team "A" before making any changes.
"""
type ComplexType {
"""
id is unique identifier for ComplexType. Example: `id-123:web`
"""
id: ID!
"""
name is name of the ComplexType. Example: `ComplexObject`
"""
name: String!
"""
description is description of the ComplexType. Example: `This is a complex type`
"""
description: String
"""
Dangerous to change. Consult with team "B" before making any changes.
"""
nestedTypeField: NestedType
}
"""
NestedType is a generic type and used by both web and mobile. Dangerous to change. Consult with team "B" before making any changes.
"""
type NestedType {
"""
id is unique identifier for NestedType. Example: `id-123:web`
"""
id: ID!
"""
name is name of the NestedType. Example: `NestedObject`
"""
name: String!
"""
description is description of the NestedType. Example: `This is a nested type`
"""
description: String
}
we can cover types with descriptions in schema.gql
Quite simple and very fast to implement. Do you already have that in your system? Let me know in the comments.
You can subscribe on my newsletters
Let's see if we can become internet friends.