Combine API documents

Turn related OpenAPI or GraphQL files into one logical Spec without forcing unrelated APIs into one Project.

A Project owns one logical Spec. That Spec may contain many files, but every operation should belong to one API product consumed, versioned, and released together.

Choose the right shape

What you have	What to do
One OpenAPI entrypoint with external `$ref` files	Point Typeship at the entrypoint. Typeship resolves the graph itself.
Several complete OpenAPI descriptions that form one consumer product	Create and commit one combined entrypoint, then point Typeship at it.
GraphQL SDL split across files	Use whole-document `#import "./file.graphql"` directives from one root SDL file.
Independently consumed APIs with different audiences or release schedules	Create separate Projects. Do not join them to save configuration.

Multi-file OpenAPI

OpenAPI already supports a document graph. Keep a small root file and reference path items or schemas by repository-relative path:

openapi: 3.1.0
info:
  title: Parcel API
  version: 1.0.0
paths:
  /customers:
    $ref: ./paths/customers.yaml
components:
  schemas:
    Customer:
      $ref: ./components/schemas/customer.yaml

Set this root as the Spec entrypoint. Typeship records every resolved source file in the Spec Revision, watches referenced-file-only changes, and reports Diagnostics against the original file coordinates. You do not need to bundle this graph for Typeship.

Repository references must stay inside the connected repository. URL references must stay on the entrypoint's origin.

See Specs for the resolution boundary and Spec compatibility for limits.

Several complete OpenAPI descriptions

Two complete descriptions do not become one API merely because they share a directory. Combine them only when their operations should ship to the same consumers under one compatibility and release policy.

Typeship does not execute repository build commands. Produce one combined OpenAPI document with your own tooling, then commit it or serve it at a stable URL and use it as the Spec entrypoint. Generate it deterministically in CI and fail the build when the committed file drifts from its inputs, so the Spec always matches the descriptions it came from.

Before combining, resolve conflicts in:

paths and operation IDs;
tags and schemas;
security schemes; and
server semantics.

Combining is different from bundling. Bundling follows $ref values from one root, which Typeship already does for you; combining merges several independent root descriptions into one.

Multi-file GraphQL

Typeship composes whole SDL documents with simple import directives:

# schema.graphql
#import "./customers.graphql"
#import "./payments.graphql"

schema {
  query: Query
  mutation: Mutation
}

Each imported file contributes its complete SDL. Named import syntax is not supported, and duplicate or conflicting types fail resolution.

GraphQL endpoint, authentication, environment, scalar, and title settings remain on the Spec.

Keep APIs separate when ownership is separate

Use separate Projects when APIs have distinct consumers, authentication boundaries, version policies, owners, or release schedules. A shared repository does not require a shared Project. Each Project can point at a different entrypoint in that repository.

For AI agents

Inspect the repository before proposing composition. Configure an existing root directly when files are connected by $ref or whole-document GraphQL imports. If several OpenAPI roots form one product, add a deterministic committed join step. Ask the API owner before joining independently consumed APIs.