Directives

GraphQL directives available in the pyck API

Audience: Programmer

Directives provide a way to modify the execution of GraphQL queries and control schema behavior. pyck uses both standard federation directives and custom directives for various purposes.

Custom Directives

@public

Marks fields, queries, or mutations as publicly accessible without authentication.

Usage: Applied to schema elements that should be accessible without authentication.

type Query {
  # This query is accessible without authentication
  publicDataTypes: [DataType!]! @public
  
  # This query requires authentication (default)
  inventoryItems: InventoryItemConnection!
}

Note: Most of the pyck API requires authentication. Only specific endpoints marked with @public are accessible without credentials.

@goField

Controls Go code generation for specific fields.

Usage: Internal directive used by the code generator to customize field behavior in Go.

type InventoryItem {
  # Custom Go field configuration
  data: Map @goField(name: "customData", forceResolver: true)
}

Parameters:

name: Custom field name in Go code
forceResolver: Forces generation of a resolver method

@goModel

Maps GraphQL types to specific Go models.

Usage: Internal directive for mapping GraphQL types to Go structs.

type Time @goModel(model: "time.Time")

Federation Directives

pyck uses Apollo Federation v2.3 directives for distributed schema composition:

@key

Defines the primary key for an entity that can be resolved across services.

type InventoryItem @key(fields: "id") @key(fields: "sku") {
  id: ID!
  sku: String!
}

@requires

Specifies external fields required to resolve a field.

extend type InventoryItem @key(fields: "id") {
  id: ID! @external
  stock: Stock @requires(fields: "id")
}

@provides

Indicates fields that this service provides for an external type.

type PickingOrderItem {
  inventoryItem: InventoryItem @provides(fields: "name sku")
}

@external

Marks fields that are defined in another service.

extend type User @key(fields: "id") {
  id: ID! @external
  email: String! @external
  pickingOrders: [PickingOrder!]!
}

@extends

Extends a type that originates from another service.

extend type InventoryItem @key(fields: "id") {
  # Fields added by this service
}

@shareable

Indicates that a field can be resolved by multiple services.

type Product @key(fields: "id") {
  id: ID!
  name: String! @shareable
}

Federation-Specific Join Directives

These directives are used internally by the federation runtime:

@join__enumValue: Maps enum values across services
@join__field: Configures field joining behavior
@join__graph: Identifies subgraph sources
@join__implements: Handles interface implementation across services
@join__type: Manages type definitions across services
@join__unionMember: Handles union members across services

@link

Imports federation specifications and features.

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.3",
    import: ["@key", "@shareable", "@provides", "@external", "@requires", "@extends"])

Directive Usage in Queries

While most directives are schema-level, some can be used in queries:

@include

Conditionally includes fields based on a variable.

query GetItem($showDetails: Boolean!) {
  inventoryItem(id: "123") {
    id
    name
    # Only include details if requested
    description @include(if: $showDetails)
    data @include(if: $showDetails)
  }
}

@skip

Conditionally skips fields based on a variable.

query GetItems($hideStock: Boolean!) {
  inventoryItems {
    edges {
      node {
        id
        name
        # Skip stock info if not needed
        stock @skip(if: $hideStock) {
          available
          reserved
        }
      }
    }
  }
}

Best Practices

Authentication: Assume all fields require authentication unless marked with @public
Federation: Let the Gateway handle federation directives automatically
Conditional Fields: Use @include/@skip for dynamic field selection
Performance: Be mindful that conditional directives still affect query complexity

JavaScript Example

// Using @include directive
const query = gql`
  query GetInventoryItem($id: ID!, $includeStock: Boolean!) {
    inventoryItem(id: $id) {
      id
      name
      sku
      stock @include(if: $includeStock) {
        available
        reserved
        incoming
      }
    }
  }
`;

// Fetch without stock information
const minimalResult = await client.query({
  query,
  variables: {
    id: "item_123",
    includeStock: false
  }
});

// Fetch with stock information
const detailedResult = await client.query({
  query,
  variables: {
    id: "item_123",
    includeStock: true
  }
});