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
$refvalues; or - a GraphQL schema composed from multiple SDL files with
#importdirectives.
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 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.
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.