Schema Contracts

Schema contracts are a powerful feature that allows you to define and enforce a specific subset of the schema either statically or dynamically.

Schema contracts rely on a contracts extension to modify the schema. The marketplace provides a tag extension which defines the following directive:

directive @tag(
  name: String!
) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION

The directive can be used in any subgraph with the following import:

extend schema
  @link(url: "https://grafbase.com/extensions/tag/1.0.0", import: ["@tag"])

type Accounts @tag(name: "private") {
  id: ID!
}

In addition to the @tag directive, a contract key must be defined to include or exclude certain tags. The tag accepts a JSON string as follows:

{
  "includedTags": ["public"],
  "excludedTags": ["private"]
}

The contract key can be defined either statically in the configuration with:

# grafbase.toml
[graph.contracts]
default_key = '{"includedTags": ["public"], "excludedTags": ["private"]}'

Or it can be dynamically defined by the on_request hook (guide) for each individual request. Schema contracts will be cached by their contract key in the gateway.

In addition contracts extensions can also modify the subgraph URLs.

Custom schema contracts

tag is just one possibility of contracts extension. You can create your own with the grafbase-sdk.