> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/graphql-api/directives.md).

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

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

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

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

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

### @requires

Specifies external fields required to resolve a field.

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

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

### @external

Marks fields that are defined in another service.

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

### @extends

Extends a type that originates from another service.

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

### @shareable

Indicates that a field can be resolved by multiple services.

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

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

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

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

## Best Practices

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

## JavaScript Example

```javascript
// 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
  }
});
```

## See Also

* [Schema Overview](/graphql-api/schema-overview.md) for federation architecture
* [Authentication](/graphql-api/authentication.md) for details on the `@public` directive
* [Apollo Federation Spec](https://www.apollographql.com/docs/federation/federated-types/federated-directives) for detailed federation directive documentation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/graphql-api/directives.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.