---
title: Graphql
description: Graphql protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

GraphQL Protocol Support

GraphQL is a query language for APIs and a runtime for executing those queries.

It provides a complete and understandable description of the data in your API,

gives clients the power to ask for exactly what they need, and enables powerful

developer tools.

## Overview

GraphQL provides:

- Type-safe schema definition

- Precise data fetching (no over/under-fetching)

- Introspection and documentation

- Real-time subscriptions

- Batched queries with DataLoader

## Use Cases

1. **Modern API Development**

- Mobile and web applications

- Microservices federation

- Real-time dashboards

2. **Data Aggregation**

- Multi-source data integration

- Complex nested queries

- Efficient data loading

3. **Developer Experience**

- Self-documenting API

- Type safety and validation

- GraphQL playground

@see https://graphql.org/

@see https://spec.graphql.org/

@example GraphQL Query

```graphql

query GetCustomer($id: ID!) \{

customer(id: $id) \{

id

name

email

orders(limit: 10, status: "active") \{

id

total

items \{

product \{

name

price

\}

\}

\}

\}

\}

```

@example GraphQL Mutation

```graphql

mutation CreateOrder($input: CreateOrderInput!) \{

createOrder(input: $input) \{

id

orderNumber

status

\}

\}

```

<Callout type="info">
**Source:** `packages/spec/src/api/graphql.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api';
import type { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api';

// Validate data
const result = FederationEntity.parse(data);
```

---

## FederationEntity

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **typeName** | `string` | ✅ | GraphQL type name for this entity |
| **keys** | `Object[]` | ✅ | Entity key definitions |
| **externalFields** | `Object[]` | optional | Fields owned by other subgraphs |
| **requires** | `Object[]` | optional | Required external fields for computed fields |
| **provides** | `Object[]` | optional | Fields provided during resolution |
| **owner** | `boolean` | ✅ | Whether this subgraph is the owner of this entity |


---

## FederationEntityKey

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **fields** | `string` | ✅ | Selection set of fields composing the entity key |
| **resolvable** | `boolean` | ✅ | Whether entities can be resolved from this subgraph |


---

## FederationExternalField

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field name marked as external |
| **ownerSubgraph** | `string` | optional | Subgraph that owns this field |


---

## FederationGateway

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable GraphQL Federation gateway mode |
| **version** | `Enum<'v1' \| 'v2'>` | ✅ | Federation specification version |
| **subgraphs** | `Object[]` | ✅ | Subgraph configurations |
| **serviceDiscovery** | `Object` | optional | Service discovery configuration |
| **queryPlanning** | `Object` | optional | Query planning configuration |
| **composition** | `Object` | optional | Schema composition configuration |
| **errorHandling** | `Object` | optional | Error handling configuration |


---

## FederationProvides

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field that provides additional entity fields |
| **fields** | `string` | ✅ | Selection set of provided fields (e.g., "name price") |


---

## FederationRequires

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field with the requirement |
| **fields** | `string` | ✅ | Selection set of required fields (e.g., "price weight") |


---

## GraphQLDataLoaderConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | DataLoader name |
| **source** | `string` | ✅ | Source object or datasource |
| **batchFunction** | `Object` | ✅ | Batch function configuration |
| **cache** | `Object` | optional | DataLoader caching |
| **options** | `Object` | optional | DataLoader options |


---

## GraphQLDirectiveConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Directive name (camelCase) |
| **description** | `string` | optional | Directive description |
| **locations** | `Enum<'QUERY' \| 'MUTATION' \| 'SUBSCRIPTION' \| 'FIELD' \| 'FRAGMENT_DEFINITION' \| 'FRAGMENT_SPREAD' \| 'INLINE_FRAGMENT' \| 'VARIABLE_DEFINITION' \| 'SCHEMA' \| 'SCALAR' \| 'OBJECT' \| 'FIELD_DEFINITION' \| 'ARGUMENT_DEFINITION' \| 'INTERFACE' \| 'UNION' \| 'ENUM' \| 'ENUM_VALUE' \| 'INPUT_OBJECT' \| 'INPUT_FIELD_DEFINITION'>[]` | ✅ | Directive locations |
| **args** | `Record<string, Object>` | optional | Directive arguments |
| **repeatable** | `boolean` | ✅ | Can be applied multiple times |
| **implementation** | `Object` | optional | Directive implementation |


---

## GraphQLDirectiveLocation

### Allowed Values

* `QUERY`
* `MUTATION`
* `SUBSCRIPTION`
* `FIELD`
* `FRAGMENT_DEFINITION`
* `FRAGMENT_SPREAD`
* `INLINE_FRAGMENT`
* `VARIABLE_DEFINITION`
* `SCHEMA`
* `SCALAR`
* `OBJECT`
* `FIELD_DEFINITION`
* `ARGUMENT_DEFINITION`
* `INTERFACE`
* `UNION`
* `ENUM`
* `ENUM_VALUE`
* `INPUT_OBJECT`
* `INPUT_FIELD_DEFINITION`


---

## GraphQLMutationConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Mutation field name (camelCase recommended) |
| **object** | `string` | ✅ | Source ObjectQL object name |
| **type** | `Enum<'create' \| 'update' \| 'delete' \| 'upsert' \| 'custom'>` | ✅ | Mutation type |
| **description** | `string` | optional | Mutation description |
| **input** | `Object` | optional | Input configuration |
| **output** | `Object` | optional | Output configuration |
| **transaction** | `Object` | optional | Transaction configuration |
| **authRequired** | `boolean` | ✅ | Require authentication |
| **permissions** | `string[]` | optional | Required permissions |
| **hooks** | `Object` | optional | Lifecycle hooks |


---

## GraphQLPersistedQuery

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable persisted queries |
| **mode** | `Enum<'optional' \| 'required'>` | ✅ | Persisted query mode (optional: allow both, required: only persisted) |
| **store** | `Object` | optional | Query store configuration |
| **apq** | `Object` | optional | Automatic Persisted Queries configuration |
| **allowlist** | `Object` | optional | Query allow list configuration |
| **security** | `Object` | optional | Security configuration |


---

## GraphQLQueryComplexity

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable query complexity limiting |
| **maxComplexity** | `integer` | ✅ | Maximum query complexity |
| **defaultFieldComplexity** | `integer` | ✅ | Default complexity per field |
| **fieldComplexity** | `Record<string, integer \| Object>` | optional | Per-field complexity configuration |
| **listMultiplier** | `number` | ✅ | Multiplier for list fields |
| **onComplexityExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | ✅ | Action when complexity exceeded |
| **errorMessage** | `string` | optional | Custom error message for complexity violations |


---

## GraphQLQueryDepthLimit

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable query depth limiting |
| **maxDepth** | `integer` | ✅ | Maximum query depth |
| **ignoreFields** | `string[]` | optional | Fields excluded from depth calculation |
| **onDepthExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | ✅ | Action when depth exceeded |
| **errorMessage** | `string` | optional | Custom error message for depth violations |


---

## GraphQLRateLimit

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable rate limiting |
| **strategy** | `Enum<'token_bucket' \| 'fixed_window' \| 'sliding_window' \| 'cost_based'>` | ✅ | Rate limiting strategy |
| **global** | `Object` | optional | Global rate limits |
| **perUser** | `Object` | optional | Per-user rate limits |
| **costBased** | `Object` | optional | Cost-based rate limiting |
| **operations** | `Record<string, Object>` | optional | Per-operation rate limits |
| **onLimitExceeded** | `Enum<'reject' \| 'queue' \| 'log'>` | ✅ | Action when rate limit exceeded |
| **errorMessage** | `string` | optional | Custom error message for rate limit violations |
| **includeHeaders** | `boolean` | ✅ | Include rate limit headers in response |


---

## GraphQLScalarType

### Allowed Values

* `ID`
* `String`
* `Int`
* `Float`
* `Boolean`
* `DateTime`
* `Date`
* `Time`
* `JSON`
* `JSONObject`
* `Upload`
* `URL`
* `Email`
* `PhoneNumber`
* `Currency`
* `Decimal`
* `BigInt`
* `Long`
* `UUID`
* `Base64`
* `Void`


---

## GraphQLSubscriptionConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Subscription field name (camelCase recommended) |
| **object** | `string` | ✅ | Source ObjectQL object name |
| **events** | `Enum<'created' \| 'updated' \| 'deleted' \| 'custom'>[]` | ✅ | Events to subscribe to |
| **description** | `string` | optional | Subscription description |
| **filter** | `Object` | optional | Subscription filtering |
| **payload** | `Object` | optional | Payload configuration |
| **authRequired** | `boolean` | ✅ | Require authentication |
| **permissions** | `string[]` | optional | Required permissions |
| **rateLimit** | `Object` | optional | Subscription rate limiting |


---

## GraphQLTypeConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | GraphQL type name (PascalCase recommended) |
| **object** | `string` | ✅ | Source ObjectQL object name |
| **description** | `string` | optional | Type description |
| **fields** | `Object` | optional | Field configuration |
| **interfaces** | `string[]` | optional | GraphQL interface names |
| **isInterface** | `boolean` | ✅ | Define as GraphQL interface |
| **directives** | `Object[]` | optional | GraphQL directives |


---

## SubgraphConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Unique subgraph identifier |
| **url** | `string` | ✅ | Subgraph endpoint URL |
| **schemaSource** | `Enum<'introspection' \| 'file' \| 'registry'>` | ✅ | How to obtain the subgraph schema |
| **schemaPath** | `string` | optional | Path to schema file (SDL format) |
| **entities** | `Object[]` | optional | Entity definitions for this subgraph |
| **healthCheck** | `Object` | optional | Subgraph health check configuration |
| **forwardHeaders** | `string[]` | optional | HTTP headers to forward to this subgraph |


---

