Contract Overview

A unified supergraph provides a single source of truth for your organization's data. That data likely has different consumers with different needs and permissions. GraphOS contracts enable you to deliver different subsets of your supergraph to different consumers.

Each contract can include different fields and types from each subgraph.

Benefits of contracts

Contracts offer these benefits:

• Selective data access: Supergraphs often contain a wide range of data, including information that's irrelevant to specific audiences. Contracts declaratively grant access to specific subsets of the supergraph, so graph consumers only access relevant data.

• Data security and privacy: Contracts bolster data security and privacy by enabling the exclusion of confidential data from certain consumers. This ensures that only authorized parties can access sensitive data.

• Documentation and guidance: Contracts provide documentation to client developers. Contract-specific documentation helps developers better understand and more easily interact with the data they are authorized to access.

How contracts work

Each contract filters specific portions of your supergraph's schema into a different GraphOS variant:

Contracts are created by adding @tag directives to your subgraph schemas. @tags declare which types and fields to include or exclude from specific contract variants.

1
type Product {
2
  id: ID!
3
  name: String!
4
  codename: String! @tag(name: "internal")
5
}

1
type Product {
2
  id: ID!
3
  name: String!
4
  # codename field is filtered out of this contract variant
5
}

In the above example, a contract excludes types and fields marked with the internal @tag. The resulting contract schema defines a tailored GraphQL API for external audiences.

How to use contracts

You usually create a contract to support a contract router, contract documentation, or both.

Contract routers

You can deploy a managed instance of your graph router that uses a contract schema. Clients that use a contract router's endpoint can only execute GraphQL operations that the contract schema supports:

This enables you to hide experimental types and fields still in development or limit a particular audience's access to only the portions of the graph they need.

Contract routers can safely connect to the same subgraph instances as any other router because their clients can only interact with data represented in the contract schema. This does not affect internal routing. For example, filtered fields can still be used in a @requires selection set.

Contract documentation

In GraphOS Studio, each contract variant has its own README, schema reference, and Explorer. If you make a contract variant public, you can provide these resources to external client developers to help them interact with a specific portion of your graph while omitting irrelevant types and fields.

Federation 1 limitations

Contracts behave slightly differently depending on which version of Apollo Federation your graph uses—either Federation 1 or Federation 2. Most importantly, graphs that use Federation 1 cannot use @tags to exclude the following from a contract schema:

• Custom scalar types (default scalar types can never be excluded in Federation 1)
• Enum types or their values
• Input types or their fields
• Arguments of object fields or interface fields

Contracts and Federation 2

To create a contract variant that uses Federation 2, the contract's source variant must also use Federation 2. Learn how to move an existing variant to Federation 2.

Moving an existing contract to Federation 2

If a Federation 1 source variant already has one or more associated contracts, it isn't possible to move that variant or its contract variants to Federation 2. Instead, you need to delete and recreate your contract variants with the following steps:

Related resources