GraphQL Framework

For Advanced Users

This section is for advanced users who need to build custom dynamic GraphQL schemas programmatically. It requires:

• Deep understanding of the GraphQL specification
• Strong Java programming skills
• Familiarity with Java Generics and type systems

The vast majority of users do not need this. If you're looking to expose Brightspot content through GraphQL, use the GraphQL Content API (GCA) instead, which requires minimal to zero code.

This documentation is also valuable if you want to:

• Understand how the GCA works internally
• Contribute improvements to the GraphQL plugin
• Extend the framework with custom capabilities

Overview

The Brightspot GraphQL Framework is a type-safe, performant, instrumented framework for building large-scale, highly dynamic GraphQL schemas programmatically. It is the same framework that powers the GCA, providing the low-level Java APIs for complete schema control.

Built on top of the industry-standard graphql-java library, the framework abstracts away the complexities of GraphQL schema construction while enforcing compile-time type safety through Java generics. It enables you to build schemas that adapt dynamically based on your business logic, content types, or external systems.

When to Use the Framework

Choose the GraphQL Framework when you need:

Dynamic Schema Requirements

• Schema types or fields that change based on runtime conditions
• Schema generation from external systems or metadata
• Complex type hierarchies that cannot be expressed in static SDL
• Conditional type inclusion based on user permissions or configuration

Complete Control

• Full control over type resolution and field fetching logic
• Custom naming strategies for avoiding conflicts in dynamic schemas
• Specialized data fetching patterns beyond standard CRUD
• Integration with systems that require custom GraphQL behaviors

Beyond GCA Capabilities

• The GCA's content-centric model doesn't fit your use case
• You need schema features that aren't supported by the GCA
• You're building a specialized GraphQL endpoint with unique requirements

Trade-off: The framework provides maximum flexibility but requires significantly more development effort than using the GCA. You're responsible for defining every type, field, and data fetcher in your schema.

Key Features

Type Safety

APIs leverage Java Generics, ensuring strictly defined types and fields, reducing runtime errors, simplifying refactoring, and enhancing the developer experience.

• Compile-time safety catches errors before runtime
• Type mismatches generate compilation errors
• Refactoring is safer and easier with IDE support
• Better traceability from GraphQL types to Java implementations

Dynamic Type Names

The Schema Name Registry ensures uniqueness and clarity, making schemas more accessible even when types are generated dynamically.

• Automatic conflict resolution with fallback names
• Support for auto-incrementing names when conflicts occur
• GraphQL spec compliance checking
• Reserved type system for common patterns

Schema Directives

Built-in directives provide critical insights and metadata, making schemas easier to navigate and understand.

• @debug for performance profiling and query analysis
• @complexity for query cost management
• @type_origin for traceability to source code
• Custom directive support for specialized behaviors

Built-in Types

Pre-built, reusable GraphQL types for common use cases ensure consistent, efficient data handling:

• Geo-spatial types (Point, Polygon, Location)
• Marked Text types (RTE/Rich Text Editor)
• Extended number scalars (BigInteger, BigDecimal, Byte, Short, Long)
• Extended time scalars (DateTime, Instant, Duration)
• File types (StorageItem)
• Standard scalars (UUID, URL, URI, Locale, JSON)

See the Built-in Types reference for details.

Security & Performance

Enterprise-grade features for production deployments:

• Query complexity analysis and limits
• Maximum query depth enforcement
• Query timeouts
• Custom authentication and authorization
• Rate throttling per client
• Dari profiler integration for performance analysis

Documentation Structure

This section covers the GraphQL Framework in three comprehensive guides:

Getting Started - Build your first custom GraphQL endpoint with a complete "Hello World" example that demonstrates the framework's core concepts in action.

Core Concepts - Master the fundamental concepts including schema names, schema loaders, schema context, load vs. execution contexts, data fetching patterns, and the type/field builder pattern.

Type Generators - Deep dive into Type Generators, the cornerstone of the framework. Learn how to define all seven GraphQL type kinds (type, interface, union, input, enum, scalar, directive), work with field generators, implement type coercion, and leverage advanced data fetching capabilities.

Architecture

The framework is built on the graphql-java library and provides a higher-level abstraction:

1
Your Custom Endpoint
2
        ↓
3
AbstractGraphQLApiEndpoint
4
        ↓
5
GraphQLJavaSchemaLoader
6
        ↓
7
Type Generators (type, interface, union, input, enum, scalar, directive)
8
        ↓
9
Field Generators & Data Fetchers
10
        ↓
11
graphql-java library

You extend AbstractGraphQLApiEndpoint, implement a GraphQLJavaSchemaLoader that defines your root query type, and use Type Generators to define your schema's structure. The framework handles schema loading, caching, validation, and query execution.

Next Steps

If you're ready to dive in, start with Getting Started to build your first custom endpoint. For a complete understanding of the framework's capabilities, work through all three guides in order.