Contract reference

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 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.

1
type User {
2
  id: ID!
3
  name: String! @tag(name: "a/b/c/1-2-3")
4
}

Dependent @tags

• 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:

  GraphQL

  1
  type InternalUser @tag(name: "internal") {
  2
    id: ID! # Also considered to have @tag(name: "internal")
  3
  }

  Copy

• 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:

  GraphQL

  1
  type BillingAccount @tag(name: "internal") {
  2
    id: ID!
  3
    acctNumber: String!
  4
  }
  5
  
  6
  type Query {
  7
    billingAccounts: [BillingAccount!]! @tag(name: "internal")
  8
  }

  Copy

  ⚠️ 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:

    GraphQL

    1
    # Two object types implement this interface.
    2
    interface Identity {
    3
      id: ID!
    4
      name: String!
    5
    }
    6
    
    7
    # If this implementing type is excluded...
    8
    type InternalUser implements Identity @tag(name: "internal") {
    9
      id: ID!
    10
      name: String!
    11
    }
    12
    
    13
    # ...but this implementing type remains...
    14
    type ExternalUser implements Identity {
    15
      id: ID!
    16
      name: String!
    17
    }
    18
    
    19
    type Query {
    20
      # ...then this field doesn't need to be excluded.
    21
      currentIdentity: Identity
    22
    }

    Copy

  • 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:

  GraphQL

  1
  # This type definition is included because one if its fields is included.
  2
  type User {
  3
    id: ID! @tag(name: "includeMe")
  4
  }

  Copy

• If a contract excludes every field of an object or interface type, the entire type definition is excluded from the contract schema:

  GraphQL

  1
  # This object type is excluded because all its fields are excluded.
  2
  type User {
  3
    id: ID! @tag(name: "excludeMe")
  4
  }

  Copy

  ⚠️ 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:

  GraphQL

  1
  # This union type is excluded because all its possible types are excluded.
  2
  union Media = Book | Movie
  3
  
  4
  type Book @tag(name: "excludeMe") {
  5
    title: String!
  6
  }
  7
  
  8
  type Movie @tag(name: "excludeMe") {
  9
    title: String!
  10
  }

  Copy

  ⚠️ 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)

• 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: