Schema Contracts are a powerful new security feature that allows you to define and enforce specific subsets of your federated schema. Schema Contracts give you fine-grained control over what parts of your API are exposed to different consumers, whether that's based on security requirements, client capabilities, or organizational policies.
With Schema Contracts, you can create filtered views of your schema that include or exclude specific types, fields, and operations based on directives. This enables use cases like:
- Security boundaries: Hide sensitive fields or entire types from public-facing clients
- Client-specific schemas: Provide different API surfaces for mobile/web vs. agents/AI/LLMs vs. internal applications
- Progressive rollouts: Gradually expose new schema elements to different consumer groups
- Compliance: Meet regulatory requirements by controlling data access at the schema level
Schema Contracts rely on a contracts extension to mark schema elements for inclusion or exclusion.
The tag extension provides a @tag directive that can be applied to any schema element:
extend schema
@link(url: "https://grafbase.com/extensions/tag/1.0.2", import: ["@tag"])
type User {
id: ID!
email: String! @tag(name: "private")
publicProfile: Profile! @tag(name: "public")
}
type InternalAccount @tag(name: "internal") {
id: ID!
adminNotes: String!
}Contract keys define which tags to include or exclude:
{
"includedTags": ["public"],
"excludedTags": ["private", "internal"]
}You can configure contracts statically in your gateway configuration:
# grafbase.toml
[graph.contracts]
default_key = '{"includedTags": ["public"], "excludedTags": ["private"]}'The gateway can serve more than one schema contract with the help of the on_request hook (guide). Each request can have its own contract key based on the url, method or headers. Schema Contracts are cached by their contract key in the gateway, ensuring minimal performance impact.
The contracts system is also extensible - while the tag extension covers most use cases, you can build custom contract extensions using the grafbase-sdk for specialized filtering logic.
Contract extensions can even modify subgraph URLs, allowing you to route different contract views to different backend services entirely.
In addition to controlling the exposed GraphQL API, schema contract also apply on the API exposed by the MCP endpoint, allowing fine-grained control over what your agent can access.
Schema Contracts are available now for all Grafbase users. Check out the documentation to start defining contracts for your federated graph.
We're excited to see how teams use Schema Contracts to build more secure, flexible, and well-governed GraphQL APIs. As always, we'd love to hear your feedback and use cases in our community.