Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

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 @tags and contracts

Valid @tag locations

In both Federation 1 and Federation 2, you can apply tags to the following schema elements to filter your schema:

  • Object, interface, and union type definitions
  • of s
    • Federation 1 doesn't support tagging of interface types.
    • In Federation 1, you can still make an interface 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 types
  • of fields, but not 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 @tags

  • Whenever you tag the definition of an object or interface type, 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 resolves one of these fields by returning an object of an excluded type, a runtime error occurs in the and the 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 | Movie
    type 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 (Int, Float, etc.)
    • Built-in (@skip, @include, etc.)
    • Custom directives that are applied to locations (see the list)
  • 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:

ErrorDescription
ADD_DIRECTIVE_DEFINITIONS_IF_NOT_PRESENT

An error occurred adding directive definitions for @tag, @inaccessible, and core directive usages.

DIRECTIVE_DEFINITION_LOCATION_AUGMENTING

An error occurred augmenting the directive definition for @tag to support OBJECT, FIELD_DEFINITION, INTERFACE, and UNION.

EMPTY_OBJECT_AND_INTERFACE_MASKING

All of an object or interface type's fields were excluded, and an error occurred while excluding the entire type.

EMPTY_UNION_MASKING

All of a union type's included types were excluded, and an error occurred while excluding the entire union.

INPUT_VALIDATION

The contract is attempting to include and exclude the same tag.

PARSING

After including and excluding fields, the resulting contract schema failed to parse.

PARSING_TAG_DIRECTIVES

GraphOS encountered an error while trying to obtain all uses of @tag from the schema.

PARTIAL_INTERFACE_MASKING

An interface field's return type was excluded, and an error occurred while excluding that interface field.

SCHEMA_RETRIEVAL

GraphOS encountered an error while retrieving the source variant's schema. It might not yet have a valid composed schema.

TAG_INHERITING

GraphOS encountered an error while attempting to add parent tags to fields.

TAG_MATCHING

GraphOS encountered an error determining which types and fields should be inaccessible based on their tags.

TO_API_SCHEMA

GraphOS encountered an error while attempting to generate an from the contract 's .

TO_FILTER_SCHEMA

GraphOS failed to generate and return a contract supergraph schema for an unknown reason.

UNKNOWN

An unknown error occurred.

UNREACHABLE_TYPE_MASKING

GraphOS encountered an error while attempting to exclude unreachable types in the resulting contract schema.

VERSION_CHECK

do not support the Federation version used.

Previous
Creating and Using Contracts
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company