Graphql

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

Modern API Development

Mobile and web applications
Microservices federation
Real-time dashboards

Data Aggregation

Multi-source data integration
Complex nested queries
Efficient data loading

Developer Experience

Self-documenting API
Type safety and validation
GraphQL playground

@see https://graphql.org/

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

@example GraphQL Query


query GetCustomer($id: ID!) \{

customer(id: $id) \{

id

name

email

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

id

total

items \{

product \{

name

price

\}

\}

\}

\}

\}

@example GraphQL Mutation


mutation CreateOrder($input: CreateOrderInput!) \{

createOrder(input: $input) \{

id

orderNumber

status

\}

\}

Source: packages/spec/src/api/graphql.zod.ts

TypeScript Usage

import { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig, SubgraphConfig } from '@objectstack/spec/api';
import type { FederationEntity, FederationEntityKey, FederationExternalField, FederationGateway, FederationProvides, FederationRequires, GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, 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")

GraphQLConfig

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable GraphQL API
path	`string`	✅	GraphQL endpoint path
playground	`Object`	optional	GraphQL Playground configuration
schema	`Object`	optional	Schema generation configuration
dataLoaders	`Object[]`	optional	DataLoader configurations
security	`Object`	optional	Security configuration
federation	`Object`	optional	GraphQL Federation gateway configuration

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

GraphQLQueryConfig

Properties

Property	Type	Required	Description
name	`string`	✅	Query field name (camelCase recommended)
object	`string`	✅	Source ObjectQL object name
type	`Enum<'get' \| 'list' \| 'search'>`	✅	Query type
description	`string`	optional	Query description
args	`Record<string, Object>`	optional	Query arguments
filtering	`Object`	optional	Filtering capabilities
sorting	`Object`	optional	Sorting capabilities
pagination	`Object`	optional	Pagination configuration
fields	`Object`	optional	Field selection configuration
authRequired	`boolean`	✅	Require authentication
permissions	`string[]`	optional	Required permissions
cache	`Object`	optional	Query caching

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

GraphQLResolverConfig

Properties

Property	Type	Required	Description
path	`string`	✅	Resolver path (Type.field)
type	`Enum<'datasource' \| 'computed' \| 'script' \| 'proxy'>`	✅	Resolver implementation type
implementation	`Object`	optional	Implementation configuration
cache	`Object`	optional	Resolver caching

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

On this page