graphql / graphql/graphql-spec

Explicitly state in spec that full introspection output is equivalent to full SDL document

Open
#864 9 comments 2 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
14.6k
Forks
1.2k
PR merge metrics
No merged PRs in 30d

Description

(for the next spec version)

## Suggested change
State explicitly (probably in Introspection section) that **information set available through Introspection API is equivalent (no less, no more) to SDL schema document.** These are two information channels for the same information set, but for different 'audiences': SDL doc is for humans, Introspection for tools. There is no reason why infoset should be different.

But it is, currently. For example, directives are allowed on type fields, but there is no Directives collection on __Field intro type. This is a subject of discussion in issue #300, although the problem there is formulated about availability of extra metadata - is it good or not. Regardless of this metadata question, the real problem and resolution should be (in my opinion) about EQUIVALENCY of infosets.

Interestingly, in this thread @benjie clearly states:
_Everything that's representable via introspection should be representable via the GraphQL IDL and vice-versa._
link: https://github.com/graphql/graphql-spec/issues/300#issuecomment-716590195

If it should, then it should. Should be stated and implemented. **The Intro API should be examined and all missing info should be added** - I speculate here, but think we have shortage on Intro side, not the other way around.

## Possible objections
Possibly break clients. This is not valid in my opinion. First, it is adding info (I think/speculate), and this should never break clients - they should be forgiving, and just ignore any extra stuff by default. Secondly, client dev teams will have plenty of time to prepare using spec drafts.

I volunteer to drive this issue if initial consensus is reached to go forward.

## Why it is important
First, It makes total sense, adds clarity and consistency to the spec and API.
As a maker of GraphQL server framework, and at the same time app developer, I think this is important. As an example, I plan to add a custom **maxLen(n)** directive on fields, so that client UI form can request it at Form initialization and properly setup UI control, instead of having it hard-coded - so directives on fields should be available through Intro.

As other consequence, that addition resolves the discussions about primary source of truth, or questions about server-side only or 'private' directives that are there in SDL but not in introspection. There's should be no such thing as private directives - if it is there - it is in both places and that's it.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.