Unknown directive "aws_subscribe". invalid-graphql-schema

Looks like v0.2.0 is breaking with custom directives

Unknown directive “aws_subscribe”. invalid-graphql-schema

I can’t see in the documentation how to customize invalid-graphql-schema rule to enable custom directives like @aws_subscribe for AWS AppSync. Is there a way?

type Subscription {
    addedPost: Post
    @aws_subscribe(mutations: ["addPost"])
    updatedPost: Post
    @aws_subscribe(mutations: ["updatePost"])
    deletedPost: Post
    @aws_subscribe(mutations: ["deletePost"])
}

Reference: https://docs.aws.amazon.com/appsync/latest/devguide/real-time-data.html

PS: By the way thank you for you tool 👍 and I suggest you to use git tags and GitHub releases every time you release a new version https://github.com/cjoudrey/graphql-schema-linter/releases

[cjoudrey]

About #171 (comment) I think that adding a specific--aws-appsync edge case to the linter is too specific to AWS.

Agreed, I kinda want to stick with graphql-schema-linter linter/aws_appsync.graphql schema.graphql for now and see how it plays out.

What’s the current workaround

Currently the workaround would be to provide the AWS AppSync type definitions when linting your schema. These definitions can live in a separate file than your schema.

Create a file named aws_appsync.graphql, for example:

# https://docs.aws.amazon.com/appsync/latest/devguide/scalars.html#appsync-defined-scalars

"""
The AWSDate scalar type represents a valid extended ISO 8601 Date string. In other words, this scalar type accepts date strings of the form YYYY-MM-DD. This scalar type can also accept time zone offsets. For example, 1970-01-01Z, 1970-01-01-07:00 and 1970-01-01+05:30 are all valid dates. The time zone offset must either be Z (representing the UTC time zone) or be in the format ±hh:mm:ss. The seconds field in the timezone offset will be considered valid even though it is not part of the ISO 8601 standard.
"""
scalar AWSDate

"""
The AWSTime scalar type represents a valid extended ISO 8601 Time string. In other words, this scalar type accepts time strings of the form hh:mm:ss.sss. The field after the seconds field is a nanoseconds field. It can accept between 1 and 9 digits. The seconds and nanoseconds fields are optional (the seconds field must be specified if the nanoseconds field is to be used). This scalar type can also accept time zone offsets.

For example, 12:30Z, 12:30:24-07:00 and 12:30:24.500+05:30 are all valid time strings.

The time zone offset must either be Z (representing the UTC time zone) or be in the format hh:mm:ss. The seconds field in the timezone offset will be considered valid even though it is not part of the ISO 8601 standard.
"""
scalar AWSTime

"""
The AWSDateTime scalar type represents a valid extended ISO 8601 DateTime string. In other words, this scalar type accepts datetime strings of the form YYYY-MM-DDThh:mm:ss.sssZ. The field after the seconds field is a nanoseconds field. It can accept between 1 and 9 digits. The seconds and nanoseconds fields are optional (the seconds field must be specified if the nanoseconds field is to be used). The time zone offset is compulsory for this scalar. The time zone offset must either be Z (representing the UTC time zone) or be in the format ±hh:mm:ss. The seconds field in the timezone offset will be considered valid even though it is not part of the ISO 8601 standard.
"""
scalar AWSDateTime

"""
The AWSTimestamp scalar type represents the number of seconds that have elapsed since 1970-01-01T00:00Z. Timestamps are serialized and deserialized as numbers. Negative values are also accepted and these represent the number of seconds till 1970-01-01T00:00Z.
"""
scalar AWSTimestamp

"""
The AWSEmail scalar type represents an Email address string that complies with RFC 822. For example, [e-mail] is a valid Email address.
"""
scalar AWSEmail

"""
The AWSJSON scalar type represents a JSON string that complies with RFC 8259.

Maps like {\"upvotes\": 10}, lists like [1,2,3], and scalar values like \"AWSJSON example string\", 1, and true are accepted as valid JSON. They will automatically be parsed and loaded in the resolver mapping templates as Maps, Lists, or Scalar values rather than as the literal input strings. Invalid JSON strings like {a: 1}, {'a': 1} and Unquoted string will throw GraphQL validation errors.
"""
scalar AWSJSON

"""
The AWSURL scalar type represents a valid URL string. The URL may use any scheme and may also be a local URL (Ex: <http://localhost/>). URLs without schemes are considered invalid. URLs which contain double slashes are also considered invalid.
"""
scalar AWSURL

"""
The AWSPhone scalar type represents a valid Phone Number. Phone numbers are serialized and deserialized as Strings. Phone numbers provided may be whitespace delimited or hyphenated. The number can specify a country code at the beginning but this is not required.
"""
scalar AWSPhone

"""
The AWSIPAddress scalar type represents a valid IPv4 or IPv6 address string.
"""
scalar AWSIPAddress

"""
Specify multiple mutations which trigger a subscription.
"""
directive @aws_subscribe(mutations: [String!]!) on FIELD_DEFINITION

Then when running graphql-schema-linter specify this file, for example:

graphql-schema-linter schema/*.graphql aws_appsync.graphql

One problem you might run into is the linter will complain about unused types, for example:

aws_appsync.graphql
8:1  The type `AWSTime` is defined in the schema but not used anywhere.       defined-types-are-used

I would comment out the types you don’t use. This isn’t great, but it works for now.

[cjoudrey]

Hi @yvele, thanks for the feedback and opening this issue. 😄

This is an interesting issue. Have you considered including a directive definition at the top of your schema or in a separate file? Something like this:

directive @aws_subscribe(mutations: [String!]!) on FIELD_DEFINITION

By doing this, the linter error would go away and your schema would be complete which might make it easier for someone new to add a @aws_subscribe elsewhere.

In an ideal world, it would be great if AWS AppSync provided an SDL file with all the custom directives it supports, that way you could either extend the schema with it or simply pass both files to graphql-schema-linter.

An alternative solution would be to customize invalid-graphql-schema as you suggested, but I’m hesitant because it encourages people to write incomplete schemas.

Any further thoughts?

and I suggest you to use git tags and GitHub releases every time you release a new version

👍 That’s a great point. I completely forgot to do this since the beginning. 😢I’ll see if I can retroactively create them based on commit data. In the meantime, CHANGELOG.md might be helpful.

Edit: I’ve started re-adding them retroactively. Thanks for calling this out. 😄