Namespacing Remote Schemas

Introduction

When integrating multiple schemas into your Hasura project, there may be instances where two schemas define types with the same name. This can lead to naming conflicts, preventing your GraphQL schema from working correctly.

To solve this, you can use namespacing and prefixes to ensure that each type definition has a unique identifier.

Common Error: Conflicting Definitions

Hasura GraphQL Engine automatically checks for type conflicts in your schema. If two schemas share the same top-level type definition, you might encounter an error like this:

Found conflicting definitions for GraphQL type 'collections_order_by'. The definition at query_root.near.collections.order_by differs from the definitions at [query_root.aptos.nftz.order_by.collection, query_root.aptos.collections_search_aggregate.order_by, query_root.aptos.collections_search.order_by, query_root.aptos.collections_aggregate.order_by, query_root.aptos.collections.order_by, query_root.aptos.actions.collection.edition_launches.order_by.collection, query_root.aptos.actions.collection.attributes.nft.listings.order_by.collection, query_root.aptos.actions.collection.attributes.nft.bids.order_by.collection, query_root.aptos.actions.collection.attributes.order_by.collection, query_root.aptos.actions.order_by.nft.collection, query_root.aptos.actions.order_by.collection]

With the most important part being the first statement:

Found conflicting definitions for GraphQL type ‘collections_order_by’

This error means that the same type is defined in multiple places, creating a conflict that Hasura cannot resolve automatically. In such cases, Hasura offers a mechanism to rename conflicting types using namespaces or prefixes.

Console

From the Remote Schemas tab, after filling in your schema's details, click GraphQL Customizations and add your customization values here.

CLI

Find the remote_schemas.yaml file in your metadata and customize your namespacing and prefixing values.

- name: <remote_schema_name>
  definition:
    url: <your_remote_schema_url>
    timeout_seconds: 60
    customization:
      field_names:
        - mapping: {}
          parent_type: <your_prefix>_
          prefix: <your_prefix>_
        - mapping: {}
          parent_type: <your_prefix>_
          prefix: <your_prefix>_
      root_fields_namespace: <your_namespace_prefix>_
      type_names:
        mapping: {}
        prefix: <your_prefix>_
        suffix: <your_prefix>_

API

If you're using the API, you can add your Remote Schema with a namespace using this template, taking special note of the root_fields_namespace and prefix keys.

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "add_remote_schema",
  "args": {
      "name": "your remote schema name",
      "definition": {
          "url": "https://remote-server.com/graphql",
          "headers": [{"name": "X-Server-Request-From", "value": "Hasura"}],
          "forward_client_headers": false,
          "timeout_seconds": 60,
          "customization": {
             "root_fields_namespace": "your_field_name",
             "type_names": {
                 "prefix": "your_type_name_prefix",
                 "mapping": {
                     "some_type_name": "some_new_type_name"
                 }
             },
             "field_names": [ {
                 "parent_type": "your_type_name",
                 "prefix": "your_field_name_prefix",
                 "mapping": {
                     "some_field_name": "some_new_field_name"
                 }
             } ]
          }
      },
  }
}

Apply the Metadata by running:

hasura metadata apply