How do I add a description to a field in “GraphQL schema language”

Question

I have a graphql schema, a fragment of which looks like this:

type User {
    username: String!
    password: String!
}

In graphiql, there is a description field, but it always says “self-descriptive”. How do I add descriptions to the schema?

PS hash your passwords kids!

– derekdreery

Oct 11, 2016 at 7:55 — Oct 11, 2016 at 7:55

Trevor 11.1k2 gold badges33 silver badges40 bronze badges · Accepted Answer · 2018-04-24 10:36:01Z

If you’re using GraphQL.js version 0.7.0 or above, you can simply add a comment directly before the field, type, or argument you want to describe. For example:

# A type that describes the user
type User {
     # The user's username, should be typed in the login field.
     username: String!
     # The user's password.
     password: String!
}

Below version 0.7.0 it is not possible to add descriptions inside the schema language.

UPDATE: since version v0.12.3 you should use string literals

"""
A type that describes the user. Its description might not 
fit within the bounds of 80 width and so you want MULTILINE
"""
type User {
     "The user's username, should be typed in the login field."
     username: String!
     "The user's password."
     password: String!

}

This is no longer the default, see: github.com/graphql/graphql-js/blob/master/src/utilities/… — should be a string literal like "My description" — Jan 10, 2018 at 1:05
So string literals are the current default as of February 2018. — Feb 23, 2018 at 7:11
Relevant part of spec: graphql.github.io/graphql-spec/June2018/#sec-Descriptions — Apr 15, 2019 at 12:35
If anybody is looking for how to do it in TypeGraphQL, just use the description property in decorator options. eg. @ObjectType({description:'Here'}). Same for @Field({description:...}, @Arg and @Query — user10706046, Sep 11, 2019 at 10:56

Josh BlackJosh Black 9892 gold badges8 silver badges16 bronze badges · Accepted Answer · 2016-10-10 17:29:45Z

This is a great question! And actually has a great history in graphql world.

There were multiple issues, discussions, and Pull Requests on the graphql-js repo that tried to discuss possible syntax for this, as it was something that a lot of members of the community felt were needed. Thanks to Lee Byron and this Pull Request, we can actually add descriptions to a schema language by using traditional comments.

For example,

// Grab some helpers from the `graphql` project
const { buildSchema, graphql } = require('graphql');

// Build up our initial schema
const schema = buildSchema(`
schema {
  query: Query
}

# The Root Query type
type Query {
  user: User
}

# This is a User in our project
type User {
  # This is a user's name
  name: String!

  # This is a user's password
  password: String!
}
`);

And, if we’re using graphql that’s newer than 0.7.0, the comments are actually turned into the description for the fields or types. We can verify this by running an introspection query on our schema:

const query = `
{
  __schema {
    types {
        name
        description,
        fields {
            name
            description
        }
    }
  }
}
`;

graphql(schema, query)
  .then((result) => console.log(result));

Which would give us a result that looks like:

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "User",
          "description": "This is a User in our project",
          "fields": [
            {
              "name": "name",
              "description": "This is a user's name"
            },
            {
              "name": "password",
              "description": "This is a user's password"
            }
          ]
        },
      ]
    }
  }
}

And shows us that the # comments were incorporated as the descriptions for the fields/comments that we put them on.

Hope that helps!

Very helpful thanks – I did search for a long time for an answer, and was struggling through lots of old issues – when the answer was so simple! 🙂 — Oct 11, 2016 at 8:03
I'm using graphql 0.12.3 and this isn't working for me. Description is always null using the code above. — Jan 10, 2018 at 1:00

FabianFabian 3,1803 gold badges26 silver badges32 bronze badges · Accepted Answer · 2018-01-29 20:30:08Z

In case you’re using a Java implementation ….

For graphql-java version 7.0 (the latest version as of this writing) with a schema first approach, you can use comments above the field, type, or argument.

String literals are not valid syntax as of version 7.0.

How do I add a description to a field in “GraphQL schema language”