aws / aws/aws-appsync-community

Support Descriptions/BlockString from June 2018 GraphQL spec

Open
#38 33 comments 78 reactions 0 assignees View on GitHub
bug
Dominant language
HTML
Stars
507
Forks
37
PR merge metrics
No merged PRs in 30d

Description

The June 2018 GraphQL spec states the following regarding descriptions ([Source](https://graphql.github.io/graphql-spec/June2018/#sec-Descriptions)):

> 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](https://graphql.github.io/graphql-spec/June2018/#example-64e5a) 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."

![Screenshot from 2019-07-06 14-37-04](https://user-images.githubusercontent.com/5232630/60759993-a415a380-9ffb-11e9-8ef4-15d6b887d397.png)

Contributor guide

Open the contributing guide

Research direction

Start by reading the linked June 2018 GraphQL specification section and its well-described schema example, then reproduce the BlockString parsing errors in AWS AppSync, including through CloudFormation. Done means AppSync accepts valid description BlockStrings without the reported syntax or schema-creation errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, graphql
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.