extend semantic introspection with __coordinates

[PascalSenn]

No description provided.

[Keweiqu]

Okay now I finally understood what this is. I'd recommend calling it __definitions() I keep thinking "__coordinates" should return a list of coordinates.

A controversial take, should we just return SDL string? That's a more concise output format

[martinbonnin]

+1 about changing the name. Maybe __typeSystemDefinitions? Or __schemaMembers if we keep __SchemaMember?

Re: SDL, there was a discussion during the wg about getting applied directives (graphql-spec/#300). SDL would solve that and there is a precedent of __InputValue.defaultValue

[rebello95]

A controversial take, should we just return SDL string? That's a more concise output format

Re: SDL, there was a discussion during the wg about getting applied directives (graphql-spec/#300). SDL would solve that and there is a precedent of __InputValue.defaultValue

Thanks for surfacing this, was going to follow up after the WG meeting 😄
+1 to these suggestions; I've had success with returning the SDL in a similar API for a few reasons (some of which were already stated above):

1. Context/token conservation: Returning an SDL string is significantly more token-efficient than returning a very large JSON blob. This could be worked around by adding an intermediary parsing layer on the client, but I imagine most folks would want to use MCP for this, which means agents would be consuming all of it.
2. LLMs natively understand GraphQL: Agents can easily understand relationships, documentation, semantics, and directives in the native SDL format, whereas they are not natively familiar with this JSON format.
3. All directives are available automatically. Certain directives can influence how queries should be written. For example, if a team uses a custom directive called @canonical to denote a "core" type or field, an engineer writing the query might want the agent to prioritize types/fields with that directive over others, and returning the SDL directly here would allow for that (even with custom directives). Another example would be @oneOf -- if an agent writes a query using semantic introspection then tries to execute it, it'll need to know that @oneOf was present on a given input type in order to synthesize a valid input object to execute the query with.

[martinbonnin]

@rebello95 note that @oneOf isn't a great example because since its a standard directive now, the information is available in introspection. See __Type.isOneOf.

Agree with everything else!