Schema Overview

Introduction

Polen provides comprehensive schema documentation features. You can work with a single schema or a set of them to capture different versions of your schema across time.

Features that Polen offers based on the schemas you give include automatic reference docs and changelogs.

Supplying Your Schema

You can provide your GraphQL schema to Polen in various ways ranging from convention to configuraiton.

File Convention

You can have a single schema.graphql SDL file in your project directory. This works for simple projects but won't support versioning.

schema.graphql

Directory Convention

You can have your schema under a schema directory in your project root. This opens you up to versioning (discussed later).

schema/
  schema.graphql

Configuration

You can use configuration if you wish, supplying a schema inline even. Refer to extensive JSDoc on configuration properties for details.

import { Polen } from 'polen'

export default Polen.defineConfig({
  schema: {
    useDataSources: 'memory',
    dataSources: {
      memory: {
        versions: [
          {
            date: new Date('2023-01-15'),
            value: `
              type Query {
                users: [User]
              }
              type User {
                id: ID!
                name: String!
              }
            `,
          },
        ],
      },
    },
  },
})

Introspection File Convention

If you have a schema.introspection.json file in your project root, Polen will automatically use it as a schema source. This file should contain a standard GraphQL introspection query result.

This enables interoperability: Any tool that produces a valid GraphQL introspection JSON file will work with Polen:

• GraphQL Codegen
• Apollo CLI
• Custom scripts
• CI/CD pipelines

schema.introspection.json  # Polen automatically detects this

Automatic Introspection

Polen can also fetch and cache introspection results for you if you configure it. For example:

import { Polen } from 'polen'

export default Polen.defineConfig({
  schema: {
    dataSources: {
      introspection: {
        url: 'https://api.example.com/graphql',
        headers: {
          'Authorization': `Bearer ${process.env.API_TOKEN}`,
        },
      },
    },
  },
})

Lifecycle Details

• If there is a schema.introspection.json file then Polen will not run introspection.
• If there is no file present then Polen will perform introspection and create schema.introspection.json
• So, delete this file to have new introspection.
• Note: When running the dev server, Polen watches for changes to schema.introspection.json. If you delete the file, Polen will automatically fetch a fresh schema from your endpoint.

Query details

• Polen uses Graffle's introspection extension which performs the standard GraphQL introspection query
• Fetches complete schema information: all types, fields, descriptions, deprecations, directives, etc.
• Currently no configuration options for customizing the introspection query
• The schema.introspection.json file contains the raw introspection query result in standard GraphQL format
• The file format is validated when read - invalid JSON or introspection data will produce clear error messages

Precedence

When multiple schema sources are available, Polen uses the following precedence order:

1. Data - Pre-built schema objects (if configured)
2. Directory Convention - schema/ directory with versioned SDL files
3. File Convention - Single schema.graphql file
4. Memory - Inline schemas in configuration
5. Introspection - GraphQL endpoint introspection

You can override this default order using the useDataSources configuration:

schema: {
  // Try introspection first, fall back to file
  useDataSources: ['introspection', 'file'],
  dataSources: {
    introspection: { url: 'https://api.example.com/graphql' },
    file: { path: './fallback-schema.graphql' }
  }
}

Versioning

Polen supports documenting different versions of your schema.

Specifier Kinds

Each schema needs a version identifier, just like package releases on npm. Polen supports different specifier kinds to accommodate various versioning strategies.

Important: All schemas in your project must use the same specifier kind.

Date

Polen supports date-based versions in ISO 8601 format:

• Format: YYYY-MM-DD
• Examples: 2024-01-15, 2023-12-31, 2024-03-20
• Behavior: Shows the schema version from that specific date

Future

Future Support

Additional version formats like semantic versioning (semver) may be supported in future releases. Share your feedback on what version formats would be most valuable for your use case.

Supplying Your Versioned Schema

Here's how supplying multiple schemas maps to the different sources:

Source Type	How Multiple Schemas Are Provided	Examples
File	N/A (single schema only)	N/A
Directory	Place multiple SDL files in schema/ directory with each version as the file name	schema/ ├── 2024-01-15.graphql └── 2024-03-20.graphql
Configuration	Define multiple versions in dataSources.memory.versions array	See example above

Features Enabled

Polen provides the following schema-related features:

Feature	Single Schema	Multiple Schemas
Reference	Basic type and field documentation	Versioned URLs for historical schema access
Changelog	N/A	Automatically generated changelog showing schema evolution

Current Limitations

• Introspection only supports single schemas (no versioning/changelog support)
• Version navigation in the reference docs requires manual URL construction
• Changelog doesn't include clickable links to versioned reference pages