Docs
Launch GraphOS Studio

Contract reference

Reference for valid @tag locations, names, contract errors, and more


This feature is only available with a

.
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

    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
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company