Naming conventions for GraphQL schema

When you build a GraphQL API with Hasura, the GraphQL Engine automatically generates names for the GraphQL schema objects.

Starting with Hasura v2.8.0, you can customize the name of fields, types, and arguments.

Why would you customize the names? In certain use cases, one Hasura application might have multiple databases. With the "naming convention" feature, you can:

• group together all fields belonging to a database
• solve conflicts with existing GraphQL objects
• easily identify fields & types of a particular database

There are 2 naming conventions available - hasura-default and graphql-default. By default, Hasura applications use the hasura-default naming convention.

This article will help you get started with the "naming convention" feature.

How to enable the Naming Convention feature

The "naming convention" feature is experimental, meaning that you need to enable it in the "Env vars" section from your Hasura project settings.

After adding the env variable, navigate to the "Data Manager" page and click on the "Edit" button from your chosen database (in case you have multiple databases).

Then scroll until you see the "GraphQL Field Customization" field. Click on it to expand the section.

In the new section, you can choose a different naming convention and customize the root & type names.

Try it out via Hasura

This article uses a Hasura application with 2 databases. The first database holds information about users and their notes. The second database stores private notes.

If you want to follow along, the quickest way to use Hasura is via the Hasura Cloud. Create a new Hasura project and launch the console.

Note: If you prefer local development using Docker, check out the documentation on getting started with Docker.

Root fields namespace

Looking at the "Explorer" tab, you cannot determine which tables belong to which database. With the naming convention feature, you can group all tables belonging to a database.

For example, let's use a custom namespace for the database with "public" notes.

If you navigate to the Hasura console, you can see all the tables from the public database under the public namespace. Now it's easier to see which tables belong to which database.

You could go a step further and use a namespace for the other database as well. You could group all the tables from that database under the private namespace. Thus, you would have the public and private namespaces.

Different naming convention

By default, all Hasura applications use the hasura-default naming convention. With hasura-default:

• all names use snake casing (snake_case)
• enum values are not changed

If you want to change to another naming convention, you can use graphql-default. In this naming convention:

• PascalCase is used for type names
• camelCase is used for field names and arguments
• UPPERCASE is used for enum values

Let's change the naming convention for the second database (private notes) to graphql-default.

The figure below illustrates how the GraphQL query and the response look with the graphql-default naming convention.

This example shows how to change the naming convention for one source. However, you can set a default naming convention for all the sources in a Hasura application.

You can do it by setting the environment variable HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION to the preferred naming convention.

Prefixes and suffixes

Lastly, you can customize the root fields and type names by adding prefixes/suffixes. Let's assume you want to prefix and suffix public notes with public_ and _db, respectively.

Navigate to the "GraphQL Field Customization" section and add the prefix and suffix for the root fields.

If you navigate to the Hasura console, you should see them applied to the root fields.

Similarly, you can add a prefix and suffix for type names. In the "GraphQL Field Customization" section, move the values public_ and _db from "Root Fields" to "Type Names".

Looking at the image, you can see that the type names now contain the custom prefix and suffix.

Summary

The "Naming Convention" feature makes it easier to identify fields & types of a particular database. You can use namespaces, prefixes, and suffixes to organize your application. The documentation for naming conventions is available here.

There is also a video talking about this feature.