> 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/scalars/federation-scalars.md).

# Federation Scalars

Apollo Federation scalar types used in pyck

Audience: Programmer

Federation scalars are special scalar types used by Apollo Federation for distributed GraphQL schema composition. These scalars are primarily used internally by the federation runtime and are not typically used directly in client queries.

## Available Federation Scalars

### join\_\_FieldSet

A string representation of a selection set used to specify fields for federation key directives.

**Type**: `String`

**Usage**: Used in `@key` directives to define entity keys across services.

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

### link\_\_Import

Represents an import statement for federation directives and types.

**Type**: `String`

**Usage**: Used to import federation specifications and features.

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

## Understanding Federation in pyck

pyck uses Apollo Federation to compose multiple GraphQL services into a single unified API:

1. **Attachments Service**: Handles file uploads and attachments
2. **Inventory Service**: Manages inventory items, movements, and repositories
3. **MainData Service**: Handles master data (customers, suppliers, data types)
4. **Management Service**: Manages companies, users, and access control
5. **Picking Service**: Handles picking orders and order fulfillment
6. **Receiving Service**: Manages inbound shipments and receiving
7. **WorkflowService**: Orchestrates Temporal workflows

### Federation Directives

While not scalars, these directives work with federation scalars:

* `@key`: Defines the primary key for an entity
* `@requires`: Specifies fields needed from other services
* `@provides`: Indicates fields provided by this service
* `@external`: Marks fields defined in another service
* `@extends`: Extends a type from another service

## Example: Federated Entity

```graphql
# In Inventory Service
type InventoryItem @key(fields: "id") {
  id: ID!
  sku: String!
  name: String!
  stock: Stock
}

# In Picking Service
extend type InventoryItem @key(fields: "id") {
  id: ID! @external
  pickingOrders: [PickingOrderItem!]!
}
```

## Client Perspective

From a client's perspective, federation is transparent. You query the unified schema without needing to know about the underlying service boundaries:

```graphql
query {
  inventoryItem(id: "item_123") {
    # From Inventory Service
    id
    sku
    name
    stock {
      available
      reserved
    }
    
    # From Picking Service (federated)
    pickingOrders {
      id
      quantity
      pickingOrder {
        referenceId
        status
      }
    }
  }
}
```

## Best Practices

1. **Let Federation Handle It**: These scalars are managed by the federation runtime
2. **Focus on the API**: As a client developer, work with the composed schema
3. **Understand Service Boundaries**: Knowing which service owns which data can help with performance optimization

## See Also

* [Schema Overview](/graphql-api/schema-overview.md) for the complete composed schema
* [Architecture](/development/architecture.md) for service architecture details
* [Apollo Federation Docs](https://www.apollographql.com/docs/federation/) for detailed federation concepts


---

# 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/scalars/federation-scalars.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.