Add a note about omitting introspection type definitions

[martinbonnin]

There is a similar note

for scalars:

When representing a GraphQL schema using the type system definition language, all built-in scalars 
must be omitted for brevity.

for directives:

When representing a GraphQL schema using the type system definition language any built-in directive 
may be omitted for brevity.

I didn't find anything for introspection types.

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	350a140
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/64cb67c66dd0bd0008766a6f
😎 Deploy Preview	https://deploy-preview-1036--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[benjie]

Typo?

Stale

[IvanGoncharov]

Based on Aug 3th WG discussion: I think we can untangle this change from scalars and direcives by saying that you have two options:

1. Status quo: Query root doesn't have __schema and __type so you shouldn't include Introspection types.
2. Query root has __schema and __type then you should include all the introspection type reachable from those two fields.

We can't tangle it with scalars because currently below is a valid behaviours for scalars:
You print scalars used only by introspection or standard directives even if you omitted those directives. Moreover graphql-js does that and we can't make such documents invalid or broken.

[IvanGoncharov]

However, it creates a slightly different problem since introspection for the Query root type doesn't contain __type and __schema.
So technically you wouldn't be able to convert introspection to SDL with introspection types.

[martinbonnin]

Thanks for circling back on this!

Query root doesn't have __schema and __type so you shouldn't include Introspection types.

That sounds like a short term thing that doesn't have too many implications, I like this :) 👍.

Edit, I'm re-reading myself and I think I got it wrong. I actually want introspection types even if __schema and __type are not present

You print scalars used only by introspection or standard directives even if you omitted those directives.

I'm confused. The spec says:

When representing a GraphQL schema using the type system definition language, all built-in scalars 
must be omitted for brevity.

It's a "must" so my understanding is (in the current form at least), scalar type definitions must never be present in a SDL document?

graphql-js has the printIntrospectionSchema() that (I think) outputs them but it's an exception to the spec?

[benjie]

Feels like we could do this by adding an includeMeta/similar option. We could either go with boolean like includeDeprecated, or we could be more granular to differentiate between whether __typename should or should not be included:

+ enum __IncludeMeta { NONE ALL ALL_EXCEPT_TYPENAME }
  type __Type {
    # ...
    fields(
      includeDeprecated: Boolean = false
+     includeMeta: __IncludeMeta = NONE
    ): [__Field!]

[martinbonnin]

Closing in favor of #1049