lexicographic_sort_schema is underspecified.

[pmantica1]

First of all thanks for the amazing work in porting the GraphQL reference implementation.

I wanted to compute the fingerprint of a schema by running lexicographic_sort_schema and print_schema then computing the sha256 of the output.
kensho-technologies/graphql-compiler#737

However, it is unclear whether lexicographic_sort_schema modifies the input schema. So I was having trouble documenting my function. Would you mind clarifying the function's spec?

[Cito]

The function takes a schema and returns a new, sorted schema. The input schema should not be modified (otherwise, please file a bug report).

[obi1kenobi]

I suspect that "parse schema -> sort -> print schema" may be a common usage pattern of lexicographic_sort_schema. There may be value in us documenting some of the sharp edges that @pmantica1 uncovered in this pattern, even though lexicographic_sort_schema is not the cause, purely as a nota bene to future users. A couple of examples:

• extend expressions are lost in the parse-print process: Type extension information gets lost when a schema is parsed and printed graphql/graphql-js#2386
• schema directives (e.g. directives used at FIELD_DEFINITION locations in the GraphQL SDL) are lost in the parse-print process: Add a function that computes the fingerprint of a schema kensho-technologies/graphql-compiler#737 (comment) and Add field directives on Info graphql/graphql-js#1789

If you think this is a good idea, @pmantica1 and I can work on a PR adding these notes to the lexicographic_sort_schema docstring.

Thanks again for all the work you've put into this library! Using it has been a pleasure, and I'd love to help in any way I can.

[Cito]

Adding more documentation can never harm. If you think something needs to be improved or discussed more fundamentally, maybe it's a good idea to create a ticket at GraphQL.js. The way how the functions work and the docsstrings are ported from there and it's always best to fix things at the source.

[obi1kenobi]

Thanks! I'll start by opening a ticket in GraphQL.js and see how people feel about the idea of parse-print producing SDL equivalent to the original input, then based on the feedback either write some nota bene documentation or pitch in for any code changes that may be necessary.

[Cito]

Just saw Ivan answered this has already been improved in GraphQL.js 15.0.0-alpha.2. In fact the current master in GraphQL core only has the changes up to 15.0.0-alpha.1. These improvements will probably be ported in the next weeks as I am following up.

[obi1kenobi]

graphql/graphql-js#2389 appears to still be a concern in GraphQL.js 15.0.0-alpha.2.

Also, @pmantica1 and I are happy to pitch in and open PRs to port the GraphQL.js fixes if you'd like any help.

[Cito]

Thank you. I'll go over the new changes in the coming days and let you know if you can help with anything. I'm trying to port every change in order, so this needs some coordination.

[Cito]

Just a small progress report: GraphQL-Core v3.1.0b0 has been released today which is on par with GraphQL.js v15.0.0rc1. But as far as I understand, the problem is not yet fully solved upstream.