Maven GraphQL Schema Exploration Language

Table of contents

• Introduction
• Kobby Pattern
• GSEL query syntax
  • Schema Query
    • <type/>
  • Operation Query
    • <include/>
    • <exclude/>
  • Type Query
    • <enumValue/>
    • <field/>
    • <anyOverriddenField/>
    • <dependency/>
    • <subTypeDependency/>
    • <superTypeDependency/>
    • <argumentDependency/>
    • <transitiveDependency/>
    • <minWeight/>
    • <maxWeight/>

Introduction

The GraphQL Schema Exploration Language (GSEL) was developed to enable searching for fields in various GraphQL types based on a set of conditions. The Kobby plugin uses this language to truncate GraphQL schemas before generating DSL, as well as to serve as a GraphQL schema analysis tool.

Queries in this language look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation=
                 "http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <build>
        <plugins>
            <plugin>
                <groupId>io.github.ermadmi78</groupId>
                <artifactId>kobby-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>generate-kotlin</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <schema>
                        <analyze>
                            <queries>
                                <query>
                                    <!-- Select values 'COMEDY' and 'HORROR' -->
                                    <!-- in the 'Genre' enumeration -->
                                    <type>Genre</type>
                                    <include>
                                        <enumValue>COMEDY|HORROR</enumValue>
                                    </include>
                                </query>
                                <query>
                                    <!-- Select all 'Query' type fields -->
                                    <!-- except 'film' and 'films' -->
                                    <type>__query</type>
                                    <exclude>
                                        <field>film|films</field>
                                    </exclude>
                                </query>
                                <query>
                                    <!-- Select all 'Mutation' type fields -->
                                    <!-- where one of the argument types is `FilmInput` -->
                                    <type>__mutation</type>
                                    <include>
                                        <argumentDependency>FilmInput</argumentDependency>
                                    </include>
                                </query>
                                <query>
                                    <!-- For any type -->
                                    <!-- select all fields of type 'Country' or 'Film' -->
                                    <type>__any</type>
                                    <include>
                                        <dependency>Country|Film</dependency>
                                    </include>
                                </query>
                            </queries>
                        </analyze>
                    </schema>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Kobby Pattern

The GSEL query uses the Kobby pattern matching tool to find target types or fields. The Kobby pattern syntax is as follows: ↑

• ? - matches one character.
• * - matches zero or more characters.
• | - OR operator.
• __query - alias for Query type.
• __mutation - alias for Mutation type.
• __subscription - alias for Subscription type.
• __root - alias for Query, Mutation and Subscription types.
• __any - alias for any type in the GraphQL schema.
• __anyScalar - alias for any scalar in the GraphQL schema.
• __anyObject - alias for any object in the GraphQL schema.
• __anyInterface - alias for any interface in the GraphQL schema.
• __anyUnion - alias for any union in the GraphQL schema.
• __anyEnum - alias for any enum in the GraphQL schema.
• __anyInput - alias for any input object in the GraphQL schema.

For example:

<query>
    <type>__root|Actor*</type>
    <include>
        <argumentDependency>__anyEnum|Film*</argumentDependency>
    </include>
</query>

GSEL query syntax

The GSEL query consists of 3 parts: ↑

1. Schema Query part — responsible for searching types in a GraphQL schema.
2. Operation Query part — responsible for applying the type subquery to the target GraphQL type (include and exclude operations).
3. Type Query part — responsible for selecting fields in the target GraphQL type.

<queries>
    <query>
        <type>Actor</type> <!-- Schema Query part -->
        <include> <!-- Operation Query part -->
            <dependency>Country</dependency> <!-- Type Query part -->
        </include>
    </query>
</queries>

The GSEL query may contain multiple schema queries. In this case, the schema queries conditions are combined using the "or" operator:

<!-- Find the fields in the "Actor" type or in the "Movie" type -->
<queries>
    <query>
        <type>Actor</type>
        <include>
            <dependency>Country</dependency>
        </include>
    </query>
    <query>
        <type>Film</type>
        <include>
            <dependency>Country</dependency>
        </include>
    </query>
</queries>

To simplify this query, you can use the Kobby Pattern:

<queries>
    <query>
        <type>Actor|Film</type>
        <include>
            <dependency>Country</dependency>
        </include>
    </query>
</queries>

Schema Query

The part of the query that is responsible for selecting the GraphQL types in which to look for fields. ↑

Select type by pattern

<type>pattern</type> ↑

Apply the operation subquery to all types in the GraphQL schema that match the pattern.

<query>
    <!-- Schema Query -->
    <type>Actor</type>

    <!-- Operation subquery -->
    <include/>
    <exclude/>
</query>

Operation Query

The part of the query responsible for applying the type subquery to the target GraphQL type. ↑

An "Operation Query" contains both include and exclude operation. The exclude operation excludes all fields that match the include operation from the query result. If the include operation is not specified, the "include all" operation is assumed to apply.

For example, this query will find all fields of type Film in the Query type and exclude the field named "films" from the query results.

<query>
    <type>__query</type>
    <include>
        <dependency>Film</dependency>
    </include>
    <exclude>
        <field>films</field>
    </exclude>
</query>

Include operation

<include/> ↑

Apply the type subquery to a target GraphQL type. Put fields of the target type that match the subquery into the query result.

<query>
    <type>Actor</type>
    <include>
        <!-- Type subquery -->
    </include>
</query>

Exclude operation

<exclude/> ↑

Apply the type subquery to a target GraphQL type. Put fields of the target type that do not match the subquery into the query result.

<query>
    <type>Actor</type>
    <exclude>
        <!-- Type subquery -->
    </exclude>
</query>

Type Query

The part of the query that is responsible for selecting fields in the target GraphQL type. ↑

A "Type Query" may contain multiple conditions. In this case, the conditions are combined using the "or" operator:

<query>
    <type>__query</type> <!-- For type Query  -->
    <include> <!-- include -->
        <!-- a fields named "country" or "countries" -->
        <field>country|countries</field>

        <!-- or fields of type "Film" or "Actor" -->
        <dependency>Film|Actor</dependency> <!-- -->
    </include>
</query>

Select enum value by pattern

<enumValue>pattern</enumValue> ↑

Select enum values whose name matches the pattern.

<query>
    <type>Genre</type>
    <exclude>
        <enumValue>DRAMA|COMEDY</enumValue>
    </exclude>
</query>

Select field by pattern

<field>pattern</field> ↑

Select fields whose name matches the pattern.

<query>
    <type>__query</type>
    <include>
        <field>country|countries</field>
    </include>
</query>

Select any overridden field

<anyOverriddenField>true</anyOverriddenField> ↑

Select fields that override any fields from the supertype.

<query>
    <type>Actor</type>
    <include>
        <anyOverriddenField>true</anyOverriddenField>
    </include>
</query>

Select dependency by pattern

<dependency>pattern</dependency> ↑

Select fields whose type matches the pattern.

<query>
    <type>__query</type>
    <include>
        <dependency>Film|Actor</dependency>
    </include>
</query>

Select subtype dependency by pattern

<subTypeDependency>pattern</subTypeDependency> ↑

Select fields where one of the subtypes matches the pattern.

<query>
    <type>__any</type>
    <include>
        <subTypeDependency>Film|Actor</subTypeDependency>
    </include>
</query>

Select supertype dependency by pattern

<superTypeDependency>pattern</superTypeDependency> ↑

Select fields where one of the supertypes matches the pattern.

<query>
    <type>__any</type>
    <include>
        <superTypeDependency>Taggable|Native</superTypeDependency>
    </include>
</query>

Select argument dependency by pattern

<argumentDependency>pattern</argumentDependency> ↑

Select fields where one of the argument types matches the pattern.

<query>
    <type>__mutation</type>
    <include>
        <argumentDependency>ActorInput|FilmInput</argumentDependency>
    </include>
</query>

Select transitive dependency by pattern

<transitiveDependency>pattern</transitiveDependency> ↑

Select fields where one of the transitive dependencies matches the pattern.

The transitive dependencies of a GraphQL field are all types (except scalars) returned by a query on that field, as well as the types of the field's arguments.

<query>
    <type>__any</type>
    <include>
        <transitiveDependency>Tag</transitiveDependency>
    </include>
</query>

Select fields whose weight at least the minimum weight

<minWeight>minWeight</minWeight> ↑

Select fields whose weight is greater than or equal to the minWeight param.

The weight of a GraphQL type is the number of types (excluding scalars) that are available for querying on a field that returns the given type.

The weight of a GraphQL field is the weight of its type plus the weights of the types of its arguments.

<query>
    <type>__mutation</type>
    <include>
        <minWeight>9</minWeight>
    </include>
</query>

Select fields whose weight not greater than the maximum weight

<maxWeight>maxWeight</maxWeight> ↑

Select fields whose weight is less than or equal to the maxWeight param.

The weight of a GraphQL type is the number of types (excluding scalars) that are available for querying on a field that returns the given type.

The weight of a GraphQL field is the weight of its type plus the weights of the types of its arguments.

<query>
    <type>__mutation</type>
    <include>
        <maxWeight>9</maxWeight>
    </include>
</query>