GraphQL Hive Technical Specifications

Federation @link compliant features for GraphQL Hive.

Introduction

Links are a feature in Federation 2.x that allow external specifications to be referenced and used by a subgraph. Hive uses links to allow schemas to opt in to schema related features, such as metadata.

Importing via `@link`

A preqrequisite is that the subgraph is using Federation 2.x:


extend schema
  @link(url: "https://specs.apollo.dev/link/v1.0")
  @link(url: "https://specs.apollo.dev/federation/v2.3")

Then the Hive features can be imported like:


extend schema @link(url: "https://specs.graphql-hive.com/hive/v1.0", import: ["@meta"])

Be sure to import and add definitions for all resources you intend to use.

Subgraph schema additions


directive @meta(
  name: String!
  content: String!
) repeatable on SCHEMA | OBJECT | INTERFACE | FIELD_DEFINITION

Features

@meta

Use this directive to enhance schema types with additional data, visible via the Hive Console. This intentionally does not appear in the API Schema to avoid bloat. But if you want this directive to be returned to your gateway, then you can use @composeDirective


directive @meta(
  name: String!
  content: String!
) repeatable on SCHEMA | OBJECT | INTERFACE | FIELD_DEFINITION

Metadata is useful for indicating ownership, contact information, importance, domain, or more. It can be viewed from Hive’s explorer page:

And can be used in Hive’s explorer page to filter the list of elements:

Usage

@meta can be applied to schemas, types, interfaces, and fields. A field’s metadata is a union of all applied metadata. This is applied using the following rules:

meta on a schema applies to every field in the schema.
meta on a type applies to every field in that exact type.
meta on an interface applies to every field in that interface on every implemented type.
meta on a field applies only to that field for that type.