or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

federation-directives.mdfederation-types.mdindex.mdschema-building.mdschema-printing.md
tile.json

schema-printing.mddocs/

Schema Printing

Utilities for outputting federation-aware schema representations as SDL (Schema Definition Language) strings, preserving federation directives, metadata, and proper formatting for subgraph schemas.

Capabilities

Print Subgraph Schema

Prints a GraphQL schema as federation-aware SDL, including federation directives and schema transformations specific to subgraph representation.

/**
 * Prints subgraph schema with federation directives included
 * @param schema - GraphQL schema to print
 * @returns Federation-aware SDL string
 */
function printSubgraphSchema(schema: GraphQLSchema): string;

Usage Example:

import { buildSubgraphSchema, printSubgraphSchema } from "@apollo/subgraph";
import { gql } from "graphql-tag";

const schema = buildSubgraphSchema(gql`
  type Query {
    product(id: ID!): Product
  }

  type Product @key(fields: "id") {
    id: ID!
    name: String!
    price: Float
  }
`);

const sdl = printSubgraphSchema(schema);
console.log(sdl);
// Output includes federation directives:
// extend schema @link(url: "https://specs.apollo.dev/federation/v2.0")
// type Product @key(fields: "id") { ... }

Print Introspection Schema

Prints a schema with directive applications but without skipping directive definitions, useful for full schema inspection including federation metadata.

/**
 * Prints schema with directive applications and directive definitions
 * @param schema - GraphQL schema to print
 * @returns Full schema SDL with all directives
 */
function printIntrospectionSchema(schema: GraphQLSchema): string;

Usage Example:

import { printIntrospectionSchema } from "@apollo/subgraph";

const fullSDL = printIntrospectionSchema(schema);
// Includes directive definitions and applications

Print Type

Prints a specific GraphQL named type with its definition and extensions.

/**
 * Prints a specific GraphQL named type
 * @param type - GraphQL named type to print
 * @returns SDL string for the type
 */
function printType(type: GraphQLNamedType): string;

Usage Example:

import { printType } from "@apollo/subgraph";

const schema = buildSubgraphSchema(/* ... */);
const productType = schema.getType('Product');

if (productType) {
  const typeSDL = printType(productType);
  console.log(typeSDL);
  // Output: type Product @key(fields: "id") { id: ID! name: String! }
}

Print Block String

Formats block strings with proper indentation for GraphQL SDL output, handling multi-line strings and proper escaping.

/**
 * Formats block strings with proper indentation
 * @param value - String value to format
 * @param preferMultipleLines - Force multi-line format
 * @returns Formatted block string with triple quotes
 */
function printBlockString(
  value: string,
  preferMultipleLines?: boolean
): string;

Usage Example:

import { printBlockString } from "@apollo/subgraph";

const description = `
This is a multi-line description
that needs proper formatting
in GraphQL SDL.
`;

const formatted = printBlockString(description, true);
console.log(formatted);
// Output:
// """
// This is a multi-line description
// that needs proper formatting
// in GraphQL SDL.
// """

Integration with Federation

Subgraph SDL Generation

The printing utilities are specifically designed to work with federated schemas:

  1. Federation Directives: Preserves all federation directives (@key, @external, etc.)
  2. Link Directive: Automatically includes federation specification links
  3. Entity Definitions: Properly formats entity types with their federation metadata
  4. Service SDL: Generates SDL suitable for gateway composition

Schema Introspection

Federation gateways use the printed SDL for:

  • Schema Composition: Combining multiple subgraph schemas
  • Query Planning: Understanding entity relationships and field ownership
  • Validation: Ensuring schema compatibility across services

Example Integration:

import { buildSubgraphSchema, printSubgraphSchema } from "@apollo/subgraph";

// Build federated schema
const schema = buildSubgraphSchema([
  {
    typeDefs: gql`
      type Query {
        me: User
      }

      type User @key(fields: "id") {
        id: ID!
        username: String!
        posts: [Post!]! @requires(fields: "username")
      }

      type Post @key(fields: "id") {
        id: ID!
        title: String! @external
        author: User! @provides(fields: "username")
      }
    `,
    resolvers: {
      Query: {
        me: () => ({ id: "1", username: "alice" })
      },
      User: {
        __resolveReference: (user) => ({ ...user, username: "resolved-user" }),
        posts: (user) => [{ id: "1", title: "Hello World", author: user }]
      },
      Post: {
        __resolveReference: (post) => ({ ...post }),
        author: (post) => ({ id: "1", username: "alice" })
      }
    }
  }
]);

// Print for gateway consumption
const sdl = printSubgraphSchema(schema);

// The SDL includes all federation metadata:
// - @link directive for federation spec
// - @key directives for entity identification
// - @requires/@provides for field dependencies
// - Proper type definitions with federation extensions

Output Format

SDL Structure

The printed SDL follows federation conventions:

  1. Schema Extensions: extend schema @link(url: "...")
  2. Federation Directives: Complete directive definitions
  3. Entity Types: Types with federation metadata
  4. Field Directives: @requires, @provides, @external annotations
  5. Custom Directives: User-defined directives preserved

Formatting Rules

  • Consistent Indentation: Proper spacing for readability
  • Directive Ordering: Federation directives first, then custom directives
  • Field Ordering: Maintains original field order from schema
  • Comment Preservation: Retains SDL comments and descriptions

Error Handling

The printing functions are designed to be robust:

  • Invalid Schemas: Gracefully handle malformed schemas
  • Missing Types: Skip undefined or null types
  • Directive Issues: Continue printing even with directive problems
  • Encoding: Handle special characters in field names and descriptions

Error Example:

try {
  const sdl = printSubgraphSchema(schema);
} catch (error) {
  console.error('Failed to print schema:', error.message);
  // Handle printing errors gracefully
}