Support Descriptions/BlockString from June 2018 GraphQL spec

[ack210]

The June 2018 GraphQL spec states the following regarding descriptions (Source):

To allow GraphQL service designers to easily publish documentation alongside the capabilities of a GraphQL service, GraphQL descriptions are defined using the Markdown syntax (as specified by CommonMark). In the type system definition language, these description strings (often BlockString) occur immediately before the definition they describe.

All GraphQL types, fields, arguments and other definitions which can be described should provide a Description unless they are considered self descriptive.

However, when attempting to provide a schema using BlockStrings for descriptions to AppSync, I receive multiple syntax errors. For example, using the example of a well-described schema from the spec, I receive multiple syntax errors such as "Unexpected string". Deploying from CloudFormation gives a less specific error of "Schema Creation Status is FAILED with details: Failed to parse schema document - ensure it's a valid SDL-formatted document."

[tinnou]

Hello,

Thank you for reporting this. AppSync currently does not support multiline strings comments and I'll make sure the team sees this.

For the time being, the workaround is to use single line comments using the # symbol.
Example:

# Single line comment
# On multiple lines
type Mutation {
	# Put a single value of type 'Post'.
	### If an item exists it's updated. If it does not it's created.
	putPost(id: ID!, title: String!): Post
}

[radman-rt]

Even single line """ descriptions do not work in Amplify -- the built schema.graphql does display them but not the AWS AppSync console. YAAB -- yet another AppSync bug.

[nextdude-mdsol]

It's a little crazy that AppSync still doesn't support the June 2018 GraphQL Spec on this and other things. Comments are supposed to be ignored by a GraphQL processor. Triple and single quoted descriptions are the way to document types, fields, arguments, etc.

Also, & is the required way to separate interfaces that a type implements, yet this also throws errors in AppSync. These issues shouldn't be hard to fix. I'd love to use AppSync, but our generated models, which are spec-compliant, are large and tweaking them to work with AppSync is an unnecessary burden.

[alextriaca]

+1 on this issue. We've worked around it thus far with hash based comments. However we've hit a case now where that doesn't work and there doesn't appear to be any work around. When documenting a field with arguments the argument comments are not returned when querying via graphiql. Below is an example of the schema.graphql:

type Query {
    # This comment is present in the schema and will propagate when queried introspectively
    myField (
       # This comment is present in the schema but does not propagate when queried introspectively
       arg1: String
       "This is not a valid comment but is how it should be allowed" 
       arg2: Int
    }
}

[colin-h]

+1 would love to see this supported.

[jongrubb]

It's a little crazy that AppSync still doesn't support the June 2018 GraphQL Spec on this and other things. Comments are supposed to be ignored by a GraphQL processor. Triple and single quoted descriptions are the way to document types, fields, arguments, etc.

Also, & is the required way to separate interfaces that a type implements, yet this also throws errors in AppSync. These issues shouldn't be hard to fix. I'd love to use AppSync, but our generated models, which are spec-compliant, are large and tweaking them to work with AppSync is an unnecessary burden.

Just got burnt on this. Not only the & is not supported, I have also found while creating an interface you cannot implement from other interfaces with appsync.

interface MyInterface implements AnotherInterface {
...
}

[nextdude-mdsol]

It's a little crazy that AppSync still doesn't support the June 2018 GraphQL Spec on this and other things. Comments are supposed to be ignored by a GraphQL processor. Triple and single quoted descriptions are the way to document types, fields, arguments, etc.
Also, & is the required way to separate interfaces that a type implements, yet this also throws errors in AppSync. These issues shouldn't be hard to fix. I'd love to use AppSync, but our generated models, which are spec-compliant, are large and tweaking them to work with AppSync is an unnecessary burden.

Just got burnt on this. Not only the & is not supported, I have also found while creating an interface you cannot implement from other interfaces with appsync.

interface MyInterface implements AnotherInterface {
...
}

I don't think the GraphQL spec allows interfaces to extend other interfaces, so that's not on AppSync. If you don't mind using a , to separate interfaces, you can work around both of these problems, although not optimally for sure.

[jongrubb]

It's a little crazy that AppSync still doesn't support the June 2018 GraphQL Spec on this and other things. Comments are supposed to be ignored by a GraphQL processor. Triple and single quoted descriptions are the way to document types, fields, arguments, etc.
Also, & is the required way to separate interfaces that a type implements, yet this also throws errors in AppSync. These issues shouldn't be hard to fix. I'd love to use AppSync, but our generated models, which are spec-compliant, are large and tweaking them to work with AppSync is an unnecessary burden.

Just got burnt on this. Not only the & is not supported, I have also found while creating an interface you cannot implement from other interfaces with appsync.
interface MyInterface implements AnotherInterface {
...
}

I don't think the GraphQL spec allows interfaces to extend other interfaces, so that's not on AppSync. If you don't mind using a , to separate interfaces, you can work around both of these problems, although not optimally for sure.

I think you're right on that one...my fault. With apollo server, it allows it and that's what made me assume it was part of the spec. The final schema from apollo server does not show that my interface implements another interface.

[AaronHarris]

Interface implementing another interface

This was actually approved in the GraphQL spec in graphql/graphql-spec#373, however this is a relatively recent change, and it is sill only included in the prerelease, working draft of the spec. I suggest opening up a separate issue to track this.

[billkidwell]

I don't see it mentioned here, but this problem also impacts comments when using GraphQL Transform (gql-compile) from AWS Amplify. See here

A good description of the issue from an integration standpoint is located here.

Although there is a workaround for this issue, I feel it is important to get it resolved. It is a bad user experience to setup a GraphQL API for the first time in Amplify, and immediately have to chase down workarounds to publish the documentation for your APIs.

[piotrmoszkowicz]

That's really strange that AppSync still does not support that... We are using some libraries to combine our .graphql files together and they use """ comment syntax, which doesn't work with AppSync...

[hunterhug]

when support this, my friends?

[trsrm]

+1

[matart15]

Just a few experiments

CDK version : 2.16.0 (build 4c77925)

"comment"            - NOT WORK

"""comment"""        - NOT WORK

"""
comment
"""                 - NOT WORK

# comment
# comment            - WORKS. But starting from second line comment gets displayed BIGGER

[CypherPoet]

I'm seeing the same behavior that @matart15 was mentioning (2.16.0). Support for """-style syntax would be greatly appreciated 👍 .

[v-karbovnichy]

Should this be considered to be taken in scope, given we are almost 4 years from the spec?

[ViniciussSantos]

Any news on this? Almost five years since this feature has been announced, and it's still not supported by AppSync.

[andresionek91]

Any timelines for this?

[pribrahimsari]

Almost passed 5 years, and still does not have support for docstrings ?

[Charlie059]

It's really hard to record API

[cad]

If only there were some blog posts that warned me against this problem. I would chose apollo-server or something else to establish my GraphQL api on top of. I might as well write one.

[ides15]

EDIT - looks like this behavior only occurs when the page is not reloaded when switching from the schema page to the query page, so this is basically useless. Sorry for getting hopes up...

---

It seems like (as of today at least) multi-line comments are possible in the AppSync UI (albeit with the # character, not the """ syntax).

Just treat everything above your type/field as Markdown, i.e. if you want multiline comments, add a newline in between the two lines. And as @matart15 demonstrated above, adding markdown annotations to your comments also works.

# Author of a book.
#
# `givenName` - first name of the author
#
# `surname` - last name of the author
type Author {
	name: String!
}

# Book in a library of books.
type Book {
	ISBN: String!
	title: String!
	author: Author!
}

type Query {
	# List all books in the library
	books: [Book!]!
	# Get a single author by name
	#
	# # This is a large comment
	#
	# `name` - full name of the author
	author(name: String!): Author
}

displays:

[ides15]

If anyone is using GraphQL Eslint and having trouble getting the # syntax to play nicely with the @graphql-eslint/require-description rule - me too 😢. Had to disable the rule for now, but if anyone has a solution please lmk.

[sgrannan]

+1 on this issue. We already have an existing well defined GQL schema and wanted to migrate to AWS Appsync. Our schema includes comments (""") per the GraphQL spec. How is this not solved yet??

I'm literally going to have to spend HOURS taking them out line by line if we want to trial Appsync. This is BS. Follow the spec!!

[aureliomarcoag]

We'd love to be able use docstrings on query arguments. They are supported to an extent in AppSync, in the sense that we can write them and even see them in the Schema editor, but if we introspect the API or use any of the options to export the schema, those docstrings are lost.

Example:

type Query {
	# This query returns a pet
	pets(
		# The ID of the pet to return
		id: ID
	): Pet
}

Exported schema:

type Query {
	# This query returns a pet
	pets(id: ID): Pet
}

As I said, the docstrings are even present when we look at the Schema in the console, so I don't think it's unreasonable to expect them to show up in the exported schema as well.

[PatrykMilewski]

cmon, this is not a rocket science, it's already open for 5 years

[nickydonna]

Any updates on this issue?

[jimmyn]

Hello,

Are there any updates on this issue? Proper documentation of the schema is urgently needed.

[Emesilver]

+1