graphql-introspection-model

Types for GraphQL introspection model. Used by graphql-sdl-exporter.

A GraphQL server supports introspection over its schema. This schema is queried using GraphQL itself, creating a powerful platform for tool‐building.

Here's what a "classic" introspection query looks like:

query IntrospectionQuery {
  __schema {
    queryType { name }
    mutationType { name }
    subscriptionType { name }
    types {
      ...FullType
    }
    directives {
      name
      description
      locations
      args {
        ...InputValue
      }
    }
  }
}

fragment FullType on __Type {
  kind
  name
  description
  fields(includeDeprecated: true) {
    name
    description
    args {
      ...InputValue
    }
    type {
      ...TypeRef
    }
    isDeprecated
    deprecationReason
  }
  inputFields {
    ...InputValue
  }
  interfaces {
    ...TypeRef
  }
  enumValues(includeDeprecated: true) {
    name
    description
    isDeprecated
    deprecationReason
  }
  possibleTypes {
    ...TypeRef
  }
}

fragment InputValue on __InputValue {
  name
  description
  type { ...TypeRef }
  defaultValue
}

fragment TypeRef on __Type {
  kind
  name
  ofType {
    kind
    name
    ofType {
      kind
      name
      ofType {
        kind
        name
        ofType {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
              ofType {
                kind
                name
              }
            }
          }
        }
      }
    }
  }
}

The result of this query (like all other GraphQL queries) is JSON. You can deal with it directly or deserialize it into some data structures. Such data structures are provided by this repository. The top level type is GraphQLResponse. After deserialization JSON into the GraphQLResponse (or after creating GraphQLSchema in any other way), it can be transformed into AST representation and then printed by SDLPrinter from GraphQL-Parser nuget package.

Example of deserializing introspection response

using System.Text.Json;

string text = ...; // from HTTP introspection response
var response = JsonSerializer.Deserialize<GraphQLResponse>(text, new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true,
    Converters = { new JsonStringEnumConverter() }
});
var schema = response.Data.__Schema; // note that Data may be null, so check response.Errors 

Example of printing GraphQLSchema into SDL

GraphQLSchema schema = ...;

var converter = new ASTConverter();
var document = converter.ToDocument(schema);
var printer = new SDLPrinter(options);
var sdl = printer.Print(document);

// or use one-line extension method
var sdl = schema.Print();

GraphQL has its own language to write GraphQL schemas, SDL - Schema Definition Language. SDL is simple and intuitive to use while being extremely powerful and expressive. Some examples of SDL documents can be found in graphql-sdl-exporter project.

Many types in this project implement the IHasDirectives interface. It serves to obtain information about the directives applied to the element. The official specification does not describe such a possibility, although discussions are underway to expand the specification to add this feature. graphql-sdl-exporter can get information about directives if the server supports this feature.

Variations of introspection query

This repo provides 4 variations of introspection query:

1. Classic - "classic" introspection query provided above (without exposing applied directives). It conforms to the latest release version of the spec.

2. ClassicDraft - the same as "classic" + deprecations for input values. See PR for more info. It conforms to the prerelease (working draft) version of the spec.

3. Modern - modified "classic" introspection query, in which the directives applied to the schema elements are exposed. It requires GraphQL server to support this feature. See GraphQL.NET as an example of such a server.

4. ModernDraft - the same as "modern" + deprecations for input values. This is the most advanced query among all available.