---
title: "Definitions"
description: "The complete API contract Typeship resolves, versions, diagnoses, and gives to every Target."
url: https://typeship.dev/docs/projects/definitions
markdown: https://typeship.dev/docs/projects/definitions.md
section: "Get started"
---
> ## Documentation index
> Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt.
> Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page.

# Definitions

The complete API contract Typeship resolves, versions, diagnoses, and gives to every Target.

A **Definition** is the API contract owned by a Project. It is the one immutable input shared by Diagnostics, compatibility review, CLI, MCP, SDKs, previews, and releases.

A Definition can be:

* one OpenAPI or Swagger document;
* one GraphQL schema;
* a resolved graph of OpenAPI documents connected by repository-relative `$ref` values; or
* a GraphQL schema composed from multiple SDL files with `#import` directives.

Use separate Projects for independently consumed APIs. Multiple files that describe one API belong to one Definition; unrelated APIs do not.

See [Combine API documents](https://typeship.dev/docs/guides/combine-api-specs) when you have several OpenAPI roots or need to decide whether files belong in one Definition.

## Sources

A Definition has one entrypoint, either a URL or a file in a GitHub repository. A URL source may carry write-only fetch credentials. A repository source uses the Typeship GitHub App and can participate in source pull-request review.

OpenAPI references may stay split across repository files. URL references must remain on the entrypoint's origin and use the configured source credentials.

Before accepting the graph, Typeship limits redirects, reference depth, cycles, document count, and total bytes. It never executes customer code to produce a Definition.

GraphQL receives an equivalent native path: SDL files are composed and hashed as GraphQL, not converted to OpenAPI. Endpoint, authentication, environment, title, and scalar settings live on the Definition because the schema itself cannot express them.

## Definition Revisions

Every changed observation creates an immutable **Definition Revision** (`drev_*`). It records the resolved graph and each source document's coordinate, digest, size, and role.

The graph hash covers every document. Changing only a referenced file therefore creates a revision and triggers preview generation.

Repeated observations of the same current graph reuse the current revision. A later A → B → A revert records a new observation, so history remains truthful.

The Console shows a file tree only when a Definition actually has multiple documents. The revision API can retrieve the canonical resolved content or the exact raw content of an individual source document.

## One input everywhere

Typeship does not resolve the source separately for different features. Preflight, Diagnostics, patches, compatibility checks, and every Target consume the same resolved revision. This prevents a green review from describing different bytes than the generated package.

Free projects retain and diagnose the complete Definition. The Free cap applies when each Target is generated: the first 25 operations are included and the response states how many were omitted.

> **For AI agents:** Retrieve the Definition from the Project's `definition_id`. Use `definitions retrieve`, `definitions update`, `definition-revisions list`, and `definition-revisions retrieve-content`. Address individual source files by `document_id`. Public v1 uses `definition`, `definition_revision`, and `document` IDs.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)