Contract Reference
Reference for valid @tag locations, names, contract errors, and more
This feature is only available with a GraphOS Enterprise plan.
You can test it out by signing up for a free Enterprise trial.
Rules for @tag
s and contracts
Valid @tag
locations
In both Federation 1 and Federation 2, you can apply tags to the following schema elements to filter your contract schema:
- Object, interface, and union type definitions
- Fields of object types
- Federation 1 doesn't support tagging fields of interface types.
- In Federation 1, you can still make an interface field inaccessible by tagging the interface definition or by ensuring that object fields that implement the interface field are removed.
In Federation 2 only, you can also apply tags to the following:
- Fields of interface types
- Enum types and their values
- Input types and their fields
- Definitions of custom scalar types
- Arguments of fields, but not directive arguments
Valid @tag
names
@tag
names can include alphanumeric characters (a-z
,A-Z
,0-9
), along with hyphens (-
) and forward slashes (/
).- Each tag name cannot exceed 128 characters.
type User {id: ID!name: String! @tag(name: "a/b/c/1-2-3")}
Dependent @tag
s
Whenever you tag the definition of an object or interface type, GraphOS automatically considers that tag to be applied to all fields of that type:
type InternalUser @tag(name: "internal") {id: ID! # Also considered to have @tag(name: "internal")}Whenever you tag the definition of an object, interface, or union type, you should always apply that same tag to every field that returns that type:
type BillingAccount @tag(name: "internal") {id: ID!acctNumber: String!}type Query {billingAccounts: [BillingAccount!]! @tag(name: "internal")}⚠️ CAUTION
If you don't do this, a contract might exclude a type while including fields that return that type. This produces an invalid contract schema.
If a contract excludes an object that implements an interface or is included in a union:
The contract is not required to exclude schema fields that return that interface or union as long as at least one other associated object type remains:
# Two object types implement this interface.interface Identity {id: ID!name: String!}# If this implementing type is excluded...type InternalUser implements Identity @tag(name: "internal") {id: ID!name: String!}# ...but this implementing type remains...type ExternalUser implements Identity {id: ID!name: String!}type Query {# ...then this field doesn't need to be excluded.currentIdentity: Identity}However, if a subgraph resolves one of these fields by returning an object of an excluded type, a runtime error occurs in the router and the operation fails.
Special cases for filtering
If a contract defines a list of included
@tags
, any object or interface type without an included tag is still included in the contract schema if at least one of its fields is included:# This type definition is included because one if its fields is included.type User {id: ID! @tag(name: "includeMe")}If a contract excludes every field of an object or interface type, the entire type definition is excluded from the contract schema:
# This object type is excluded because all its fields are excluded.type User {id: ID! @tag(name: "excludeMe")}⚠️ CAUTION
This can produce an invalid contract schema if any fields that return the excluded type are included.
If a contract excludes every object type that's part of a union type, the entire union type definition is excluded from the contract schema:
# This union type is excluded because all its possible types are excluded.union Media = Book | Movietype Book @tag(name: "excludeMe") {title: String!}type Movie @tag(name: "excludeMe") {title: String!}⚠️ CAUTION
This can produce an invalid contract schema if any fields that return the excluded union type are included.
A contract cannot exclude any of the following, even if tagged:
- Built-in scalars (
Int
,Float
, etc.) - Built-in directives (
@skip
,@include
, etc.) - Custom directives that are applied to type system locations (see the list)
- Built-in scalars (
A contract can exclude object fields that are used in a computed field's
@requires
directive without causing runtime errors.
Errors
GraphOS may encounter the following errors when creating or updating a contract schema. Errors descriptions include the step in the creation process where the error occurred:
Error | Description |
---|---|
| An error occurred adding directive definitions for |
| An error occurred augmenting the directive definition for |
| All of an object or interface type's fields were excluded, and an error occurred while excluding the entire type. |
| All of a union type's included types were excluded, and an error occurred while excluding the entire union. |
| The contract is attempting to include and exclude the same tag. |
| After including and excluding fields, the resulting contract schema failed to parse. |
| GraphOS encountered an error while trying to obtain all uses of |
| An interface field's return type was excluded, and an error occurred while excluding that interface field. |
| GraphOS encountered an error while retrieving the source variant's schema. It might not yet have a valid composed schema. |
| GraphOS encountered an error while attempting to add parent tags to fields. |
| GraphOS encountered an error determining which types and fields should be inaccessible based on their tags. |
| GraphOS encountered an error while attempting to generate an API schema from the contract variant's supergraph schema. |
| GraphOS failed to generate and return a contract supergraph schema for an unknown reason. |
| An unknown error occurred. |
| GraphOS encountered an error while attempting to exclude unreachable types in the resulting contract schema. |
| Contracts do not support the Federation version used. |