Docs
Launch GraphOS Studio

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:

  • of interface types
  • Enum types and their values
  • Input types and their s
  • Definitions of custom types
  • of , 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 @tags

  • Whenever you tag the definition of an object or interface type, automatically considers that tag to be applied to all 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 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 might exclude a type while including that return that type. This produces an invalid contract schema.

  • If a excludes an object that implements an interface or is included in a union:

    • The is not required to exclude schema that return that interface or union as long as at least one other associated 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 by returning an object of an excluded type, a runtime error occurs in the and the fails.

Special cases for filtering

  • If a defines a list of included @tags, any object or interface type without an included tag is still included in the schema if at least one of its is included:

    # This type definition is included because one if its fields is included.
    type User {
    id: ID! @tag(name: "includeMe")
    }
  • If a excludes every 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 schema if any that return the excluded type are included.

  • If a excludes every 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 schema if any that return the excluded union type are included.

  • A cannot exclude any of the following, even if tagged:

    • Built-in (Int, Float, etc.)
    • Built-in (@skip, @include, etc.)
    • Custom that are applied to locations (see the list)
  • A can exclude object that are used in a computed field's @requires directive without causing runtime errors.

Errors

may encounter the following errors when creating or updating a 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 definitions for @tag, @inaccessible, and core usages.

DIRECTIVE_DEFINITION_LOCATION_AUGMENTING

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

EMPTY_OBJECT_AND_INTERFACE_MASKING

All of an object or interface type's 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 is attempting to include and exclude the same tag.

PARSING

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

PARSING_TAG_DIRECTIVES

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

PARTIAL_INTERFACE_MASKING

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

SCHEMA_RETRIEVAL

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

TAG_INHERITING

encountered an error while attempting to add parent tags to .

TAG_MATCHING

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

TO_API_SCHEMA

encountered an error while attempting to generate an API schema from the 's .

TO_FILTER_SCHEMA

failed to generate and return a for an unknown reason.

UNKNOWN

An unknown error occurred.

UNREACHABLE_TYPE_MASKING

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

VERSION_CHECK

do not support the Federation version used.

Previous
Creating and using contracts
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company