A monograph is a graph with GraphQL Federation turned off, limited to a single subgraph. When you create a monograph, Cosmo creates that subgraph internally. You interact only with the monograph. It is not a federated graph with one subgraph: federation is off until you migrate.

What happens to schema contracts when I migrate?

Migrating a monograph into a federated graph migrates all connected schema contracts.

Can I use Schema Contracts with a monograph?

Yes. Monograph schemas can use `@tag` directives, and Schema Contracts can filter the schema for different audiences. Each contract has its own router deployment.

What do I need to use a monograph?

You need a GraphQL server accessible from the router, router deployment infrastructure, and a wgc API key with access to the graph.

Monograph Support | Cosmo by WunderGraph

Q: What platform features are available for monographs?

Monographs support Cosmo platform features including schema registry, schema checks, analytics, Studio, contracts, and Cosmo Router integration. You get these capabilities without configuring federation.

The problem

Why single-service GraphQL teams often end up under-tooled

Not every GraphQL deployment needs federation from day one. Without monograph support, a single-service team chooses between adopting federation early or using basic tooling now and migrating later.

Federation overhead before you need it

A team with one GraphQL service does not need federation yet. Cosmo does not require federation configuration for it, so the team avoids federation complexity until it needs multiple services.

Basic tooling now, harder migration later

Use basic tooling now and migrate when the time comes, or adopt federation complexity before it is needed. Both choices create tradeoffs for teams that only need one GraphQL service today.

No schema registry for simple APIs

Teams with simple GraphQL APIs often still need professional schema management, checks, analytics, and contracts. A monograph gives one service those features without federation.

Our solution

A first-class path for single-service GraphQL

Cosmo’s monograph support provides a first-class experience for single-service GraphQL APIs. Create a monograph, publish your schema, and access schema registry, checks, analytics, contracts, Studio, and Router without configuring federation. When you are ready to split into multiple services, one CLI command migrates the monograph to a federated graph, along with its connected schema contracts.

How it works end to end

Create a monograph with `wgc monograph create production --routing-url ... --graph-url ...`. The routing URL is where clients connect; the graph URL is your GraphQL server.
Publish your schema with `wgc monograph publish production --schema ./schema.graphql`. Cosmo registers it and makes it available in Studio for schema management and analytics.
Access Cosmo platform features like schema registry, Studio, analytics, checks, and contracts.
Run `wgc monograph check production --schema ./schema.graphql` in CI before every deploy to catch breaking changes and composition errors, plus lint issues if the namespace has a lint policy enabled.
When your architecture grows, run `wgc monograph migrate production` to convert to a federated graph. Connected schema contracts are migrated with it. Update the label matchers and labels afterwards so new subgraphs compose with it.

Start simple. Scale to federation when you are ready.

Monograph support

Before & After

Before Cosmo	With Cosmo
Limited tooling for non-federated GraphQL	Full platform features for monographs
Painful migration to federation later	Single-command migration when ready
No schema registry for simple APIs	Complete schema management
Basic analytics only	Full analytics and observability

Under the hood

What a monograph is

One internal subgraph: federation is off, and Cosmo manages the single subgraph for you. You interact only with the monograph.
Routing URL — where clients connect to the Cosmo Router.
Graph URL — your actual GraphQL server endpoint. The router proxies requests there.
Migration to federation: running `wgc monograph migrate production` converts the monograph to a federated graph. Update its label matchers and labels afterwards so new subgraphs compose with it.

Key benefits

Professional tooling from day one

Available on every Cosmo plan, including the free Developer plan and self-hosted. Monographs count toward each plan’s graph limit.

Zero federation overhead

Deploy a single-service GraphQL API without federation complexity or configuring federation. Cosmo automatically manages the internal subgraph so you interact only with the monograph.

Full platform access

Schema registry, schema checks, analytics, Studio, contracts, and Cosmo Router integration are available for monographs without needing a federated graph from day one.

One-command migration to federation

Run `wgc monograph migrate production` to convert the monograph into a federated graph. Migration gives the graph and its subgraph new, unique labels, so nothing recomposes until you update the label matchers and labels to bring in new subgraphs.

Contract support for single-service APIs

Use `@tag` directives in your schema and create filtered contracts for different audiences, including internal and external consumers, before you add a second service.

A path to federation from day one

Start with one service and a clear path to federation. When you migrate, connected schema contracts are migrated with the graph.

How monograph support works

01

One command to get started.

Create the monograph

Run `wgc monograph create production --routing-url ... --graph-url ...`. Cosmo creates the graph and its managed subgraph internally. You interact only with the monograph.

02

Schema registered on publish.

Publish your schema

Run `wgc monograph publish production --schema ./schema.graphql`. Cosmo publishes the schema to the monograph and makes it available in Studio.

03

No federation configuration required.

Use Cosmo platform features

Use Cosmo platform features like Studio, schema registry, analytics, checks, and contracts without configuring federation.

04

Catch issues before deploy.

Validate in CI

Add `wgc monograph check production --schema ./schema.graphql` to your CI pipeline. Breaking changes and composition errors are caught before they reach production, plus lint issues if a lint policy is enabled.

05

One command to federate.

Migrate when ready

Run `wgc monograph migrate production` to convert the monograph into a federated graph. Migration gives the graph and its subgraph new, unique labels, so nothing recomposes until you update the label matchers and labels to bring in new subgraphs.

Use cases

When teams use monograph support

Quick API deployment

Quick start

A team wants professional schema management for a single GraphQL service. Create a monograph with `wgc monograph create production --routing-url ... --graph-url ...`, publish the schema, and use Studio for schema management and analytics without configuring federation.

API with multiple audiences

Contracts

A single GraphQL service needs to expose different schemas to internal and external consumers. Add `@tag` directives to the monograph schema, create contracts for each audience, and deploy a router per contract.

Migration to federation

Growth

A growing application needs to split into multiple services. Run `wgc monograph migrate production` to convert the monograph into a federated graph. Migration gives the graph and its subgraph new, unique labels, so nothing recomposes until you update the label matchers and labels to bring in new subgraphs.

Schema validation in CI

CI/CD

A team wants to catch breaking changes before every deploy. Add `wgc monograph check production --schema ./schema.graphql` to the CI pipeline. Breaking changes and composition errors are reported before production, plus lint issues if a lint policy is enabled.

When to use a monograph

When to use

You have one GraphQL service and want professional schema management without federation complexity.
You need schema checks, analytics, or contracts before you have multiple services.
You expect to grow to multiple services and want a clear migration path.

Requirements

A GraphQL server accessible from the Cosmo Router.
Router deployment infrastructure.
A wgc API key with access to the graph.

Start with one service. Scale when you are ready.

Monograph support is available on every Cosmo plan, including the free Developer plan and self-hosted.

Start Free See the docs

Cosmo platform features for a single GraphQL service